pi-agent-browser-native 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.9.3 - 2026-10-05
+
+### Fixed
+
+- Avoid repeated JSON parsing exceptions for the exact redaction marker and ordinary text that cannot begin JSON, and skip redacting a discarded ref copy in browser-code results. Preserve native grammar validation, secret masking, complete output/spill content, retained snapshot/replay state and direct failure receipts.
+- Run offline native discovery pipeline contracts automatically when the host exports its public instruction-groups factory; retain the explicit force-on diagnostic.
+
+- Verify the current complete URL before one-use approved-capture actions in wrapper-owned managed sessions, preserving path/hash drift refusal and unchanged-page success.
+- Preserve exact tab-creation confirmation decisions and visible conditional navigation guidance from narrowly validated transport metadata, without automatically executing continuation arguments.
+
+- Complete semantic role click/check/fill and unique accessible select after snapshot approval by reusing only the eligible next-call capture. Render pending snapshots as native confirmation controls rather than empty pages.
+
+- Keep the established native confirmation policy across same-session helpers, exact confirm/deny follow-ups, code/advanced calls and resume, without changing caller argv or native first-command precedence. Pending navigation, including native batch rows, never becomes an observed target; completed compound confirmations reconcile their actual target before follow-ups. Replacement cleanup retains the old identity's selected string and continuity state until successful close; native unset still uses native defaults. Exact native guarded-control markers avoid helper-slot replacement without command replay or native ID-validation claims. Completed click/tab/close effects and inner failures reconcile normally; cold pending helpers expose the exact decision before getters dispatch. Electron host helpers retain the setting, and definite unestablished requests no longer overwrite it.
+
 ## 0.9.2 - 2026-10-04
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ It is for Pi users who want agents to browse sites, inspect pages, click through
 
 ## Pi release qualification
 
-Development host dependencies are pinned to official Pi **1.0.0**, with wildcard runtime peers. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. It does not substitute a fork SDK while leaving official types or child CLI installed.
+CI qualifies the latest stable official Pi and latest maintained fork `main`, resolving their version/commit once per run and retaining SDK/CLI identity evidence. Locked development dependencies are reproducible build snapshots, not qualification targets; runtime peers remain wildcard. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. It does not substitute a fork SDK while leaving official types or child CLI installed.
 
 Run in an empty HOME with a **short** TMPDIR outside your real home. Long temporary paths can exceed macOS's 103-byte Unix socket limit; keep the fixture's socket safety checks intact. Native lifecycle controls, live upstream help sampling, lifecycle dogfood, and platform qualification remain the separate gates documented below. A Pi-only compatibility run uses no live browser profiles, credentials, or agent-browser fork, and does not certify those external integrations.
 
@@ -90,7 +90,7 @@ The result is optimized for agent work:
 | Stateful cookies/storage/auth output bloats or leaks context | Presentation layer redacts `details.data` for cookies and credential-like storage values while keeping low-risk local QA values such as `theme: dark` readable; recursively scrubs other structured upstream JSON (network, diff, trace/profiler, stream, dashboard, chat, auth, dialog, frame, state, and similar) using sensitive key names plus string heuristics; masks sensitive argv flags and positionals, including raw batch rows and ordered code journals; scrubs secrets from failed batch step errors; and exposes a compact redacted `batch` matrix on top-level `details.data` | `extensions/agent-browser/lib/results/presentation.ts`, `extensions/agent-browser/lib/results/presentation/diagnostics.ts`, `extensions/agent-browser/lib/runtime.ts`, `test/agent-browser.presentation-diagnostics.test.ts` |
 | Stale `@eN` refs fail mysteriously | Defines full per-session refs once in the native journal, exposes them on dedicated captures, rejects mismatched URLs / unknown refs / unsafe `batch` stdin ordering before spawn, adds recovery guidance to rerun `snapshot -i` or use stable `find` locators | `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/session-page-state.ts`, `test/agent-browser.session-page-state.test.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.extension-semantic-recovery.test.ts` |
 | Agents need stable success/failure buckets | Exposes bounded `resultCategory`, `successCategory`, and `failureCategory` on tool `details` for branching without parsing prose; final results return native `isError` and a visible prose failure notice while preserving parseable caller-requested `--json` output. Native structured results expose the same bounded, redacted observations, not internal replay metadata | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/results/categories.ts`, `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/pi-tool-rendering.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.pi-pipeline.test.ts` |
-| Clicks can report success without the page receiving the event | Top-level non-Electron direct `click` calls on `xpath=` targets or role-gated current `@e…` refs (`button`, `checkbox`, `menuitem`, `radio`, `switch`, `tab`) install a bounded target-specific DOM-event probe; eligible `@e…` refs require a unique role/name in both the latest snapshot and the live candidates. A per-probe temporary DOM marker must be read back by native `get attr <original-selector> <marker>` before the candidate can verify dispatch, including XPath scope. Missing or mismatched identity cleans up the probe and leaves the native click unverified, not failed. Duplicate-name refs pass through without a probe: their old ordinal cannot prove which element received the click. If upstream reports success but no trusted event reaches the resolved target, the wrapper fails the tool, exposes `details.clickDispatch`, and suggests explicit retry/inspect next actions (no in-page replay), including a nested-scroll `scrollintoview` action when the probe sees the target outside a scroll container or viewport. Unresolved locator clicks such as raw `find … click` are left upstream-owned to avoid false failures for frame-scoped targets. Other click results still expose `details.pageChangeSummary`; `observed: false` explicitly marks dispatch-only mutation summaries and adds a visible `Action dispatched; application change unverified` warning. Unchanged-URL clicks can surface evidence-backed `details.overlayBlockers` candidates. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts`, `extensions/agent-browser/lib/results/presentation/navigation.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-click-dispatch.test.ts` |
+| Clicks can report success without the page receiving the event | Top-level non-Electron direct `click` calls on `xpath=` targets or role-gated current `@e…` refs (`button`, `checkbox`, `menuitem`, `radio`, `switch`, `tab`) install a bounded target-specific DOM-event probe; eligible `@e…` refs require a unique role/name in both the latest snapshot and the live candidates. A per-probe temporary DOM marker must be read back by native `get attr <original-selector> <marker>` before the candidate can verify dispatch, including XPath scope. Missing or mismatched identity cleans up the probe and leaves the native click unverified, not failed. Normal collection cancels the probe timer; if a pending native decision blocks cleanup, listeners and the window marker self-expire after this call's process-timeout budget plus the existing two-second cleanup grace, without another browser command. Duplicate-name refs pass through without a probe: their old ordinal cannot prove which element received the click. If upstream reports success but no trusted event reaches the resolved target, the wrapper fails the tool, exposes `details.clickDispatch`, and suggests explicit retry/inspect next actions (no in-page replay), including a nested-scroll `scrollintoview` action when the probe sees the target outside a scroll container or viewport. Unresolved locator clicks such as raw `find … click` are left upstream-owned to avoid false failures for frame-scoped targets. Other click results still expose `details.pageChangeSummary`; `observed: false` explicitly marks dispatch-only mutation summaries and adds a visible `Action dispatched; application change unverified` warning. Unchanged-URL clicks can surface evidence-backed `details.overlayBlockers` candidates. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts`, `extensions/agent-browser/lib/results/presentation/navigation.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-click-dispatch.test.ts` |
 | Dashboard scroll commands can look successful while nothing moves | Handles standard `scroll <dir> [px]` against the document first (including pages whose smooth-scroll CSS defeats upstream wheel timing), falls back upstream when the document cannot move, and samples viewport/containers around the fallback; explicit CSS-container scrolling uses instant movement so smooth-scroll CSS cannot cause a premature no-movement failure; unchanged positions fail as `upstream-error` with `details.scrollNoop`, visible recovery guidance, and exact snapshot/screenshot checks. Unsupported `scrollintoview text=...` fails before dispatch, including inside effective batch rows, and shows exact native `find text ... hover` and snapshot/ref recovery payloads; help remains native pass-through. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `test/agent-browser.extension-validation.test.ts` |
 | Dropdown/combobox clicks can focus or hit native option box-model errors | Adds first-class `select <selector> <value...>` paths through native `args` and `agent_browser_action`; semantic role/name or label select resolves exactly one current visible combobox/listbox ref before action. Custom combobox clicks still detect focused controls with explicit `aria-expanded` state but no visible options and return `details.comboboxFocus` plus exact recovery `nextActions` | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `extensions/agent-browser/lib/input-modes/semantic-action.ts`, `test/agent-browser.extension-input-modes.test.ts`, `test/agent-browser.extension-validation.test.ts` |
 | Recording workflows fail late when `ffmpeg` is missing or report stale lifecycle state | After successful `record start` / `record restart`, reports `successCategory: "artifact-pending"`, returns an exact `stop-pending-recording` action, warns when older natives report pending output without `ffmpeg`, and conservatively invalidates prior page-scoped `@e…` refs on every executed start attempt and URL-bearing restart to protect older supported natives. This is not evidence of a page change: 0.37 records the active page unless a URL is supplied; FPS-only calls keep the intended tab; an unbounded transcript-backed namespace/session index reserves active destinations across aliases, serializes artifact lifecycle and explicit wait/output writes, persists cross-branch close tombstones, retires every successful close path (including every matching namespace owner for `close --all`), rejects missing/stale restart output, coalesces terminal batch state, keeps only the newest pending path per identity, rejects recording starts after a nested close, folds Unicode path aliases, and retains exact cleanup actions with visible guidance on any later same-session failure | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#diff-debug-and-streaming), `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.presentation-artifacts-batch.test.ts` |
@@ -103,7 +103,7 @@ Artifact results show known requested paths separately from reported/resolved lo
 
 ## Fastest way to try it
 
-Use Node 24.21.0 or newer and Pi 1.0.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, pins its direct Pi validation dependencies to 1.0.0, and makes Pi hosts below 1.0.0 a setup failure through `pi-agent-browser-doctor`. There are no compatibility shims for older Pi releases.
+Use Node 24.21.0 or newer and Pi 1.0.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, retains a locked Pi development snapshot while qualifying the latest official/fork graphs, and makes Pi hosts below 1.0.0 a setup failure through `pi-agent-browser-doctor`. There are no compatibility shims for older Pi releases.
 
 Install upstream `agent-browser` first and make sure it is on `PATH`:
 
@@ -327,7 +327,7 @@ Profile hints with `authenticated-only` remain advisory. Global/override profile
 
 You usually prompt the agent in natural language. These JSON snippets show the exact native tool shape the agent should use.
 
-Open a page and inspect it (first-call recipe: open → snapshot -i → interact with current `@refs` → snapshot -i after changes). Omit `--json` unless you need JSON text; structured details are always available.
+Open a page and inspect it (first-call recipe: open → snapshot -i → interact with current `@refs` → snapshot -i after changes). Omit `--json` unless you need JSON text; structured details are available by default. Explicit `--json false` selects native text without trusted row, confirmation, lifecycle, page-target or artifact receipts; see [the output contract](docs/TOOL_CONTRACT.md#wrapper-json).
 
 ```json
 { "args": ["open", "https://example.com"] }
@@ -427,6 +427,8 @@ Evaluate page JavaScript through stdin. Put the script in the top-level `stdin`
 { "args": ["eval", "--stdin"], "stdin": "({ title: document.title, url: location.href })", "outputPath": "logs/page-state.json" }
 ```
 
+Native text cookie reads redact `name=value` values, including empty cookie names; storage reads redact `key: value`, including empty and colon-containing keys, using the same benign-value policy as JSON. Standalone `storage local|session get <key>` and native shorthand `storage local|session <key>` protect the entire sensitive value, including embedded newlines, even when invocation display redaction changes the supplied key. Names and benign preferences remain visible in content, details, spills and exports. Native all-entry storage and raw batches do not escape multiline values, so text redaction is heuristic: use structured JSON when sensitive storage must be unambiguous.
+
 Use `outputPath` when `eval`, `get`, `snapshot`, or another extraction should be saved as a durable workspace file. Recording results also export on failure or timeout: their JSON envelope retains the failed attempt, native receipt, verification and any recovery evidence rather than writing misleading bare success data. Keep it distinct from screenshot, download, recording, and other browser artifact destinations; preflight rejects known same-call aliases before browser activity, and the result writer preserves the browser artifact if an alias becomes apparent only afterward. The wrapper writes `details.data` when present, otherwise the model-facing text content. When presentation compacted a large direct result, a result row, or the whole `batch`, it instead reads the full command-redacted pre-compaction payload only from the corresponding live wrapper-managed spill recorded in `details.artifactManifest`; if any required spill is unavailable or untrusted, the call fails without writing compact metadata to the requested path. `details.outputFile` reports the saved path and byte count. Explicit upstream `--json` content stays parseable, including early snapshot/network filters, scroll results, and preparation failures; metadata stays in `details` and the save notice lives only in `details.outputFile`. Help/version output remains native text.
 
 Recording receipts separate captured-frame rate and wall-clock capture duration from nominal/output FPS. `details.artifacts[].recording` includes native capture timestamps, received frame counts (not pixel-unique frames), encoded/written/held/dropped/skipped counts, and output duration. Missing native metrics stay unknown. Repeated, static, sparse or final-state-only frames cannot establish UI smoothness.
@@ -561,7 +563,9 @@ Each automatic root has its own stable native restore key. Native save/restore p
 
 Explicit native `session` defaults (config or `AGENT_BROWSER_SESSION`) still override automatic root selection, including `sessionMode: "fresh"`. They intentionally share whichever browser the caller selected. Per-call session/namespace flags retain precedence. Ordinary launch options such as `--profile` or `--executable-path` still use the root-group name. Repeat explicit options when deliberately relaunching a persistent per-root profile after close. Explicit `fresh` and attachment choices retain their existing managed-session lifecycle; later auto calls follow that selected managed session. Use `session info` with the reported `sessionName` for read-only native daemon/browser evidence. Unknown native fields remain unknown.
 
-Policy-required URL reads keep the two-call read → confirm/deny flow. Returned actions name the actual native namespace/session, including `default`; routing survives transcript resume and branch changes. Only explicit-read provenance plus native `capabilities.readRequiresConfirmation: true` permits matching confirm/deny without page helpers. This capability includes native confirmation-ID checking. Legacy prompts retain correct routing but normal page checks; DOM or content-shaped prompts never receive the exemption.
+Set `--confirm-actions` on the session's first command. Its established setting follows same-namespace/session helpers and ordinary, code, advanced and resumed calls, so exact returned confirm/deny actions work without repeating the policy. Bare follow-ups retain a selected string, including explicit `""`, over ambient environment or discovered-config changes. Native unset is not retained and keeps ordinary native default resolution. A new explicit `--confirm-actions` or `--config` selection uses native argv → environment → config precedence and can restart the daemon, losing pending confirmations. Successful close retires the setting. Replacement cleanup uses the old identity's setting and retains its continuity state if close fails or needs confirmation. Electron launch and host helpers use the same selected setting. Definite pre-dispatch, native CLI parse/config and local-inspection rejections do not replace an established setting unless an earlier browser helper admitted it; interrupted work retains its selected intent.
+
+Native confirmation controls retain their exact ID, namespace/session and compact command/action provenance in the existing transcript state. Use the exact returned confirm/deny action: matching guarded decisions skip page helpers that could overwrite the native pending slot, then reconcile the completed browser action normally. In native batch, that helper suppression applies only to a matching first effective decision; raw arguments win over stdin and later page/ref checks remain. This does not prove native ID validation or make the action browser-independent. Page content cannot create this provenance. A pending `tab_new` transport may retain paired `after_confirmation: ["open", <requested URL>]` and nonempty `guidance` only when the continuation matches the original tab URL. Its conditional guidance stays visible: approve to create the blank/labeled tab, then explicitly navigate that new tab; denial never authorizes the continuation. The extension does not execute these arguments automatically. Completed confirmed full snapshots install their refs, including in batch row order. A final confirmed capture can supply the next same-identity call's freshness sample once, including semantic role click/check/fill and unique role/label select resolution; intervening calls or later rows consume that opportunity. Pending snapshots render a confirmation control, not an empty page. Target/membership/invalidation and native-generation checks still apply. On this one use, live verification compares the complete capture URL, including fragments, and rejects refs when it changes—including wrapper-owned managed sessions and warm sessions without resume. Ordinary ref/tab URL comparisons remain fragment-insensitive. Only a DOM-only rename on the same page after that sample is not resampled on this one use. Further ref operations use the normal freshness check. Policy-required explicit URL reads keep their separate two-call flow; only `capabilities.readRequiresConfirmation: true` grants browser-independent confirmation with native ID checking. Legacy URL-read prompts retain correct routing but normal page checks. A pending cold-reopen helper exposes its decision without dispatching the requested getter or replaying the original open.
 
 Full live identity, browser-independent native reads/confirmations and detailed recording receipts require the companion upstream fixes; the current recommended release does not yet supply all of them. Older supported versions remain accepted with unavailable evidence marked unknown. The extension does not upgrade or restart your installed browser to obtain these fields.
 
@@ -737,6 +741,14 @@ The upstream browser engine remains [`agent-browser`](https://agent-browser.dev/
 - Real authenticated profile use is powerful but sensitive. Treat profile and cookie access as user-approved, task-specific behavior.
 - Wrapper tab/session recovery is best effort around observed upstream behavior, not a replacement for explicit profile/session design.
 
+## Automatic npm releases (maintainers)
+
+Follow the [shared release procedure](https://github.com/fitchmultz/.github#automatic-npm-releases): merge a reviewed PR into `main` with an intentional `package.json` version bump and a matching versioned `CHANGELOG.md` section. Automation never bumps versions, overwrites releases, or republishes an existing version. Once configured and enabled, it runs existing compatibility and native lifecycle checks, qualifies one candidate tarball, then waits for `fitchmultz` approval in the `npm` environment.
+
+Approve only after checking the exact source commit, version, downloaded candidate tarball and summary against [the existing release gates](docs/RELEASE.md#pre-release-checks), including required lifecycle/live-site evidence, artifact checks and all three final reviewer approvals. Apply the documented Windows waiver without claiming a Windows or full composed-gate pass. Approval attests genuine satisfaction of those requirements; it does not create proof. Authenticated, model-backed and paid checks stay outside CI. Automated publication disables npm hooks to publish the already checked bytes; the manual publisher instructions and their gates remain valid.
+
+Failed/unpublished candidates can retry daily at 12:17 UTC or via manual dispatch of `npm release` on `main`, without another bump. Set repository variable `NPM_RELEASE_ENABLED` to anything other than `true` to stop new release plans; cancel pending runs separately when needed. Workflow validation is not evidence of a completed real OIDC publication.
+
 ## Local development
 
 Install upstream `agent-browser`, then install dependencies:
@@ -745,7 +757,7 @@ Install upstream `agent-browser`, then install dependencies:
 npm install
 ```
 
-Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` (for example `npx -y npm@12.2.0 install`) so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 1.0.0 or newer for lifecycle and interactive browser smokes; the pinned Pi 1.0.0 devDependencies are validation fixtures, not an exact-version requirement for the host CLI. See [Environment and automation pitfalls](docs/RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
+Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` (for example `npx -y npm@12.2.0 install`) so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 1.0.0 or newer for lifecycle and interactive browser smokes; locked Pi devDependencies are reproducible build snapshots, not qualification targets. CI selects the once-resolved latest official graph for native lifecycle and package smoke, and independently qualifies the latest maintained fork. See [Environment and automation pitfalls](docs/RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
 
 Checkout-only extension smoke test:
 

package/dist/extensions/agent-browser/index.js

@@ -9,7 +9,7 @@ import { SessionPageState } from "./lib/session-page-state.js";
 import { appendBrowserTransition, applyArtifactChanges, artifactChanges, browserStateEffects, getBrowserRecord, getBrowserResultMessage, pageChange, snapshotDefinition } from "./lib/browser-transcript.js";
 import { appendBrowserRecord, captureBrowserBranch, hasPublishedBrowserJournal, readBrowserEntries, requirePublishedBrowserJournal } from "./lib/browser-journal.js";
 import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactInvocationArgs, redactSensitiveText, redactSensitiveValue, isPlainTextInspectionArgs, } from "./lib/runtime.js";
-import { deleteIdentityKeysInNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences } from "./lib/argv-grammar.js";
+import { isBooleanFlagEnabled, deleteIdentityKeysInNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences } from "./lib/argv-grammar.js";
 import { parseArgvDescriptor } from "./lib/argv-descriptor.js";
 import { needsManagedSession } from "./lib/command-policy.js";
 import { ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
@@ -43,7 +43,7 @@ import { appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, apply
 import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "./lib/config.js";
 import { appendRecordingReservationTransition, applyRecordingArtifactsToReservations, restoreRecordingReservationStateFromBranch, retireRecordingReservation, } from "./lib/recording-reservations.js";
 import { createAgentBrowserWebSearchTool } from "./lib/web-search.js";
-import { scopeReadConfirmationArgs } from "./lib/read-confirmation.js";
+import { isSuccessfulNativeConfirmedClose, scopeReadConfirmationArgs } from "./lib/read-confirmation.js";
 import { isDirectAgentBrowserBashAllowed, isHarmlessAgentBrowserInspectionCommand, looksLikeDirectAgentBrowserBash, } from "./lib/bash-guard.js";
 import { AgentBrowserResultComponent, formatAgentBrowserRenderCall, } from "./lib/pi-tool-rendering.js";
 function browserExecutionFailure(error, signal, fallbackCategory = "upstream-error") {
@@ -113,6 +113,8 @@ function getArtifactPreflightValidationError(options) {
     const artifactDestinations = new Map();
     let sawBatchClose = false;
     for (const [index, commandStep] of steps.entries()) {
+        if (commandStep.length === 0)
+            continue; // Native skips empty stdin rows.
         if (batch) {
             const stepValidationError = validateToolArgs(commandStep, { batchStep: true });
             if (stepValidationError)
@@ -288,7 +290,7 @@ function restoreAttachedSessionKeysFromBranch(branch) {
         if (!sessionName)
             continue;
         const sessionKey = getSessionContextKey(sessionName, namespace) ?? sessionName;
-        if ((succeeded && isCloseCommand(extractUpstreamCommandTokens(args)[0])) || terminalBatchClose)
+        if ((succeeded && (isCloseCommand(typeof details.command === "string" ? details.command : extractUpstreamCommandTokens(args)[0]) || isSuccessfulNativeConfirmedClose(extractUpstreamCommandTokens(args), details.data))) || terminalBatchClose)
             attachedSessionKeys.delete(sessionKey);
         else if (details.attachedBrowserSession === true || isAttachedBrowserInvocation(args, {}))
             attachedSessionKeys.add(sessionKey);
@@ -563,10 +565,11 @@ function collectBranchManagedResourceEvents(branch) {
             const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined, replacedSessionNamespace), eventRank);
         }
-        if (succeeded && !isCloseCommand(command) && sessionName && ((!explicitSessionName && (usedImplicitSession || sessionMode === "fresh")) || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
+        const closesSession = isCloseCommand(command) || isSuccessfulNativeConfirmedClose(extractUpstreamCommandTokens(getToolResultArgs(details)), details.data);
+        if (succeeded && !closesSession && sessionName && ((!explicitSessionName && (usedImplicitSession || sessionMode === "fresh")) || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
             setBranchManagedSessionActive(events, sessionName, namespace, eventRank);
         }
-        if (succeeded && isCloseCommand(command)) {
+        if (succeeded && closesSession) {
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(explicitSessionName ?? sessionName ?? outcomeAttemptedSessionName ?? outcomeCurrentSessionName, namespace), eventRank);
         }
         if (closeAllApplied) {
@@ -618,12 +621,12 @@ function syncElectronCleanupManagedSessions(sessions, cleanupResults, fallbackNa
         untrackOwnedManagedSession(sessions, identity.sessionName, identity.namespace);
     }
 }
-async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessionName, timeoutMs, attachedSessionKeys, keepNamespace, onClosed) {
+async function closeOwnedManagedSessionsExcept(sessions, restoreState, sessionPageState, keepSessionName, timeoutMs, attachedSessionKeys, keepNamespace, onClosed) {
     const keepKey = getSessionContextKey(keepSessionName, keepNamespace);
     for (const [key, owner] of [...sessions]) {
         if (key === keepKey)
             continue;
-        const error = await closeManagedSession({ cwd: owner.cwd, headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, socketDir: owner.socketDir, timeoutMs });
+        const error = await closeManagedSession({ confirmActions: sessionPageState.get(key).confirmActions ?? process.env.AGENT_BROWSER_CONFIRM_ACTIONS, cwd: owner.cwd, headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, socketDir: owner.socketDir, timeoutMs });
         if (!error) {
             sessions.delete(key);
             onClosed?.(owner);
@@ -943,6 +946,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
     };
     const closeScriptSessionLeaseWithinQueue = async (sessionName, cwd) => {
         const closeError = await withIsolatedAgentBrowserEnvironment(() => closeManagedSession({
+            confirmActions: sessionPageState.get(getAgentBrowserSessionIdentityKey(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE)).confirmActions,
             cwd,
             namespace: AGENT_BROWSER_SCRIPT_NAMESPACE,
             restoreState: managedSessionRestoreState,
@@ -991,6 +995,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         const previousManagedSessionName = managedSessionName;
         const previousFreshSessionOrdinal = freshSessionOrdinal;
         const previousAttachedSessionKeys = attachedSessionKeys;
+        const previousSessionPageState = sessionPageState;
         managedSessionBaseName = createImplicitSessionName(ctx.sessionManager.getSessionId(), ctx.cwd, ephemeralSessionSeed);
         browserOwnerSessionId = ctx.sessionManager.getSessionId();
         let branch;
@@ -1160,6 +1165,11 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             }
         }
         if (!options.resetRuntimeOwnership) {
+            // Off-branch live owners still need their established setting for cleanup.
+            for (const key of ownedManagedSessions.keys()) {
+                if (!branchResourceEvents.managedSessionActiveIdentities.has(key))
+                    sessionPageState.setConfirmActions(key, previousSessionPageState.get(key).confirmActions);
+            }
             for (const sessionKey of previousAttachedSessionKeys) {
                 if (ownedManagedSessions.has(sessionKey))
                     attachedSessionKeys.add(sessionKey);
@@ -1239,6 +1249,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 electronLaunchRecords: electronRecordsToCleanup,
                 managedSessionRestoreState,
                 ownedManagedSessions,
+                sessionPageState,
                 timeoutMs: implicitSessionCloseTimeoutMs,
             });
             preservedElectronProfileDirs = [...new Set([
@@ -1249,10 +1260,10 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             for (const identity of getCleanupResultsClosedManagedSessionIdentities(electronCleanupResults))
                 retireRecordingSession(identity.sessionName, identity.namespace);
             if (quitting) {
-                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
+                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, sessionPageState, undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
             }
             else {
-                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
+                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, sessionPageState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
             }
             flushRecordingReservations();
             notifyRecordingPersistence(ctx);
@@ -1404,11 +1415,11 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 await beforeExecute?.(nativeToolCallId, { ...ctx, signal });
                 const runtimeBrowserConfig = loadAgentBrowserConfigSync({ cwd: ctx.cwd, includeProjectConfig: shouldIncludeProjectConfig(ctx) });
                 const rootProfile = runtimeBrowserConfig.trustedBrowserDefaultProfile;
-                const pendingReadConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
+                const pendingReadConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE), resolvedInput.toolStdin);
                 const rootSessionId = process.env.PI_SUBAGENT_CHILD === "1" && process.env.PI_SUBAGENT_ROOT_SESSION_ID
                     ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : ctx.sessionManager.getSessionId();
                 return withNativeSessionDefaults(resolvedInput, browserCwd, signal, async (resolvedInput, withLaunchDefaults) => {
-                    const readConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
+                    const readConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE), resolvedInput.toolStdin);
                     if (readConfirmation)
                         resolvedInput = { ...resolvedInput, toolArgs: scopeReadConfirmationArgs(resolvedInput.toolArgs, readConfirmation) };
                     if (resolvedInput.kind === "qa" && resolvedInput.compiledQaPreset.checks.attached && !managedSessionActive && !extractExplicitSessionName(resolvedInput.toolArgs)) {
@@ -1657,13 +1668,16 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             && (needsManagedSession(parseArgvDescriptor(toolArgs), resolvedInput.toolStdin) || (selectedPlan.startupScopedFlags?.length ?? 0) > 0);
                         const operationId = randomUUID();
                         const selectedKey = getAgentBrowserSessionIdentityKey(selectedPlan.sessionName ?? "default", selectedPlan.namespace);
+                        browserRunState.confirmationPolicyIdentity = selectedKey;
+                        const confirmActions = getAgentBrowserProcessEnvironment().AGENT_BROWSER_CONFIRM_ACTIONS;
+                        workingPageState.setConfirmActions(selectedKey, confirmActions);
                         const begin = { event: {
                                 version: 1, phase: "begin", operationId, toolCallId, commandIndex: commandIndex ?? 0, isError: true,
                                 state: { args: redactInvocationArgs(toolArgs), sessionName: selectedPlan.sessionName, namespace: selectedPlan.namespace,
                                     ownerSessionId: ctx.sessionManager.getSessionId(), usedImplicitSession: selectedPlan.usedImplicitSession,
                                     wrapperManaged: selectedPlan.managedSessionName !== undefined || ownedManagedSessions.has(selectedKey), managedSessionCwd: browserCwd,
                                     managedSessionSocketDir: resolveAgentBrowserSocketDir({ ownedManagedSession: selectedPlan.managedSessionName !== undefined || ownedManagedSessions.has(selectedKey) }) },
-                                pages: [{ key: selectedKey, refs: { kind: "unknown" }, unknown: true }],
+                                pages: [{ key: selectedKey, confirmActions: confirmActions ?? null, refs: { kind: "unknown" }, unknown: true }],
                             } };
                         if (browserAffecting) {
                             try {
@@ -1716,6 +1730,8 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             result = { ...failure, details: { ...browserRunState.observedBrowserEffects, ...(isRecord(failure.details) ? failure.details : {}) } };
                         }
                         const branchRestoreStillCurrent = branch.isCurrent();
+                        if (browserRunState.confirmationPolicyMayBeEstablished === false)
+                            workingPageState.setConfirmActions(selectedKey, priorPages.get(selectedKey)?.confirmActions);
                         const resultDetails = isRecord(result.details) ? result.details : undefined;
                         if (resultDetails && begin.event.state.wrapperManaged === true)
                             resultDetails.managedSessionSocketDir = begin.event.state.managedSessionSocketDir;
@@ -1736,7 +1752,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             const closeAllApplied = resultDetails?.closeAllApplied === true;
                             const attachedSessionRemainsActive = result.isError !== true
                                 || ((attachedSessionRequested || attachedSessionKnown) && managedSessionOutcome?.activeAfter === true);
-                            const closesAttachedSession = (result.isError !== true && isCloseCommand(extractUpstreamCommandTokens(toolArgs)[0]))
+                            const closesAttachedSession = (result.isError !== true && (isCloseCommand(extractUpstreamCommandTokens(toolArgs)[0]) || isSuccessfulNativeConfirmedClose(extractUpstreamCommandTokens(toolArgs), resultDetails?.data)))
                                 || resultBatchCloseLifecycle?.endsClosed === true;
                             if (closeAllApplied) {
                                 deleteIdentityKeysInNamespace(attachedSessionKeys, resultNamespace);
@@ -1835,7 +1851,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                 delete result.details.refSnapshot;
                             result.details.artifactManifest = invocationArtifactManifest(branch.isCurrent() ? artifactManifest : browserRunState.artifactManifest, initialArtifactManifest, result.details);
                         }
-                        return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
+                        return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, preserveTextContent: Array.isArray(params.args) && isBooleanFlagEnabled(params.args, "--json"), result: warnRecordingPersistence(result) });
                     };
                     const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
                     const runWithLaunchDefaults = async () => {
@@ -1847,7 +1863,14 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             stdin: resolvedInput.toolStdin,
                         });
                         const owner = ownedManagedSessions.get(getAgentBrowserSessionIdentityKey(plan.sessionName ?? "default", plan.namespace));
-                        return withAgentBrowserProcessEnvironment(owner?.socketDir ? { PI_AGENT_BROWSER_SOCKET_DIR: owner.socketDir } : {}, async () => {
+                        // Resolve inside the identity queue, before daemon inspection or any page helper.
+                        const explicitConfirmationSetting = ["--confirm-actions", "--config"].some(flag => scanUpstreamGlobalFlagOccurrences(toolArgs, flag).length > 0);
+                        const retainedConfirmActions = sessionPageState.get(getAgentBrowserSessionIdentityKey(plan.sessionName ?? "default", plan.namespace)).confirmActions;
+                        const confirmActions = !explicitConfirmationSetting && retainedConfirmActions !== undefined ? retainedConfirmActions : resolvedInput.nativeConfirmActions;
+                        return withAgentBrowserProcessEnvironment({
+                            ...(owner?.socketDir ? { PI_AGENT_BROWSER_SOCKET_DIR: owner.socketDir } : {}),
+                            AGENT_BROWSER_CONFIRM_ACTIONS: confirmActions,
+                        }, async () => {
                             const run = (executionSignal = signal) => {
                                 const execute = () => withLaunchDefaults
                                     ? withLaunchDefaults(inactive => runBrowserCommand(inactive, executionSignal), executionSignal)
@@ -2033,7 +2056,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         if (result.isError && details.error === undefined)
             details.error = details.validationError ?? details.summary ?? result.content.filter(item => item.type === "text").map(item => item.text).join("\n");
         const priorManifest = isSessionArtifactManifest(details.artifactManifest) ? details.artifactManifest : undefined;
-        const renderOptions = { content: result.content, details, json: "code" in params || params.args?.includes("--json") === true, succeeded: result.isError !== true,
+        const renderOptions = { content: result.content, details, json: "code" in params || isBooleanFlagEnabled(params.args ?? [], "--json"), succeeded: result.isError !== true,
             persistentArtifactStore: branch.isCurrent() ? getPersistentSessionArtifactStore(ctx) : undefined,
             withArtifactWrite: (write) => artifactExecutionQueue.run(() => {
                 if (!branch.isCurrent())

package/dist/extensions/agent-browser/lib/batch-lifecycle.js

@@ -1,6 +1,8 @@
 import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
 import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
+import { isSuccessfulNativeConfirmedClose } from "./read-confirmation.js";
+import { detectConfirmationRequired } from "./results/confirmation.js";
 export function batchHasSuccessfulCloseAll(data, fallbackCommands = []) {
     if (!Array.isArray(data))
         return false;
@@ -10,7 +12,7 @@ export function batchHasSuccessfulCloseAll(data, fallbackCommands = []) {
         const rowCommand = Array.isArray(row.command) && row.command.every((token) => typeof token === "string")
             ? row.command
             : fallbackCommands[index];
-        return rowCommand ? isCloseAllCommand(extractUpstreamCommandTokens(rowCommand)) : false;
+        return rowCommand ? !detectConfirmationRequired(row.result) && isCloseAllCommand(extractUpstreamCommandTokens(rowCommand)) : false;
     });
 }
 export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
@@ -41,12 +43,13 @@ export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
             continue;
         }
         const [command, subcommand] = extractUpstreamCommandTokens(rowCommand);
-        if (stepSucceeded && isCloseCommand(command)) {
+        if (stepSucceeded && !detectConfirmationRequired(result) && (isCloseCommand(command) || isSuccessfulNativeConfirmedClose(extractUpstreamCommandTokens(rowCommand), result))) {
             sawClose = true;
             endsClosed = true;
             browserActiveAfterClose = false;
             recordingClosedAfterBatch = true;
-            statePath = typeof result?.statePath === "string" ? result.statePath : undefined;
+            const closeData = command === "confirm" && isRecord(result?.result) ? result.result.data : result;
+            statePath = isRecord(closeData) && typeof closeData.statePath === "string" ? closeData.statePath : undefined;
         }
         else if (sawClose && command === "record") {
             if (browserLaunched !== false) {

package/dist/extensions/agent-browser/lib/browser-transcript.js

@@ -44,6 +44,7 @@ export function getBrowserRecord(entry) {
     }
     if (event.pages !== undefined && (!Array.isArray(event.pages) || !event.pages.every(page => isRecord(page)
         && typeof page.key === "string" && isRecord(page.refs) && ["reuse", "replace", "invalidate", "unknown"].includes(String(page.refs.kind))
+        && (page.confirmActions === undefined || page.confirmActions === null || typeof page.confirmActions === "string")
         && (!["reuse", "replace"].includes(String(page.refs.kind)) || typeof page.refs.snapshotId === "string" && page.refs.snapshotId.length > 0)
         && (page.target === undefined || isRecord(page.target) && normalizeSessionTabTarget(page.target) !== undefined)
         && (page.unknown === undefined || page.unknown === true) && (page.clear === undefined || page.clear === true)
@@ -96,7 +97,7 @@ export function snapshotFromDefinition(definition) {
 }
 export function pageChange(key, page, previousSnapshotId) {
     return {
-        key, target: page.tabTarget, unknown: page.tabTargetUnknown, reopenPending: page.tabReopenPending, pinningReason: page.pinningReason,
+        key, confirmActions: page.confirmActions ?? null, target: page.tabTarget, unknown: page.tabTargetUnknown, reopenPending: page.tabReopenPending, pinningReason: page.pinningReason,
         refs: page.tabTargetUnknown ? { kind: "unknown", invalidation: page.refSnapshotInvalidation }
             : page.refSnapshot && !targetsMatch(page.refSnapshot.target, page.tabTarget) ? { kind: "invalidate", invalidation: buildPageTransitionRefSnapshotInvalidation(`The saved refs came from a snapshot for ${page.refSnapshot.target?.url}; the current session target is ${page.tabTarget?.url}. Take a fresh snapshot before using page-scoped refs.`) }
                 : page.refSnapshot?.snapshotId ? { kind: page.refSnapshot.snapshotId === previousSnapshotId ? "reuse" : "replace", snapshotId: page.refSnapshot.snapshotId }

package/dist/extensions/agent-browser/lib/native-output.js

@@ -1,5 +1,6 @@
 import { JsonSchema } from "./json-schema.js";
 import { isRecord } from "./parsing.js";
+import { isBooleanFlagEnabled } from "./argv-grammar.js";
 import { finalizeAgentBrowserFailure } from "./pi-tool-rendering.js";
 import { isPlainTextInspectionArgs } from "./runtime.js";
 import { projectAgentBrowserObservation, OBSERVATION_INLINE_MAX_CHARS } from "./results/presentation/content.js";
@@ -32,7 +33,7 @@ export async function finalizeAgentBrowserNativeResult(result, input) {
         const { renderAgentBrowserObservation } = await import("./results/presentation/large-output.js");
         const rendered = await renderAgentBrowserObservation({
             content: finalized.content, details, succeeded,
-            json: isRecord(input) && ("code" in input || Array.isArray(input.args) && input.args.includes("--json")),
+            json: isRecord(input) && ("code" in input || Array.isArray(input.args) && isBooleanFlagEnabled(input.args, "--json")),
             // The caller's exact visible output stays inline (for example formatted search results); only the structured field is bounded.
             preserveContent: true,
         });

package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js

@@ -69,13 +69,7 @@ export function parseBatchCommandArgument(command) {
 function validateUserBatchStep(step, index) {
     if (!Array.isArray(step)) {
         return {
-            error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.${BATCH_STDIN_EXAMPLE}`,
-            ok: false,
-        };
-    }
-    if (step.length === 0) {
-        return {
-            error: `agent_browser batch stdin step ${index} must not be empty.${BATCH_STDIN_EXAMPLE}`,
+            error: `agent_browser batch stdin step ${index} must be an array of string command tokens.${BATCH_STDIN_EXAMPLE}`,
             ok: false,
         };
     }
@@ -137,5 +131,5 @@ export function getUpstreamEffectiveBatchSteps(commandTokens, stdin) {
     });
     if (argumentSteps.length > 0)
         return argumentSteps;
-    return parseUserBatchStdin(stdin).steps ?? [];
+    return parseUserBatchStdin(stdin).steps?.filter(step => step.length > 0) ?? [];
 }

package/dist/extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.js

@@ -2,6 +2,8 @@ import { isRecord, parseRefId } from "../../parsing.js";
 import { redactSensitiveText } from "../../runtime.js";
 import { withOptionalSessionArgs } from "../../results/next-actions.js";
 import { runSessionCommandData } from "./session-state.js";
+import { getAgentBrowserProcessTimeoutMs } from "../../process.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
 const CLICK_DISPATCH_MARKER_PREFIX = "__piAgentBrowserClickDispatchProbe_";
 const CLICK_DISPATCH_CLEANUP_TIMEOUT_MS = 2_000;
 const ACCESSIBLE_REF_CLICK_DISPATCH_ROLES = new Set(["button", "checkbox", "menuitem", "radio", "switch", "tab"]);
@@ -34,7 +36,7 @@ function getEvalResultRecord(data) {
 function getClickDispatchIdentityAttribute(probe) {
     return `data-pi-click-dispatch-${probe.marker.toLowerCase()}`;
 }
-function buildClickDispatchProbeInstallScript(probe) {
+function buildClickDispatchProbeInstallScript(probe, timeoutMs) {
     const target = probe.target;
     const resolveTarget = target.kind === "selector"
         ? `(() => { try { return document.querySelector(${JSON.stringify(target.selector)}); } catch { return null; } })()`
@@ -129,10 +131,15 @@ const listeners = eventTypes.map((type) => {
 });
 const identityAttribute = ${JSON.stringify(getClickDispatchIdentityAttribute(probe))};
 state.removeIdentityMarker = () => element.removeAttribute(identityAttribute);
+let cleanupTimer;
 state.cleanup = () => {
+  clearTimeout(cleanupTimer);
   state.removeIdentityMarker();
   listeners.forEach(([type, listener]) => document.removeEventListener(type, listener, true));
+  try { delete window[marker]; } catch {}
 };
+// A native pending decision can forbid cleanup eval; expire without another command.
+cleanupTimer = setTimeout(state.cleanup, ${timeoutMs + CLICK_DISPATCH_CLEANUP_TIMEOUT_MS});
 window[marker] = state;
 element.setAttribute(identityAttribute, marker);
 return { status: "installed", marker, target: state.target };
@@ -205,13 +212,16 @@ export function buildClickDispatchNextActions(options) {
 export async function prepareClickDispatchProbe(options) {
     if (!options.sessionName || options.commandTokens[0] !== "click" || options.commandTokens.includes("--new-tab"))
         return undefined;
+    // This optional diagnostic must not require approving a fresh eval on every click retry.
+    if (getAgentBrowserProcessEnvironment().AGENT_BROWSER_CONFIRM_ACTIONS?.split(",").some(action => action.trim().toLowerCase() === "evaluate"))
+        return undefined;
     const target = getClickDispatchProbeTarget(options.commandTokens, options.refSnapshot);
     if (!target)
         return undefined;
     const probe = { marker: `${CLICK_DISPATCH_MARKER_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`, target };
     let prepared = false;
     try {
-        const installData = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildClickDispatchProbeInstallScript(probe) });
+        const installData = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildClickDispatchProbeInstallScript(probe, options.timeoutMs ?? getAgentBrowserProcessTimeoutMs()) });
         if (getEvalResultRecord(installData)?.status !== "installed")
             return undefined;
         // Name matching and in-page XPath only find candidates. Native resolution

package/dist/extensions/agent-browser/lib/orchestration/browser-run/index.js

@@ -1,11 +1,18 @@
 import { runAgentBrowserProcess, withAttachedBrowserSessionContext, withChromeStartupArgs } from "../../process.js";
 import { isRecord } from "../../parsing.js";
+import { getAgentBrowserSessionIdentityKey, isBooleanFlagEnabled, resolveAgentBrowserNamespace } from "../../argv-grammar.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
+import { nextReadConfirmation, parseReadConfirmation, suppressConfirmationPageHelpers } from "../../read-confirmation.js";
+import { buildToolPresentation } from "../../results/presentation.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { collectNativeWebMcp, getNativeWebMcpCatalog } from "../../webmcp-observation.js";
 import { isPlainTextInspectionArgs, redactSensitiveValue } from "../../runtime.js";
 import { formatWebMcpCatalogUpdate } from "../../results/presentation/common.js";
 import { withOwnedManagedSessionContext } from "../../managed-session-restore.js";
 import { cleanupClickDispatchProbe } from "./click-dispatch.js";
-import { applyBrowserRunStatePatch, getSessionContextKey } from "./session-state.js";
+import { applyBrowserRunStatePatch, getSessionContextKey, nativePolicyDefinitelyUnestablished, withSessionCommandObservation } from "./session-state.js";
 import { buildScreenshotGeometry, collectScreenshotSample } from "./screenshot-observation.js";
 import { buildJsonVisibleContent, buildMissingBinaryFailureResult } from "./final-result.js";
 import { prepareBrowserRun } from "./prepare.js";
@@ -13,14 +20,42 @@ import { processBrowserOutput } from "./process-output.js";
 export { closeManagedSession } from "./managed-session-daemon-policy.js";
 export { getSessionContextKey } from "./session-state.js";
 export async function runAgentBrowserTool(options) {
-    const observed = await collectNativeWebMcp(() => withChromeStartupArgs(options.input.persistentChromeArgs, () => withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options))));
+    const observed = await collectNativeWebMcp(() => withSessionCommandObservation({
+        allow: helper => {
+            const pending = parseReadConfirmation(options.state.observedBrowserEffects?.readConfirmation);
+            return !needsManagedSession(parseArgvDescriptor(helper.args), helper.stdin) && !isBrowserIndependentRead(helper.args, helper.stdin)
+                || pending?.state !== "pending" || getAgentBrowserSessionIdentityKey(helper.sessionName ?? "default", resolveAgentBrowserNamespace([], helper.namespace ?? getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)) !== getAgentBrowserSessionIdentityKey(pending.sessionName, pending.namespace);
+        },
+        observe: (helper, processResult, envelope) => {
+            const namespace = resolveAgentBrowserNamespace([], helper.namespace ?? getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+            const sessionName = helper.sessionName ?? "default";
+            const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+            if (key === options.state.confirmationPolicyIdentity && !nativePolicyDefinitelyUnestablished(processResult, envelope, helper.args))
+                options.state.confirmationPolicyMayBeEstablished = true;
+            const confirmation = nextReadConfirmation({ commandTokens: helper.args, current: options.state.sessionPageState.getReadConfirmation(key), data: envelope?.data, namespace, sessionName, succeeded: envelope?.success === true && processResult.exitCode === 0 && !processResult.aborted && !processResult.timedOut });
+            if (confirmation) {
+                options.state.sessionPageState.applyReadConfirmation(confirmation, options.sessionPageStateUpdate);
+                if (helper.args[0] === "open" && confirmation.state === "pending") {
+                    const invalidation = options.state.sessionPageState.get(key).refSnapshotInvalidation;
+                    options.state.sessionPageState.markTabTargetUnknown({ sessionName: key, update: options.sessionPageStateUpdate });
+                    if (invalidation)
+                        options.state.sessionPageState.applyRefSnapshotInvalidation({ sessionName: key, update: options.sessionPageStateUpdate, invalidation });
+                }
+                options.state.observedBrowserEffects = { ...options.state.observedBrowserEffects, readConfirmation: confirmation };
+            }
+        },
+    }, () => withChromeStartupArgs(options.input.persistentChromeArgs, () => withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options)))));
     const result = observed.result;
     let details = isRecord(result.details) ? result.details : undefined;
+    if (details?.readConfirmation === undefined && options.state.observedBrowserEffects?.readConfirmation) {
+        details = { ...details, readConfirmation: options.state.observedBrowserEffects.readConfirmation };
+        result.details = details;
+    }
     if (observed.catalog) {
         const catalog = redactSensitiveValue(observed.catalog);
         details = { ...details, webMcpCatalog: catalog };
         result.details = details;
-        if (!options.input.toolArgs.includes("--json") && JSON.stringify(getNativeWebMcpCatalog(details.data)) !== JSON.stringify(catalog)) {
+        if (!isBooleanFlagEnabled(options.input.toolArgs, "--json") && JSON.stringify(getNativeWebMcpCatalog(details.data)) !== JSON.stringify(catalog)) {
             const notice = formatWebMcpCatalogUpdate(catalog);
             if (result.content[0]?.type === "text")
                 result.content[0] = { ...result.content[0], text: `${result.content[0].text}\n\n${notice}` };
@@ -42,11 +77,25 @@ export async function runAgentBrowserTool(options) {
     };
 }
 async function runAgentBrowserToolInContext(options) {
-    const preparedResult = await prepareBrowserRun(options);
+    let preparedResult = await prepareBrowserRun(options);
     applyBrowserRunStatePatch(options.state, preparedResult.kind === "ready" ? preparedResult.prepared.statePatch : preparedResult.statePatch);
+    const helperConfirmation = parseReadConfirmation(options.state.observedBrowserEffects?.readConfirmation);
+    if (helperConfirmation?.state === "pending") {
+        if (preparedResult.kind === "ready")
+            await preparedResult.prepared.managedSessionPolicyLock?.release();
+        const data = { confirmation_required: true, confirmation_id: helperConfirmation.id, action: helperConfirmation.action ?? "read" };
+        const presentation = await buildToolPresentation({ commandInfo: { command: helperConfirmation.command, commandTokens: [helperConfirmation.command ?? "read"] }, cwd: options.cwd, envelope: { success: true, data }, namespace: helperConfirmation.namespace, sessionName: helperConfirmation.sessionName });
+        preparedResult = { kind: "early-result", result: {
+                content: [{ type: "text", text: `Native helper ${helperConfirmation.command} requires confirmation (${helperConfirmation.action}). The requested command was not dispatched.` }, ...presentation.content],
+                details: { ...options.state.observedBrowserEffects, agentBrowserStarted: false, args: options.input.redactedArgs, data, sessionName: helperConfirmation.sessionName, namespace: helperConfirmation.namespace, sessionTabTargetUnknown: options.state.sessionPageState.get(getAgentBrowserSessionIdentityKey(helperConfirmation.sessionName, helperConfirmation.namespace)).tabTargetUnknown, readConfirmation: helperConfirmation, nextActions: presentation.nextActions,
+                    ...buildAgentBrowserResultCategoryDetails({ succeeded: false, failureCategory: "confirmation-required" }) },
+                isError: true,
+            } };
+    }
     if (preparedResult.kind === "early-result") {
+        options.state.confirmationPolicyMayBeEstablished ??= false;
         const result = preparedResult.result;
-        if (options.modelVisible !== false && options.input.toolArgs.includes("--json") && !isPlainTextInspectionArgs(options.input.toolArgs)) {
+        if (options.modelVisible !== false && isBooleanFlagEnabled(options.input.toolArgs, "--json") && !isPlainTextInspectionArgs(options.input.toolArgs)) {
             const details = isRecord(result.details) ? result.details : {};
             const summary = result.content.filter(item => item.type === "text").map(item => item.text).join("\n");
             result.content = buildJsonVisibleContent({
@@ -70,7 +119,7 @@ async function runAgentBrowserToolInContext(options) {
             const artifactRunStartedAtMs = Date.now();
             const processResult = await withChromeStartupArgs(prepared.chromeStartupArgs, () => runAgentBrowserProcess({
                 args: prepared.processArgs,
-                browserIndependentReadConfirmation: prepared.readConfirmation !== undefined,
+                nativeConfirmationDecision: suppressConfirmationPageHelpers(prepared.readConfirmation),
                 cwd: options.cwd,
                 env: ownedManagedSession
                     ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs }
@@ -99,8 +148,10 @@ async function runAgentBrowserToolInContext(options) {
                 sessionMode: prepared.sessionMode,
                 sessionTabCorrection: prepared.sessionTabCorrection,
             });
-            if (missingBinaryResult)
+            if (missingBinaryResult) {
+                options.state.confirmationPolicyMayBeEstablished ??= false;
                 return missingBinaryResult;
+            }
             const output = await processBrowserOutput({ ...options, artifactRunStartedAtMs, prepared, processResult });
             applyBrowserRunStatePatch(options.state, output.statePatch);
             if (isRecord(output.result.details) && Array.isArray(output.result.details.imageObservations) && prepared.commandTokens[0] === "screenshot") {