merge: resolve conflict in BaseSelectionList and align scroll arrow implementation

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: nmcnamara-eng <118702206+nmcnamara-eng@users.noreply.github.com>

.gcp/Dockerfile.development

@@ -0,0 +1,89 @@
+# --- STAGE 1: Base Runtime ---
+FROM docker.io/library/node:20-slim AS base
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  python3 \
+  python3-pip \
+  python3-venv \
+  curl \
+  dnsutils \
+  less \
+  jq \
+  ca-certificates \
+  git \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/*
+
+# --- STAGE 2: Builder (Compile Main) ---
+FROM base AS builder
+WORKDIR /build
+COPY . .
+RUN npm ci --ignore-scripts
+RUN npm run bundle
+# Run the official release preparation script to move the bundle and assets into packages/cli
+RUN node scripts/prepare-npm-release.js
+
+# --- STAGE 3: Development Environment ---
+FROM base AS development
+
+WORKDIR /home/node/dev/main
+
+# Set up npm global package folder
+RUN mkdir -p /usr/local/share/npm-global \
+  && chown -R node:node /usr/local/share/npm-global
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Copy package.json to extract versions for global tools
+COPY package.json /tmp/package.json
+
+# Install Build Tools, Global Dev Tools (pinned), and Linters
+ARG ACTIONLINT_VER=1.7.7
+ARG SHELLCHECK_VER=0.11.0
+ARG YAMLLINT_VER=1.35.1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  make \
+  g++ \
+  gh \
+  git \
+  unzip \
+  rsync \
+  ripgrep \
+  procps \
+  psmisc \
+  lsof \
+  socat \
+  tmux \
+  docker.io \
+  build-essential \
+  libsecret-1-dev \
+  libkrb5-dev \
+  file \
+  && curl -sSLo /tmp/actionlint.tar.gz https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VER}/actionlint_${ACTIONLINT_VER}_linux_amd64.tar.gz \
+  && tar -xzf /tmp/actionlint.tar.gz -C /usr/local/bin actionlint \
+  && curl -sSLo /tmp/shellcheck.tar.xz https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VER}/shellcheck-v${SHELLCHECK_VER}.linux.x86_64.tar.xz \
+  && tar -xf /tmp/shellcheck.tar.xz -C /usr/local/bin --strip-components=1 shellcheck-v${SHELLCHECK_VER}/shellcheck \
+  && pip3 install --break-system-packages yamllint==${YAMLLINT_VER} \
+  && export TSX_VER=$(node -p "require('/tmp/package.json').devDependencies.tsx") \
+  && export VITEST_VER=$(node -p "require('/tmp/package.json').devDependencies.vitest") \
+  && export PRETTIER_VER=$(node -p "require('/tmp/package.json').devDependencies.prettier") \
+  && export ESLINT_VER=$(node -p "require('/tmp/package.json').devDependencies.eslint") \
+  && export CROSS_ENV_VER=$(node -p "require('/tmp/package.json').devDependencies['cross-env']") \
+  && npm install -g tsx@$TSX_VER vitest@$VITEST_VER prettier@$PRETTIER_VER eslint@$ESLINT_VER cross-env@$CROSS_ENV_VER typescript@5.3.3 \
+  && npm install -g @google/gemini-cli@nightly && mv /usr/local/share/npm-global/bin/gemini /usr/local/share/npm-global/bin/g-nightly \
+  && npm install -g @google/gemini-cli@preview && mv /usr/local/share/npm-global/bin/gemini /usr/local/share/npm-global/bin/g-preview \
+  && npm install -g @google/gemini-cli@latest  && mv /usr/local/share/npm-global/bin/gemini /usr/local/share/npm-global/bin/g-stable \
+  && apt-get purge -y build-essential libsecret-1-dev libkrb5-dev \
+  && apt-get autoremove -y \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/* /tmp/* /root/.npm
+
+# Copy the bundled CLI package to a permanent location and install it
+# We MUST not delete this source folder as 'npm install -g <folder>' 
+# often symlinks to it for local folder installs.
+COPY --from=builder /build/packages/cli /usr/local/lib/gemini-cli
+RUN npm install -g /usr/local/lib/gemini-cli
+
+USER node
+CMD ["/bin/bash"]

.gcp/Dockerfile.development.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+.git
+.gemini/workspaces
+dist
+!packages/*/dist/*.tgz
+bundle
+out
+*.log
+.env
+.DS_Store

.gcp/development-worker.yml

@@ -0,0 +1,58 @@
+substitutions:
+  _IMAGE_NAME: 'development'
+  _ARTIFACT_REGISTRY_REPO: 'us-docker.pkg.dev/gemini-code-dev/gemini-cli'
+
+steps:
+  # Step 1: Install root dependencies
+  - name: 'us-west1-docker.pkg.dev/gemini-code-dev/gemini-code-containers/gemini-code-builder'
+    id: 'Install Dependencies'
+    entrypoint: 'npm'
+    args: ['install']
+
+  # Step 2: Authenticate for Docker
+  - name: 'us-west1-docker.pkg.dev/gemini-code-dev/gemini-code-containers/gemini-code-builder'
+    id: 'Authenticate docker'
+    entrypoint: 'npm'
+    args: ['run', 'auth']
+
+  # Step 3: Build workspace packages
+  - name: 'us-west1-docker.pkg.dev/gemini-code-dev/gemini-code-containers/gemini-code-builder'
+    id: 'Build packages'
+    entrypoint: 'npm'
+    args: ['run', 'build:packages']
+
+  # Step 4: Build Development Image
+  - name: 'us-west1-docker.pkg.dev/gemini-code-dev/gemini-code-containers/gemini-code-builder'
+    id: 'Build Development Image'
+    entrypoint: 'bash'
+    env:
+      - 'RAW_BRANCH_VALUE=${BRANCH_NAME}'
+    args:
+      - '-c'
+      - |-
+        IMAGE_BASE="${_ARTIFACT_REGISTRY_REPO}/${_IMAGE_NAME}"
+
+        # Determine the primary tag (branch name or 'latest' for main)
+        # Use $$ for shell variables to avoid Cloud Build attempting premature substitution
+        RAW_BRANCH="$$RAW_BRANCH_VALUE"
+        if [ "$${RAW_BRANCH}" == "main" ]; then
+          TAG_PRIMARY="latest"
+        else
+          TAG_PRIMARY=$$(echo "$${RAW_BRANCH}" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
+        fi
+
+        # Use SHORT_SHA if available (Cloud Build) or fallback to latest-dev
+        TAG_SHA="$${SHORT_SHA:-latest-dev}"
+
+        echo "📦 Building Development Image for: $${RAW_BRANCH} -> $${TAG_PRIMARY} ($${TAG_SHA})"
+
+        docker build -f .gcp/Dockerfile.development \
+          -t "$${IMAGE_BASE}:$${TAG_SHA}" \
+          -t "$${IMAGE_BASE}:$${TAG_PRIMARY}" .
+
+        docker push "$${IMAGE_BASE}:$${TAG_SHA}"
+        docker push "$${IMAGE_BASE}:$${TAG_PRIMARY}"
+
+options:
+  defaultLogsBucketBehavior: 'REGIONAL_USER_OWNED_BUCKET'
+  dynamicSubstitutions: true

.gemini/skills/docs-writer/SKILL.md

@@ -65,8 +65,6 @@ accessible.
 - **UI and code:** Use **bold** for UI elements and `code font` for filenames,
   snippets, commands, and API elements. Focus on the task when discussing
   interaction.
-- **Links:** Use descriptive anchor text; avoid "click here." Ensure the link
-  makes sense out of context.
 - **Accessibility:** Use semantic HTML elements correctly (headings, lists, 
   tables).
 - **Media:** Use lowercase hyphenated filenames. Provide descriptive alt text
@@ -100,6 +98,18 @@ accessible.
 > This is an example of a multi-line note that will be preserved
 > by Prettier.
 
+### Links
+- **Accessibility:** Use descriptive anchor text; avoid "click here." Ensure the
+  link makes sense out of context, such as when being read by a screen reader.
+- **Use relative links in docs:** Use relative links in documentation (`/docs/`)
+  to ensure portability. Use paths relative to the current file's directory
+  (for example, `../tools/` from `docs/cli/`). Do not include the `/docs/`
+  section of a path, but do verify that the resulting relative link exists. This
+  does not apply to meta files such as README.MD and CONTRIBUTING.MD.
+- **When changing headings, check for deep links:** If a user is changing a
+  heading, check for deep links to that heading in other pages and update
+  accordingly.
+
 ### Structure
 - **BLUF:** Start with an introduction explaining what to expect.
 - **Experimental features:** If a feature is clearly noted as experimental,
@@ -157,7 +167,6 @@ documentation.
 - **Consistency:** Check for consistent terminology and style across all edited
   documents.
 
-
 ## Phase 4: Verification and finalization
 Perform a final quality check to ensure that all changes are correctly formatted
 and that all links are functional.

.gemini/skills/review-duplication/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: review-duplication
+description: Use this skill during code reviews to proactively investigate the codebase for duplicated functionality, reinvented wheels, or failure to reuse existing project best practices and shared utilities.
+---
+
+# Review Duplication
+
+## Overview
+
+This skill provides a structured workflow for investigating a codebase during a code review to identify duplicated logic, reinvented utilities, and missed opportunities to reuse established patterns. By executing this workflow, you ensure that new code integrates seamlessly with the existing project architecture.
+
+## Workflow: Investigating for Duplication
+
+When reviewing code, perform the following steps before finalizing your review:
+
+### 1. Extract Core Logic
+Analyze the new code to identify the core algorithms, utility functions, generic data structures, or UI components being introduced. Look beyond the specific business logic to see the underlying mechanics.
+
+### 2. Hypothesize Existing Locations & Trace Dependencies
+Think about where this type of code *would* live if it already existed in the project. Provide absolute paths from the repo root to disambiguate.
+- **Utilities:** `packages/core/src/utils/`, `packages/cli/src/utils/`
+- **UI Components:** `packages/cli/src/ui/components/`, `packages/cli/src/ui/`
+- **Services:** `packages/core/src/services/`, `packages/cli/src/services/`
+- **Configuration:** `packages/core/src/config/`, `packages/cli/src/config/`
+- **Core Logic:** Call out `packages/core/` if functionality does not appear React UI specific.
+
+**Trace Third-Party Dependencies:** If the PR introduces a new import for a utility library (e.g., `lodash.merge`, `date-fns`), trace how and where the project currently uses that library. There is likely an existing wrapper or shared utility.
+
+**Check Package Files:** Before flagging a custom implementation of a complex algorithm, check `package.json` to see if a standard library (like `lodash` or `uuid`) is already installed that provides this functionality.
+
+### 3. Investigate the Codebase (Sub-Agent Delegation)
+Delegate the heavy lifting of codebase investigation to specialized sub-agents. They are optimized to perform deep searches and semantic mapping without bloating your session history.
+
+To ensure a comprehensive review, you MUST formulate highly specific objectives for the sub-agents, providing them with the "scents" you discovered in Step 1.
+
+- **Codebase Investigator:** Use the `codebase_investigator` as your primary researcher. When delegating, formulate an objective that asks specific, investigative questions about the codebase, explicitly including these search vectors:
+  - **Structural Similarity:** Ask if existing code uses the same underlying APIs (e.g., "Does any existing code use `Intl.DateTimeFormat` or `setTimeout` for similar purposes?").
+  - **Naming Conventions:** Ask if there are existing symbols with similar naming patterns (e.g., "Are there existing symbols with naming patterns like `*Format*` or `*Debounce*`?").
+  - **Comments & Documentation:** Ask if keywords from the PR's comments or JSDoc exist in describing similar behavior elsewhere.
+  - **Architectural Fit:** Ask where this type of logic is currently centralized (e.g., "Where is centralized date formatting logic located?").
+  - **Refactoring Guidance:** Crucially, ask the sub-agent to explain *how* the new code could be refactored to use any existing logic it finds.
+- **Generalist Agent:** Use the `generalist` for detailed, turn-intensive comparisons. For example: "Review the implementation of `MyNewComponent` in the PR and compare it semantically against all components in `packages/ui/src`. Are there any existing components that could be extended or used instead?"
+- **Retain Fast Path for Simple Searches:** For extremely simple, unambiguous checks (e.g., "Does `package.json` include `lodash`?"), perform a direct search to save time. Default to delegation for any open-ended "investigations."
+
+### 4. Evaluate Best Practices
+Check if the new code aligns with the project's established conventions.
+- **Error Handling:** Does it use the project's standard error classes or logging mechanisms?
+- **State Management:** Does it bypass established stores or contexts?
+- **Styling:** Does it hardcode colors or spacing instead of using theme variables?
+If the PR introduces a new pattern, compare it against the documented standards and explicitly confirm if an existing project pattern should have been used instead.
+
+### 5. Formulate Constructive Feedback
+If you discover that the PR duplicates existing functionality or ignores a best practice:
+- Provide a clear review comment.
+- **Identify the Source:** Explicitly mention the absolute or project-relative file path and the specific symbol (function, component, class) that should be reused.
+- **Implementation Guidance:** Provide a brief code snippet or a clear explanation showing **how** to integrate the existing code to fulfill the task's requirements.
+- **Explain the Value:** Briefly explain why reusing the existing code is beneficial (e.g., maintainability, consistency, built-in edge case handling).
+
+Example comment:
+> "It looks like this PR introduces a new `formatDate` utility. We already have a robust, tested `formatDate` function in `src/utils/dateHelpers.ts`. 
+>
+> You can replace your implementation by importing it like this:
+> ```typescript
+> import { formatDate } from '../utils/dateHelpers';
+> 
+> // Then use it here:
+> const displayDate = formatDate(userDate, 'MMM Do, YYYY');
+> ```
+> Reusing this ensures that the date formatting remains consistent with the rest of the application and handles timezone conversions correctly."

.github/workflows/chained_e2e.yml

@@ -334,8 +334,20 @@ jobs:
         if: "${{ steps.check_evals.outputs.should_run == 'true' }}"
         env:
           GEMINI_API_KEY: '${{ secrets.GEMINI_API_KEY }}'
+          GEMINI_MODEL: 'gemini-3-pro-preview'
+          # Disable Vitest internal retries to avoid double-retrying;
+          # custom retry logic is handled in evals/test-helper.ts
+          VITEST_RETRY: 0
         run: 'npm run test:always_passing_evals'
 
+      - name: 'Upload Reliability Logs'
+        if: "always() && steps.check_evals.outputs.should_run == 'true'"
+        uses: 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02' # ratchet:actions/upload-artifact@v4
+        with:
+          name: 'eval-logs-${{ github.run_id }}-${{ github.run_attempt }}'
+          path: 'evals/logs/api-reliability.jsonl'
+          retention-days: 7
+
   e2e:
     name: 'E2E'
     if: |

.github/workflows/evals-nightly.yml

@@ -61,6 +61,8 @@ jobs:
           GEMINI_MODEL: '${{ matrix.model }}'
           RUN_EVALS: "${{ github.event.inputs.run_all != 'false' }}"
           TEST_NAME_PATTERN: '${{ github.event.inputs.test_name_pattern }}'
+          # Disable Vitest internal retries to avoid double-retrying;
+          # custom retry logic is handled in evals/test-helper.ts
           VITEST_RETRY: 0
         run: |
           CMD="npm run test:all_evals"

docs/changelogs/latest.md

@@ -1,6 +1,6 @@
-# Latest stable release: v0.35.0
+# Latest stable release: v0.35.2
 
-Released: March 24, 2026
+Released: March 26, 2026
 
 For most users, our latest stable release is the recommended release. Install
 the latest stable version with:
@@ -29,6 +29,11 @@ npm install -g @google/gemini-cli
 
 ## What's Changed
 
+- fix(core): allow disabling environment variable redaction by @galz10 in
+  [#23927](https://github.com/google-gemini/gemini-cli/pull/23927)
+- fix(a2a-server): A2A server should execute ask policies in interactive mode by
+  @keith.schaab in
+  [#23831](https://github.com/google-gemini/gemini-cli/pull/23831)
 - feat(cli): customizable keyboard shortcuts by @scidomino in
   [#21945](https://github.com/google-gemini/gemini-cli/pull/21945)
 - feat(core): Thread `AgentLoopContext` through core. by @joshualitt in
@@ -380,4 +385,4 @@ npm install -g @google/gemini-cli
   [#23585](https://github.com/google-gemini/gemini-cli/pull/23585)
 
 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.34.0...v0.35.0
+https://github.com/google-gemini/gemini-cli/compare/v0.34.0...v0.35.2

docs/changelogs/preview.md

@@ -1,6 +1,6 @@
-# Preview release: v0.36.0-preview.3
+# Preview release: v0.36.0-preview.4
 
-Released: March 25, 2026
+Released: March 26, 2026
 
 Our preview release includes the latest, new, and experimental features. This
 release may not be as stable as our [latest weekly release](latest.md).
@@ -31,6 +31,8 @@ npm install -g @google/gemini-cli@preview
 
 ## What's Changed
 
+- feat(core): support inline agentCardJson for remote agents by @adamfweidman in
+  [#23743](https://github.com/google-gemini/gemini-cli/pull/23743)
 - fix(patch): cherry-pick 055ff92 to release/v0.36.0-preview.0-pr-23672 to patch
   version v0.36.0-preview.0 and create version 0.36.0-preview.1 by
   @gemini-cli-robot in
@@ -379,4 +381,4 @@ npm install -g @google/gemini-cli@preview
   [#23666](https://github.com/google-gemini/gemini-cli/pull/23666)
 
 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.35.0-preview.5...v0.36.0-preview.3
+https://github.com/google-gemini/gemini-cli/compare/v0.35.0-preview.5...v0.36.0-preview.4

docs/cli/acp-mode.md

@@ -0,0 +1,126 @@
+# ACP Mode
+
+ACP (Agent Client Protocol) mode is a special operational mode of Gemini CLI
+designed for programmatic control, primarily for IDE and other developer tool
+integrations. It uses a JSON-RPC protocol over stdio to communicate between
+Gemini CLI agent and a client.
+
+To start Gemini CLI in ACP mode, use the `--acp` flag:
+
+```bash
+gemini --acp
+```
+
+## Agent Client Protocol (ACP)
+
+ACP is an open protocol that standardizes how AI coding agents communicate with
+code editors and IDEs. It addresses the challenge of fragmented distribution,
+where agents traditionally needed custom integrations for each client. With ACP,
+developers can implement their agent once, and it becomes compatible with any
+ACP-compliant editor.
+
+For a comprehensive introduction to ACP, including its architecture and
+benefits, refer to the official
+[ACP Introduction](https://agentclientprotocol.com/get-started/introduction)
+documentation.
+
+### Existing integrations using ACP
+
+The ACP Agent Registry simplifies the distribution and management of
+ACP-compatible agents across various IDEs. Gemini CLI is an ACP-compatible agent
+and can be found in this registry.
+
+For more general information about the registry, and how to use it with specific
+IDEs like JetBrains and Zed, refer to the
+[IDE Integration](../ide-integration/index.md) documentation.
+
+You can also find more information on the official
+[ACP Agent Registry](https://agentclientprotocol.com/get-started/registry) page.
+
+## Architecture and protocol basics
+
+ACP mode establishes a client-server relationship between your tool (the client)
+and Gemini CLI (the server).
+
+- **Communication:** The entire communication happens over standard input/output
+  (stdio) using the JSON-RPC 2.0 protocol.
+- **Client's role:** The client is responsible for sending requests (e.g.,
+  prompts) and handling responses and notifications from Gemini CLI.
+- **Gemini CLI's role:** In ACP mode, Gemini CLI listens for incoming JSON-RPC
+  requests, processes them, and sends back responses.
+
+The core of the ACP implementation can be found in
+`packages/cli/src/acp/acpClient.ts`.
+
+### Extending with MCP
+
+ACP can be used with the Model Context Protocol (MCP). This lets an ACP client
+(like an IDE) expose its own functionality as "tools" that the Gemini model can
+use.
+
+1.  The client implements an **MCP server** that advertises its tools.
+2.  During the ACP `initialize` handshake, the client provides the connection
+    details for its MCP server.
+3.  Gemini CLI connects to the MCP server, discovers the available tools, and
+    makes them available to the AI model.
+4.  When the model decides to use one of these tools, Gemini CLI sends a tool
+    call request to the MCP server.
+
+This mechanism lets for a powerful, two-way integration where the agent can
+leverage the IDE's capabilities to perform tasks. The MCP client logic is in
+`packages/core/src/tools/mcp-client.ts`.
+
+## Capabilities and supported methods
+
+The ACP protocol exposes a number of methods for ACP clients (e.g. IDEs) to
+control Gemini CLI.
+
+### Core methods
+
+- `initialize`: Establishes the initial connection and lets the client to
+  register its MCP server.
+- `authenticate`: Authenticates the user.
+- `newSession`: Starts a new chat session.
+- `loadSession`: Loads a previous session.
+- `prompt`: Sends a prompt to the agent.
+- `cancel`: Cancels an ongoing prompt.
+
+### Session control
+
+- `setSessionMode`: Allows changing the approval level for tool calls (e.g., to
+  `auto-approve`).
+- `unstable_setSessionModel`: Changes the model for the current session.
+
+### File system proxy
+
+ACP includes a proxied file system service. This means that when the agent needs
+to read or write files, it does so through the ACP client. This is a security
+feature that ensures the agent only has access to the files that the client (and
+by extension, the user) has explicitly allowed.
+
+## Debugging and telemetry
+
+You can get insights into the ACP communication and the agent's behavior through
+debugging logs and telemetry.
+
+### Debugging logs
+
+To enable general debugging logs, start Gemini CLI with the `--debug` flag:
+
+```bash
+gemini --acp --debug
+```
+
+### Telemetry
+
+For more detailed telemetry, you can use the following environment variables to
+capture telemetry data to a file:
+
+- `GEMINI_TELEMETRY_ENABLED=true`
+- `GEMINI_TELEMETRY_TARGET=local`
+- `GEMINI_TELEMETRY_OUTFILE=/path/to/your/log.json`
+
+This will write a JSON log file containing detailed information about all the
+events happening within the agent, including ACP requests and responses. The
+integration test `integration-tests/acp-telemetry.test.ts` provides a working
+example of how to set this up.

docs/cli/notifications.md

@@ -15,14 +15,14 @@ CLI works in the background.
 
 ## Requirements
 
-Currently, system notifications are only supported on macOS.
-
 ### Terminal support
 
 The CLI uses the OSC 9 terminal escape sequence to trigger system notifications.
-This is supported by several modern terminal emulators. If your terminal does
-not support OSC 9 notifications, Gemini CLI falls back to a system alert sound
-to get your attention.
+This is supported by several modern terminal emulators including iTerm2,
+WezTerm, Ghostty, and Kitty. If your terminal does not support OSC 9
+notifications, Gemini CLI falls back to a terminal bell (BEL) to get your
+attention. Most terminals respond to BEL with a taskbar flash or system alert
+sound.
 
 ## Enable notifications
 

docs/cli/settings.md

@@ -29,7 +29,7 @@ they appear in the UI.
 | Vim Mode                | `general.vimMode`                  | Enable Vim keybindings                                                                                                                                                                                                                                        | `false`     |
 | Default Approval Mode   | `general.defaultApprovalMode`      | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. YOLO mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo). | `"default"` |
 | Enable Auto Update      | `general.enableAutoUpdate`         | Enable automatic updates.                                                                                                                                                                                                                                     | `true`      |
-| Enable Notifications    | `general.enableNotifications`      | Enable run-event notifications for action-required prompts and session completion. Currently macOS only.                                                                                                                                                      | `false`     |
+| Enable Notifications    | `general.enableNotifications`      | Enable run-event notifications for action-required prompts and session completion.                                                                                                                                                                            | `false`     |
 | Plan Directory          | `general.plan.directory`           | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.                                                                     | `undefined` |
 | Plan Model Routing      | `general.plan.modelRouting`        | Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.                                                                                                          | `true`      |
 | Retry Fetch Errors      | `general.retryFetchErrors`         | Retry on "exception TypeError: fetch failed sending request" errors.                                                                                                                                                                                          | `true`      |

docs/get-started/examples.md

@@ -1,141 +0,0 @@
-# Gemini CLI examples
-
-Gemini CLI helps you automate common engineering tasks by combining AI reasoning
-with local system tools. This document provides examples of how to use the CLI
-for file management, code analysis, and data transformation.
-
-<!-- prettier-ignore -->
-> [!NOTE]
-> These examples demonstrate potential capabilities. Your actual
-> results can vary based on the model used and your project environment.
-
-## Rename your photographs based on content
-
-You can use Gemini CLI to automate file management tasks that require visual
-analysis. In this example, Gemini CLI renames images based on their actual
-subject matter.
-
-Scenario: You have a folder containing the following files:
-
-```bash
-photos/photo1.png
-photos/photo2.png
-photos/photo3.png
-```
-
-Give Gemini the following prompt:
-
-```cli
-Rename the photos in my "photos" directory based on their contents.
-```
-
-Result: Gemini asks for permission to rename your files.
-
-Select **Allow once** and your files are renamed:
-
-```bash
-photos/yellow_flowers.png
-photos/antique_dresser.png
-photos/green_android_robot.png
-```
-
-## Explain a repository by reading its code
-
-Gemini CLI is effective for rapid codebase exploration. The following example
-shows how to ask Gemini CLI to fetch, analyze, and summarize a remote project.
-
-Scenario: You want to understand how a popular open-source utility works by
-inspecting its code, not just its README.
-
-Give Gemini CLI the following prompt:
-
-```cli
-Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
-```
-
-Result: Gemini performs a sequence of actions to answer your request.
-
-1.  First, it asks for permission to run `git clone` to download the repository.
-2.  Next, it finds the important source files and asks for permission to read
-    them.
-3.  Finally, after analyzing the code, it provides a summary.
-
-Gemini CLI returns an explanation based on the actual source code:
-
-```markdown
-The `chalk` library is a popular npm package for styling terminal output with
-colors. After analyzing the source code, here's how it works:
-
-- **Core functionality:** The main file sets up a chainable API. Each color or
-  modifier (like `bold` or `italic`) is a getter that appends the corresponding
-  ANSI escape code to an internal stack.
-
-- **Chainable API:** When you call `chalk.red.bold('Hello')`, you are accessing
-  getters. The `red` getter adds the red color code, and the `bold` getter adds
-  the bold code.
-
-- **Output generation:** When the chain is treated as a string (e.g., in
-  `console.log`), a final `toString()` method is called. This method joins all
-  the stored ANSI codes, wraps them around the input string ('Hello'), and adds
-  a reset code at the end. This produces the final, styled string that the
-  terminal can render.
-```
-
-## Combine two spreadsheets into one spreadsheet
-
-Gemini CLI can process and transform data across multiple files. Use this
-capability to merge reports or reformat data sets without manual copying.
-
-Scenario: You have two .csv files: `Revenue - 2023.csv` and
-`Revenue - 2024.csv`. Each file contains monthly revenue figures.
-
-Give Gemini CLI the following prompt:
-
-```cli
-Combine the two .csv files into a single .csv file, with each year a different column.
-```
-
-Result: Gemini CLI reads each file and then asks for permission to write a new
-file. Provide your permission and Gemini CLI provides the combined data:
-
-```csv
-Month,2023,2024
-January,0,1000
-February,0,1200
-March,0,2400
-April,900,500
-May,1000,800
-June,1000,900
-July,1200,1000
-August,1800,400
-September,2000,2000
-October,2400,3400
-November,3400,1800
-December,2100,9000
-```
-
-## Run unit tests
-
-Gemini CLI can generate boilerplate code and tests based on your existing
-implementation. This example demonstrates how to request code coverage for a
-JavaScript component.
-
-Scenario: You've written a simple login page. You wish to write unit tests to
-ensure that your login page has code coverage.
-
-Give Gemini CLI the following prompt:
-
-```cli
-Write unit tests for Login.js.
-```
-
-Result: Gemini CLI asks for permission to write a new file and creates a test
-for your login page.
-
-## Next steps
-
-- Follow the [File management](../cli/tutorials/file-management.md) guide to
-  start working with your codebase.
-- Follow the [Quickstart](./index.md) to start your first session.
-- See the [Cheatsheet](../cli/cli-reference.md) for a quick reference of
-  available commands.

docs/get-started/index.md

@@ -62,7 +62,133 @@ Once installed and authenticated, you can start using Gemini CLI by issuing
 commands and prompts in your terminal. Ask it to generate code, explain files,
 and more.
 
-To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md).
+<!-- prettier-ignore -->
+> [!NOTE]
+> These examples demonstrate potential capabilities. Your actual
+> results can vary based on the model used and your project environment.
+
+### Rename your photographs based on content
+
+You can use Gemini CLI to automate file management tasks that require visual
+analysis. In this example, Gemini CLI renames images based on their actual
+subject matter.
+
+Scenario: You have a folder containing the following files:
+
+```bash
+photos/photo1.png
+photos/photo2.png
+photos/photo3.png
+```
+
+Give Gemini the following prompt:
+
+```cli
+Rename the photos in my "photos" directory based on their contents.
+```
+
+Result: Gemini asks for permission to rename your files.
+
+Select **Allow once** and your files are renamed:
+
+```bash
+photos/yellow_flowers.png
+photos/antique_dresser.png
+photos/green_android_robot.png
+```
+
+### Explain a repository by reading its code
+
+Gemini CLI is effective for rapid codebase exploration. The following example
+shows how to ask Gemini CLI to fetch, analyze, and summarize a remote project.
+
+Scenario: You want to understand how a popular open-source utility works by
+inspecting its code, not just its README.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
+```
+
+Result: Gemini performs a sequence of actions to answer your request.
+
+1.  First, it asks for permission to run `git clone` to download the repository.
+2.  Next, it finds the important source files and asks for permission to read
+    them.
+3.  Finally, after analyzing the code, it provides a summary.
+
+Gemini CLI returns an explanation based on the actual source code:
+
+```markdown
+The `chalk` library is a popular npm package for styling terminal output with
+colors. After analyzing the source code, here's how it works:
+
+- **Core functionality:** The main file sets up a chainable API. Each color or
+  modifier (like `bold` or `italic`) is a getter that appends the corresponding
+  ANSI escape code to an internal stack.
+
+- **Chainable API:** When you call `chalk.red.bold('Hello')`, you are accessing
+  getters. The `red` getter adds the red color code, and the `bold` getter adds
+  the bold code.
+
+- **Output generation:** When the chain is treated as a string (e.g., in
+  `console.log`), a final `toString()` method is called. This method joins all
+  the stored ANSI codes, wraps them around the input string ('Hello'), and adds
+  a reset code at the end. This produces the final, styled string that the
+  terminal can render.
+```
+
+### Combine two spreadsheets into one spreadsheet
+
+Gemini CLI can process and transform data across multiple files. Use this
+capability to merge reports or reformat data sets without manual copying.
+
+Scenario: You have two .csv files: `Revenue - 2023.csv` and
+`Revenue - 2024.csv`. Each file contains monthly revenue figures.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Combine the two .csv files into a single .csv file, with each year a different column.
+```
+
+Result: Gemini CLI reads each file and then asks for permission to write a new
+file. Provide your permission and Gemini CLI provides the combined data:
+
+```csv
+Month,2023,2024
+January,0,1000
+February,0,1200
+March,0,2400
+April,900,500
+May,1000,800
+June,1000,900
+July,1200,1000
+August,1800,400
+September,2000,2000
+October,2400,3400
+November,3400,1800
+December,2100,9000
+```
+
+### Run unit tests
+
+Gemini CLI can generate boilerplate code and tests based on your existing
+implementation. This example demonstrates how to request code coverage for a
+JavaScript component.
+
+Scenario: You've written a simple login page. You wish to write unit tests to
+ensure that your login page has code coverage.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Write unit tests for Login.js.
+```
+
+Result: Gemini CLI asks for permission to write a new file and creates a test
+for your login page.
 
 ## Check usage and quota
 

docs/ide-integration/index.md

@@ -1,15 +1,29 @@
-# IDE integration
+# IDE Integration
 
 Gemini CLI can integrate with your IDE to provide a more seamless and
 context-aware experience. This integration allows the CLI to understand your
 workspace better and enables powerful features like native in-editor diffing.
 
-Currently, the supported IDEs are [Antigravity](https://antigravity.google),
-[Visual Studio Code](https://code.visualstudio.com/), and other editors that
-support VS Code extensions. To build support for other editors, see the
-[IDE Companion Extension Spec](./ide-companion-spec.md).
+There are two primary ways to integrate Gemini CLI with an IDE:
 
-## Features
+1.  **VS Code companion extension**: Install the "Gemini CLI Companion"
+    extension on [Antigravity](https://antigravity.google),
+    [Visual Studio Code](https://code.visualstudio.com/), or other VS Code
+    compatible editors.
+2.  **Agent Client Protocol (ACP)**: An open protocol for interoperability
+    between AI coding agents and IDEs. This method is used for integrations with
+    tools like JetBrains and Zed, which leverage the ACP Agent Registry for easy
+    discovery and installation of compatible agents like Gemini CLI.
+
+## VS Code companion extension
+
+The **Gemini CLI Companion extension** grants Gemini CLI direct access to your
+VS Code compatible IDEs and improves your experience by providing real-time
+context such as open files, cursor positions, and text selection. The extension
+also enables a native diffing interface so you can seamlessly review and apply
+AI-generated code changes directly within your editor.
+
+### Features
 
 - **Workspace context:** The CLI automatically gains awareness of your workspace
   to provide more relevant and accurate responses. This context includes:
@@ -19,8 +33,8 @@ support VS Code extensions. To build support for other editors, see the
     truncated).
 
 - **Native diffing:** When Gemini suggests code modifications, you can view the
-  changes directly within your IDE's native diff viewer. This allows you to
-  review, edit, and accept or reject the suggested changes seamlessly.
+  changes directly within your IDE's native diff viewer. This lets you review,
+  edit, and accept or reject the suggested changes seamlessly.
 
 - **VS Code commands:** You can access Gemini CLI features directly from the VS
   Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`):
@@ -32,18 +46,18 @@ support VS Code extensions. To build support for other editors, see the
   - `Gemini CLI: View Third-Party Notices`: Displays the third-party notices for
     the extension.
 
-## Installation and setup
+### Installation and setup
 
 There are three ways to set up the IDE integration:
 
-### 1. Automatic nudge (recommended)
+#### 1. Automatic nudge (recommended)
 
 When you run Gemini CLI inside a supported editor, it will automatically detect
 your environment and prompt you to connect. Answering "Yes" will automatically
 run the necessary setup, which includes installing the companion extension and
 enabling the connection.
 
-### 2. Manual installation from CLI
+#### 2. Manual installation from CLI
 
 If you previously dismissed the prompt or want to install the extension
 manually, you can run the following command inside Gemini CLI:
@@ -54,7 +68,7 @@ manually, you can run the following command inside Gemini CLI:
 
 This will find the correct extension for your IDE and install it.
 
-### 3. Manual installation from a marketplace
+#### 3. Manual installation from a marketplace
 
 You can also install the extension directly from a marketplace.
 
@@ -75,9 +89,9 @@ You can also install the extension directly from a marketplace.
 > After manually installing the extension, you must run `/ide enable` in the CLI
 > to activate the integration.
 
-## Usage
+### Usage
 
-### Enabling and disabling
+#### Enabling and disabling
 
 You can control the IDE integration from within the CLI:
 
@@ -93,7 +107,7 @@ You can control the IDE integration from within the CLI:
 When enabled, Gemini CLI will automatically attempt to connect to the IDE
 companion extension.
 
-### Checking the status
+#### Checking the status
 
 To check the connection status and see the context the CLI has received from the
 IDE, run:
@@ -108,9 +122,9 @@ recently opened files it is aware of.
 <!-- prettier-ignore -->
 > [!NOTE]
 > The file list is limited to 10 recently accessed files within your
-> workspace and only includes local files on disk.)
+> workspace and only includes local files on disk.
 
-### Working with diffs
+#### Working with diffs
 
 When you ask Gemini to modify a file, it can open a diff view directly in your
 editor.
@@ -135,6 +149,63 @@ accepting them.
 If you select ‘Allow for this session’ in the CLI, changes will no longer show
 up in the IDE as they will be auto-accepted.
 
+## Agent Client Protocol (ACP)
+
+ACP is an open protocol that standardizes how AI coding agents communicate with
+code editors and IDEs. It addresses the challenge of fragmented distribution,
+where agents traditionally needed custom integrations for each client. With ACP,
+developers can implement their agent once, and it becomes compatible with any
+ACP-compliant editor.
+
+For a comprehensive introduction to ACP, including its architecture and
+benefits, refer to the official
+[ACP Introduction](https://agentclientprotocol.com/get-started/introduction)
+documentation.
+
+### The ACP Agent Registry
+
+Gemini CLI is officially available in the **ACP Agent Registry**. This allows
+you to install and update Gemini CLI directly within supporting IDEs and
+eliminates the need for manual downloads or IDE-specific extensions.
+
+Using the registry ensures:
+
+- **Ease of use**: Discover and install agents directly within your IDE
+  settings.
+- **Latest versions**: Ensures users always have access to the most up-to-date
+  agent implementations.
+
+For more details on how the registry works, visit the official
+[ACP Agent Registry](https://agentclientprotocol.com/get-started/registry) page.
+You can learn about how specific IDEs leverage this integration in the following
+section.
+
+### IDE-specific integration
+
+Gemini CLI is an ACP-compatible agent available in the ACP Agent Registry.
+Here’s how different IDEs leverage the ACP and the registry:
+
+#### JetBrains IDEs
+
+JetBrains IDEs (like IntelliJ IDEA, PyCharm, or GoLand) offer built-in registry
+support, allowing users to find and install ACP-compatible agents directly.
+
+For more details, refer to the official
+[JetBrains AI Blog announcement](https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/).
+
+#### Zed
+
+Zed, a modern code editor, also integrates with the ACP Agent Registry. This
+allows Zed users to easily browse, install, and manage ACP agents.
+
+Learn more about Zed's integration with the ACP Registry in their
+[blog post](https://zed.dev/blog/acp-registry).
+
+#### Other ACP-compatible IDEs
+
+Any other IDE that supports the ACP Agent Registry can install Gemini CLI
+directly through their in-built registry features.
+
 ## Using with sandboxing
 
 If you are using Gemini CLI within a sandbox, please be aware of the following:
@@ -151,10 +222,9 @@ If you are using Gemini CLI within a sandbox, please be aware of the following:
 
 ## Troubleshooting
 
-If you encounter issues with IDE integration, here are some common error
-messages and how to resolve them.
+### VS Code companion extension errors
 
-### Connection errors
+#### Connection errors
 
 - **Message:**
   `🔴 Disconnected: Failed to connect to IDE companion extension in [IDE Name]. Please ensure the extension is running. To install the extension, run /ide install.`
@@ -174,7 +244,7 @@ messages and how to resolve them.
   - **Solution:** Run `/ide enable` to try and reconnect. If the issue
     continues, open a new terminal window or restart your IDE.
 
-### Manual PID override
+#### Manual PID override
 
 If automatic IDE detection fails, or if you are running Gemini CLI in a
 standalone terminal and want to manually associate it with a specific IDE
@@ -196,7 +266,7 @@ $env:GEMINI_CLI_IDE_PID=12345
 When this variable is set, Gemini CLI will skip automatic detection and attempt
 to connect using the provided PID.
 
-### Configuration errors
+#### Configuration errors
 
 - **Message:**
   `🔴 Disconnected: Directory mismatch. Gemini CLI is running in a different location than the open workspace in [IDE Name]. Please run the CLI from one of the following directories: [List of directories]`
@@ -210,7 +280,7 @@ to connect using the provided PID.
   - **Cause:** You have no workspace open in your IDE.
   - **Solution:** Open a workspace in your IDE and restart the CLI.
 
-### General errors
+#### General errors
 
 - **Message:**
   `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]`
@@ -220,9 +290,14 @@ to connect using the provided PID.
     IDE, like Antigravity or VS Code.
 
 - **Message:**
-  `No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.`
+  `No installer is available for IDE. Please install Gemini CLI Companion extension manually from the marketplace.`
   - **Cause:** You ran `/ide install`, but the CLI does not have an automated
     installer for your specific IDE.
   - **Solution:** Open your IDE's extension marketplace, search for "Gemini CLI
     Companion", and
     [install it manually](#3-manual-installation-from-a-marketplace).
+
+### ACP integration errors
+
+For issues related to ACP integration, please refer to the debugging and
+telemetry section in the [ACP Mode](../cli/acp-mode.md) documentation.

docs/index.md

@@ -19,8 +19,6 @@ Jump in to Gemini CLI.
   on your system.
 - **[Authentication](./get-started/authentication.md):** Setup instructions for
   personal and enterprise accounts.
-- **[Examples](./get-started/examples.md):** Practical examples of Gemini CLI in
-  action.
 - **[CLI cheatsheet](./cli/cli-reference.md):** A quick reference for common
   commands and options.
 - **[Gemini 3 on Gemini CLI](./get-started/gemini-3.md):** Learn about Gemini 3

docs/redirects.json

@@ -13,6 +13,7 @@
   "/docs/faq": "/docs/resources/faq",
   "/docs/get-started/configuration": "/docs/reference/configuration",
   "/docs/get-started/configuration-v1": "/docs/reference/configuration",
+  "/docs/get-started/examples": "/docs/get-started/index",
   "/docs/index": "/docs",
   "/docs/quota-and-pricing": "/docs/resources/quota-and-pricing",
   "/docs/tos-privacy": "/docs/resources/tos-privacy",

docs/reference/configuration.md

@@ -133,7 +133,7 @@ their corresponding top-level category object in your `settings.json` file.
 
 - **`general.enableNotifications`** (boolean):
   - **Description:** Enable run-event notifications for action-required prompts
-    and session completion. Currently macOS only.
+    and session completion.
   - **Default:** `false`
 
 - **`general.checkpointing.enabled`** (boolean):
@@ -2160,37 +2160,14 @@ You can customize this behavior in your `settings.json` file:
 Arguments passed directly when running the CLI can override other configurations
 for that specific session.
 
-- **`--model <model_name>`** (**`-m <model_name>`**):
-  - Specifies the Gemini model to use for this session.
-  - Example: `npm start -- --model gemini-3-pro-preview`
-- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
-  - **Deprecated:** Use positional arguments instead.
-  - Used to pass a prompt directly to the command. This invokes Gemini CLI in a
-    non-interactive mode.
-- **`--prompt-interactive <your_prompt>`** (**`-i <your_prompt>`**):
-  - Starts an interactive session with the provided prompt as the initial input.
-  - The prompt is processed within the interactive session, not before it.
-  - Cannot be used when piping input from stdin.
-  - Example: `gemini -i "explain this code"`
-- **`--output-format <format>`**:
-  - **Description:** Specifies the format of the CLI output for non-interactive
-    mode.
-  - **Values:**
-    - `text`: (Default) The standard human-readable output.
-    - `json`: A machine-readable JSON output.
-    - `stream-json`: A streaming JSON output that emits real-time events.
-  - **Note:** For structured output and scripting, use the
-    `--output-format json` or `--output-format stream-json` flag.
-- **`--sandbox`** (**`-s`**):
-  - Enables sandbox mode for this session.
-- **`--debug`** (**`-d`**):
-  - Enables debug mode for this session, providing more verbose output. Open the
-    debug console with F12 to see the additional logging.
-
-- **`--help`** (or **`-h`**):
-  - Displays help information about command-line arguments.
-- **`--yolo`**:
-  - Enables YOLO mode, which automatically approves all tool calls.
+- **`--acp`**:
+  - Starts the agent in Agent Communication Protocol (ACP) mode.
+- **`--allowed-mcp-server-names`**:
+  - A comma-separated list of MCP server names to allow for the session.
+- **`--allowed-tools <tool1,tool2,...>`**:
+  - A comma-separated list of tool names that will bypass the confirmation
+    dialog.
+  - Example: `gemini --allowed-tools "ShellTool(git status)"`
 - **`--approval-mode <mode>`**:
   - Sets the approval mode for tool calls. Available modes:
     - `default`: Prompt for approval on each tool call (default behavior)
@@ -2204,35 +2181,24 @@ for that specific session.
   - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of
     `--yolo` for the new unified approach.
   - Example: `gemini --approval-mode auto_edit`
-- **`--allowed-tools <tool1,tool2,...>`**:
-  - A comma-separated list of tool names that will bypass the confirmation
-    dialog.
-  - Example: `gemini --allowed-tools "ShellTool(git status)"`
-- **`--extensions <extension_name ...>`** (**`-e <extension_name ...>`**):
-  - Specifies a list of extensions to use for the session. If not provided, all
-    available extensions are used.
-  - Use the special term `gemini -e none` to disable all extensions.
-  - Example: `gemini -e my-extension -e my-other-extension`
-- **`--list-extensions`** (**`-l`**):
-  - Lists all available extensions and exits.
-- **`--resume [session_id]`** (**`-r [session_id]`**):
-  - Resume a previous chat session. Use "latest" for the most recent session,
-    provide a session index number, or provide a full session UUID.
-  - If no session_id is provided, defaults to "latest".
-  - Example: `gemini --resume 5` or `gemini --resume latest` or
-    `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume`
-  - See [Session Management](../cli/session-management.md) for more details.
-- **`--list-sessions`**:
-  - List all available chat sessions for the current project and exit.
-  - Shows session indices, dates, message counts, and preview of first user
-    message.
-  - Example: `gemini --list-sessions`
+- **`--debug`** (**`-d`**):
+  - Enables debug mode for this session, providing more verbose output. Open the
+    debug console with F12 to see the additional logging.
 - **`--delete-session <identifier>`**:
   - Delete a specific chat session by its index number or full session UUID.
   - Use `--list-sessions` first to see available sessions, their indices, and
     UUIDs.
   - Example: `gemini --delete-session 3` or
     `gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890`
+- **`--extensions <extension_name ...>`** (**`-e <extension_name ...>`**):
+  - Specifies a list of extensions to use for the session. If not provided, all
+    available extensions are used.
+  - Use the special term `gemini -e none` to disable all extensions.
+  - Example: `gemini -e my-extension -e my-other-extension`
+- **`--fake-responses`**:
+  - Path to a file with fake model responses for testing.
+- **`--help`** (or **`-h`**):
+  - Displays help information about command-line arguments.
 - **`--include-directories <dir1,dir2,...>`**:
   - Includes additional directories in the workspace for multi-directory
     support.
@@ -2240,19 +2206,52 @@ for that specific session.
   - 5 directories can be added at maximum.
   - Example: `--include-directories /path/to/project1,/path/to/project2` or
     `--include-directories /path/to/project1 --include-directories /path/to/project2`
+- **`--list-extensions`** (**`-l`**):
+  - Lists all available extensions and exits.
+- **`--list-sessions`**:
+  - List all available chat sessions for the current project and exit.
+  - Shows session indices, dates, message counts, and preview of first user
+    message.
+  - Example: `gemini --list-sessions`
+- **`--model <model_name>`** (**`-m <model_name>`**):
+  - Specifies the Gemini model to use for this session.
+  - Example: `npm start -- --model gemini-3-pro-preview`
+- **`--output-format <format>`**:
+  - **Description:** Specifies the format of the CLI output for non-interactive
+    mode.
+  - **Values:**
+    - `text`: (Default) The standard human-readable output.
+    - `json`: A machine-readable JSON output.
+    - `stream-json`: A streaming JSON output that emits real-time events.
+  - **Note:** For structured output and scripting, use the
+    `--output-format json` or `--output-format stream-json` flag.
+- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
+  - **Deprecated:** Use positional arguments instead.
+  - Used to pass a prompt directly to the command. This invokes Gemini CLI in a
+    non-interactive mode.
+- **`--prompt-interactive <your_prompt>`** (**`-i <your_prompt>`**):
+  - Starts an interactive session with the provided prompt as the initial input.
+  - The prompt is processed within the interactive session, not before it.
+  - Cannot be used when piping input from stdin.
+  - Example: `gemini -i "explain this code"`
+- **`--record-responses`**:
+  - Path to a file to record model responses for testing.
+- **`--resume [session_id]`** (**`-r [session_id]`**):
+  - Resume a previous chat session. Use "latest" for the most recent session,
+    provide a session index number, or provide a full session UUID.
+  - If no session_id is provided, defaults to "latest".
+  - Example: `gemini --resume 5` or `gemini --resume latest` or
+    `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume`
+  - See [Session Management](../cli/session-management.md) for more details.
+- **`--sandbox`** (**`-s`**):
+  - Enables sandbox mode for this session.
 - **`--screen-reader`**:
   - Enables screen reader mode, which adjusts the TUI for better compatibility
     with screen readers.
 - **`--version`**:
   - Displays the version of the CLI.
-- **`--experimental-acp`**:
-  - Starts the agent in ACP mode.
-- **`--allowed-mcp-server-names`**:
-  - Allowed MCP server names.
-- **`--fake-responses`**:
-  - Path to a file with fake model responses for testing.
-- **`--record-responses`**:
-  - Path to a file to record model responses for testing.
+- **`--yolo`**:
+  - Enables YOLO mode, which automatically approves all tool calls.
 
 ## Context files (hierarchical instructional context)
 

docs/resources/quota-and-pricing.md

@@ -12,6 +12,21 @@ quota for your needs, see the [Plans page](https://geminicli.com/plans/).
 This article outlines the specific quotas and pricing applicable to Gemini CLI
 when using different authentication methods.
 
+The following table summarizes the available quotas and their respective limits:
+
+| Authentication method | Tier / Subscription             | Maximum requests per user per day |
+| :-------------------- | :------------------------------ | :-------------------------------- |
+| **Google account**    | Gemini Code Assist (Individual) | 1,000 requests                    |
+|                       | Google AI Pro                   | 1,500 requests                    |
+|                       | Google AI Ultra                 | 2,000 requests                    |
+| **Gemini API key**    | Free tier (Unpaid)              | 250 requests                      |
+|                       | Pay-as-you-go (Paid)            | Varies                            |
+| **Vertex AI**         | Express mode (Free)             | Varies                            |
+|                       | Pay-as-you-go (Paid)            | Varies                            |
+| **Google Workspace**  | Code Assist Standard            | 1,500 requests                    |
+|                       | Code Assist Enterprise          | 2,000 requests                    |
+|                       | Workspace AI Ultra              | 2,000 requests                    |
+
 Generally, there are three categories to choose from:
 
 - Free Usage: Ideal for experimentation and light use.
@@ -20,6 +35,9 @@ Generally, there are three categories to choose from:
 - Pay-As-You-Go: The most flexible option for professional use, long-running
   tasks, or when you need full control over your usage.
 
+Requests are limited per user per minute and are subject to the availability of
+the service in times of high demand.
+
 ## Free usage
 
 Access to Gemini CLI begins with a generous free tier, perfect for
@@ -33,8 +51,7 @@ authorization type.
 For users who authenticate by using their Google account to access Gemini Code
 Assist for individuals. This includes:
 
-- 1000 model requests / user / day
-- 60 model requests / user / minute
+- 1000 maximum model requests / user / day
 - Model requests will be made across the Gemini model family as determined by
   Gemini CLI.
 
@@ -46,8 +63,7 @@ Learn more at
 If you are using a Gemini API key, you can also benefit from a free tier. This
 includes:
 
-- 250 model requests / user / day
-- 10 model requests / user / minute
+- 250 maximum model requests / user / day
 - Model requests to Flash model only.
 
 Learn more at
@@ -59,7 +75,7 @@ Vertex AI offers an Express Mode without the need to enable billing. This
 includes:
 
 - 90 days before you need to enable billing.
-- Quotas and models are variable and specific to your account.
+- Quotas and models are specific to your account and their limits vary.
 
 Learn more at
 [Vertex AI Express Mode Limits](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview#quotas).
@@ -112,11 +128,9 @@ Standard/Plus and AI Expanded, are not supported._
 
   This includes the following request limits:
   - Gemini Code Assist Standard edition:
-    - 1500 model requests / user / day
-    - 120 model requests / user / minute
+    - 1500 maximum model requests / user / day
   - Gemini Code Assist Enterprise edition:
-    - 2000 model requests / user / day
-    - 120 model requests / user / minute
+    - 2000 maximum model requests / user / day
   - Model requests will be made across the Gemini model family as determined by
     Gemini CLI.
 

docs/sidebar.json

@@ -12,7 +12,6 @@
             "label": "Authentication",
             "slug": "docs/get-started/authentication"
           },
-          { "label": "Examples", "slug": "docs/get-started/examples" },
           { "label": "CLI cheatsheet", "slug": "docs/cli/cli-reference" },
           {
             "label": "Gemini 3 on Gemini CLI",
@@ -112,7 +111,17 @@
               { "label": "Reference", "slug": "docs/hooks/reference" }
             ]
           },
-          { "label": "IDE integration", "slug": "docs/ide-integration" },
+          {
+            "label": "IDE integration",
+            "collapsed": true,
+            "items": [
+              { "label": "Overview", "slug": "docs/ide-integration" },
+              {
+                "label": "Developer guide: ACP mode",
+                "slug": "docs/cli/acp-mode"
+              }
+            ]
+          },
           { "label": "MCP servers", "slug": "docs/tools/mcp-server" },
           { "label": "Model routing", "slug": "docs/cli/model-routing" },
           { "label": "Model selection", "slug": "docs/cli/model" },

evals/test-helper.test.ts

@@ -0,0 +1,207 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { internalEvalTest } from './test-helper.js';
+import { TestRig } from '@google/gemini-cli-test-utils';
+
+// Mock TestRig to control API success/failure
+vi.mock('@google/gemini-cli-test-utils', () => {
+  return {
+    TestRig: vi.fn().mockImplementation(() => ({
+      setup: vi.fn(),
+      run: vi.fn(),
+      cleanup: vi.fn(),
+      readToolLogs: vi.fn().mockReturnValue([]),
+      _lastRunStderr: '',
+    })),
+  };
+});
+
+describe('evalTest reliability logic', () => {
+  const LOG_DIR = path.resolve(process.cwd(), 'evals/logs');
+  const RELIABILITY_LOG = path.join(LOG_DIR, 'api-reliability.jsonl');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    if (fs.existsSync(RELIABILITY_LOG)) {
+      fs.unlinkSync(RELIABILITY_LOG);
+    }
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(RELIABILITY_LOG)) {
+      fs.unlinkSync(RELIABILITY_LOG);
+    }
+  });
+
+  it('should retry 3 times on 500 INTERNAL error and then SKIP', async () => {
+    const mockRig = new TestRig() as any;
+    (TestRig as any).mockReturnValue(mockRig);
+
+    // Simulate permanent 500 error
+    mockRig.run.mockRejectedValue(new Error('status: INTERNAL - API Down'));
+
+    // Execute the test function directly
+    await internalEvalTest({
+      name: 'test-api-failure',
+      prompt: 'do something',
+      assert: async () => {},
+    });
+
+    // Verify retries: 1 initial + 3 retries = 4 setups/runs
+    expect(mockRig.run).toHaveBeenCalledTimes(4);
+
+    // Verify log content
+    const logContent = fs
+      .readFileSync(RELIABILITY_LOG, 'utf-8')
+      .trim()
+      .split('\n');
+    expect(logContent.length).toBe(4);
+
+    const entries = logContent.map((line) => JSON.parse(line));
+    expect(entries[0].status).toBe('RETRY');
+    expect(entries[0].attempt).toBe(0);
+    expect(entries[3].status).toBe('SKIP');
+    expect(entries[3].attempt).toBe(3);
+    expect(entries[3].testName).toBe('test-api-failure');
+  });
+
+  it('should fail immediately on non-500 errors (like assertion failures)', async () => {
+    const mockRig = new TestRig() as any;
+    (TestRig as any).mockReturnValue(mockRig);
+
+    // Simulate a real logic error/bug
+    mockRig.run.mockResolvedValue('Success');
+    const assertError = new Error('Assertion failed: expected foo to be bar');
+
+    // Expect the test function to throw immediately
+    await expect(
+      internalEvalTest({
+        name: 'test-logic-failure',
+        prompt: 'do something',
+        assert: async () => {
+          throw assertError;
+        },
+      }),
+    ).rejects.toThrow('Assertion failed');
+
+    // Verify NO retries: only 1 attempt
+    expect(mockRig.run).toHaveBeenCalledTimes(1);
+
+    // Verify NO reliability log was created (it's not an API error)
+    expect(fs.existsSync(RELIABILITY_LOG)).toBe(false);
+  });
+
+  it('should recover if a retry succeeds', async () => {
+    const mockRig = new TestRig() as any;
+    (TestRig as any).mockReturnValue(mockRig);
+
+    // Fail once, then succeed
+    mockRig.run
+      .mockRejectedValueOnce(new Error('status: INTERNAL'))
+      .mockResolvedValueOnce('Success');
+
+    await internalEvalTest({
+      name: 'test-recovery',
+      prompt: 'do something',
+      assert: async () => {},
+    });
+
+    // Ran twice: initial (fail) + retry 1 (success)
+    expect(mockRig.run).toHaveBeenCalledTimes(2);
+
+    // Log should only have the one RETRY entry
+    const logContent = fs
+      .readFileSync(RELIABILITY_LOG, 'utf-8')
+      .trim()
+      .split('\n');
+    expect(logContent.length).toBe(1);
+    expect(JSON.parse(logContent[0]).status).toBe('RETRY');
+  });
+
+  it('should retry 3 times on 503 UNAVAILABLE error and then SKIP', async () => {
+    const mockRig = new TestRig() as any;
+    (TestRig as any).mockReturnValue(mockRig);
+
+    // Simulate permanent 503 error
+    mockRig.run.mockRejectedValue(
+      new Error('status: UNAVAILABLE - Service Busy'),
+    );
+
+    await internalEvalTest({
+      name: 'test-api-503',
+      prompt: 'do something',
+      assert: async () => {},
+    });
+
+    expect(mockRig.run).toHaveBeenCalledTimes(4);
+
+    const logContent = fs
+      .readFileSync(RELIABILITY_LOG, 'utf-8')
+      .trim()
+      .split('\n');
+    const entries = logContent.map((line) => JSON.parse(line));
+    expect(entries[0].errorCode).toBe('503');
+    expect(entries[3].status).toBe('SKIP');
+  });
+
+  it('should throw if an absolute path is used in files', async () => {
+    const mockRig = new TestRig() as any;
+    (TestRig as any).mockReturnValue(mockRig);
+    mockRig.testDir = path.resolve(process.cwd(), 'test-dir-tmp');
+    if (!fs.existsSync(mockRig.testDir)) {
+      fs.mkdirSync(mockRig.testDir, { recursive: true });
+    }
+
+    try {
+      await expect(
+        internalEvalTest({
+          name: 'test-absolute-path',
+          prompt: 'do something',
+          files: {
+            '/etc/passwd': 'hacked',
+          },
+          assert: async () => {},
+        }),
+      ).rejects.toThrow('Invalid file path in test case: /etc/passwd');
+    } finally {
+      if (fs.existsSync(mockRig.testDir)) {
+        fs.rmSync(mockRig.testDir, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it('should throw if directory traversal is detected in files', async () => {
+    const mockRig = new TestRig() as any;
+    (TestRig as any).mockReturnValue(mockRig);
+    mockRig.testDir = path.resolve(process.cwd(), 'test-dir-tmp');
+
+    // Create a mock test-dir
+    if (!fs.existsSync(mockRig.testDir)) {
+      fs.mkdirSync(mockRig.testDir, { recursive: true });
+    }
+
+    try {
+      await expect(
+        internalEvalTest({
+          name: 'test-traversal',
+          prompt: 'do something',
+          files: {
+            '../sensitive.txt': 'hacked',
+          },
+          assert: async () => {},
+        }),
+      ).rejects.toThrow('Invalid file path in test case: ../sensitive.txt');
+    } finally {
+      if (fs.existsSync(mockRig.testDir)) {
+        fs.rmSync(mockRig.testDir, { recursive: true, force: true });
+      }
+    }
+  });
+});

evals/test-helper.ts

@@ -39,87 +39,34 @@ export * from '@google/gemini-cli-test-utils';
 export type EvalPolicy = 'ALWAYS_PASSES' | 'USUALLY_PASSES';
 
 export function evalTest(policy: EvalPolicy, evalCase: EvalCase) {
-  const fn = async () => {
+  runEval(
+    policy,
+    evalCase.name,
+    () => internalEvalTest(evalCase),
+    evalCase.timeout,
+  );
+}
+
+export async function internalEvalTest(evalCase: EvalCase) {
+  const maxRetries = 3;
+  let attempt = 0;
+
+  while (attempt <= maxRetries) {
     const rig = new TestRig();
     const { logDir, sanitizedName } = await prepareLogDir(evalCase.name);
     const activityLogFile = path.join(logDir, `${sanitizedName}.jsonl`);
     const logFile = path.join(logDir, `${sanitizedName}.log`);
     let isSuccess = false;
+
     try {
       rig.setup(evalCase.name, evalCase.params);
 
-      // Symlink node modules to reduce the amount of time needed to
-      // bootstrap test projects.
-      symlinkNodeModules(rig.testDir || '');
-
       if (evalCase.files) {
-        const acknowledgedAgents: Record<string, Record<string, string>> = {};
-        const projectRoot = fs.realpathSync(rig.testDir!);
-
-        for (const [filePath, content] of Object.entries(evalCase.files)) {
-          const fullPath = path.join(rig.testDir!, filePath);
-          fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-          fs.writeFileSync(fullPath, content);
-
-          // If it's an agent file, calculate hash for acknowledgement
-          if (
-            filePath.startsWith('.gemini/agents/') &&
-            filePath.endsWith('.md')
-          ) {
-            const hash = crypto
-              .createHash('sha256')
-              .update(content)
-              .digest('hex');
-
-            try {
-              const agentDefs = await parseAgentMarkdown(fullPath, content);
-              if (agentDefs.length > 0) {
-                const agentName = agentDefs[0].name;
-                if (!acknowledgedAgents[projectRoot]) {
-                  acknowledgedAgents[projectRoot] = {};
-                }
-                acknowledgedAgents[projectRoot][agentName] = hash;
-              }
-            } catch (error) {
-              console.warn(
-                `Failed to parse agent for test acknowledgement: ${filePath}`,
-                error,
-              );
-            }
-          }
-        }
-
-        // Write acknowledged_agents.json to the home directory
-        if (Object.keys(acknowledgedAgents).length > 0) {
-          const ackPath = path.join(
-            rig.homeDir!,
-            '.gemini',
-            'acknowledgments',
-            'agents.json',
-          );
-          fs.mkdirSync(path.dirname(ackPath), { recursive: true });
-          fs.writeFileSync(
-            ackPath,
-            JSON.stringify(acknowledgedAgents, null, 2),
-          );
-        }
-
-        const execOptions = { cwd: rig.testDir!, stdio: 'inherit' as const };
-        execSync('git init', execOptions);
-        execSync('git config user.email "test@example.com"', execOptions);
-        execSync('git config user.name "Test User"', execOptions);
-
-        // Temporarily disable the interactive editor and git pager
-        // to avoid hanging the tests. It seems the the agent isn't
-        // consistently honoring the instructions to avoid interactive
-        // commands.
-        execSync('git config core.editor "true"', execOptions);
-        execSync('git config core.pager "cat"', execOptions);
-        execSync('git config commit.gpgsign false', execOptions);
-        execSync('git add .', execOptions);
-        execSync('git commit --allow-empty -m "Initial commit"', execOptions);
+        await setupTestFiles(rig, evalCase.files);
       }
 
+      symlinkNodeModules(rig.testDir || '');
+
       // If messages are provided, write a session file so --resume can load it.
       let sessionId: string | undefined;
       if (evalCase.messages) {
@@ -188,6 +135,37 @@ export function evalTest(policy: EvalPolicy, evalCase: EvalCase) {
 
       await evalCase.assert(rig, result);
       isSuccess = true;
+      return; // Success! Exit the retry loop.
+    } catch (error: unknown) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      const errorCode = getApiErrorCode(errorMessage);
+
+      if (errorCode) {
+        const status = attempt < maxRetries ? 'RETRY' : 'SKIP';
+        logReliabilityEvent(
+          evalCase.name,
+          attempt,
+          status,
+          errorCode,
+          errorMessage,
+        );
+
+        if (attempt < maxRetries) {
+          attempt++;
+          console.warn(
+            `[Eval] Attempt ${attempt} failed with ${errorCode} Error. Retrying...`,
+          );
+          continue; // Retry
+        }
+
+        console.warn(
+          `[Eval] '${evalCase.name}' failed after ${maxRetries} retries due to persistent API errors. Skipping failure to avoid blocking PR.`,
+        );
+        return; // Gracefully exit without failing the test
+      }
+
+      throw error; // Real failure
     } finally {
       if (isSuccess) {
         await fs.promises.unlink(activityLogFile).catch((err) => {
@@ -206,9 +184,131 @@ export function evalTest(policy: EvalPolicy, evalCase: EvalCase) {
       );
       await rig.cleanup();
     }
+  }
+}
+
+function getApiErrorCode(message: string): '500' | '503' | undefined {
+  if (
+    message.includes('status: UNAVAILABLE') ||
+    message.includes('code: 503') ||
+    message.includes('Service Unavailable')
+  ) {
+    return '503';
+  }
+  if (
+    message.includes('status: INTERNAL') ||
+    message.includes('code: 500') ||
+    message.includes('Internal error encountered')
+  ) {
+    return '500';
+  }
+  return undefined;
+}
+
+/**
+ * Log reliability event for later harvesting.
+ *
+ * Note: Uses synchronous file I/O to ensure the log is persisted even if the
+ * test process is abruptly terminated by a timeout or CI crash. Performance
+ * impact is negligible compared to long-running evaluation tests.
+ */
+function logReliabilityEvent(
+  testName: string,
+  attempt: number,
+  status: 'RETRY' | 'SKIP',
+  errorCode: '500' | '503',
+  errorMessage: string,
+) {
+  const reliabilityLog = {
+    timestamp: new Date().toISOString(),
+    testName,
+    model: process.env.GEMINI_MODEL || 'unknown',
+    attempt,
+    status,
+    errorCode,
+    error: errorMessage,
   };
 
-  runEval(policy, evalCase.name, fn, evalCase.timeout);
+  try {
+    const relDir = path.resolve(process.cwd(), 'evals/logs');
+    fs.mkdirSync(relDir, { recursive: true });
+    fs.appendFileSync(
+      path.join(relDir, 'api-reliability.jsonl'),
+      JSON.stringify(reliabilityLog) + '\n',
+    );
+  } catch (logError) {
+    console.error('Failed to write reliability log:', logError);
+  }
+}
+
+/**
+ * Helper to setup test files and git repository.
+ *
+ * Note: While this is an async function (due to parseAgentMarkdown), it
+ * intentionally uses synchronous filesystem and child_process operations
+ * for simplicity and to ensure sequential environment preparation.
+ */
+async function setupTestFiles(rig: TestRig, files: Record<string, string>) {
+  const acknowledgedAgents: Record<string, Record<string, string>> = {};
+  const projectRoot = fs.realpathSync(rig.testDir!);
+
+  for (const [filePath, content] of Object.entries(files)) {
+    if (filePath.includes('..') || path.isAbsolute(filePath)) {
+      throw new Error(`Invalid file path in test case: ${filePath}`);
+    }
+    const fullPath = path.join(projectRoot, filePath);
+    if (!fullPath.startsWith(projectRoot)) {
+      throw new Error(`Path traversal detected: ${filePath}`);
+    }
+
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, content);
+
+    if (filePath.startsWith('.gemini/agents/') && filePath.endsWith('.md')) {
+      const hash = crypto.createHash('sha256').update(content).digest('hex');
+      try {
+        const agentDefs = await parseAgentMarkdown(fullPath, content);
+        if (agentDefs.length > 0) {
+          const agentName = agentDefs[0].name;
+          if (!acknowledgedAgents[projectRoot]) {
+            acknowledgedAgents[projectRoot] = {};
+          }
+          acknowledgedAgents[projectRoot][agentName] = hash;
+        }
+      } catch (error) {
+        console.warn(
+          `Failed to parse agent for test acknowledgement: ${filePath}`,
+          error,
+        );
+      }
+    }
+  }
+
+  if (Object.keys(acknowledgedAgents).length > 0) {
+    const ackPath = path.join(
+      rig.homeDir!,
+      '.gemini',
+      'acknowledgments',
+      'agents.json',
+    );
+    fs.mkdirSync(path.dirname(ackPath), { recursive: true });
+    fs.writeFileSync(ackPath, JSON.stringify(acknowledgedAgents, null, 2));
+  }
+
+  const execOptions = { cwd: rig.testDir!, stdio: 'inherit' as const };
+  execSync('git init --initial-branch=main', execOptions);
+  execSync('git config user.email "test@example.com"', execOptions);
+  execSync('git config user.name "Test User"', execOptions);
+
+  // Temporarily disable the interactive editor and git pager
+  // to avoid hanging the tests. It seems the the agent isn't
+  // consistently honoring the instructions to avoid interactive
+  // commands.
+  execSync('git config core.editor "true"', execOptions);
+  execSync('git config core.pager "cat"', execOptions);
+  execSync('git config commit.gpgsign false', execOptions);
+  execSync('git add .', execOptions);
+  execSync('git commit --allow-empty -m "Initial commit"', execOptions);
 }
 
 /**

evals/vitest.config.ts

@@ -16,10 +16,6 @@ export default defineConfig({
   },
   test: {
     testTimeout: 300000, // 5 minutes
-    // Retry in CI but not nightly to avoid blocking on API error.
-    retry: process.env['VITEST_RETRY']
-      ? parseInt(process.env['VITEST_RETRY'], 10)
-      : 3,
     reporters: ['default', 'json'],
     outputFile: {
       json: 'evals/logs/report.json',

integration-tests/extensions-reload.test.ts

@@ -10,13 +10,9 @@ import { TestMcpServer } from './test-mcp-server.js';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { safeJsonStringify } from '@google/gemini-cli-core/src/utils/safeJsonStringify.js';
-import { env } from 'node:process';
-import { platform } from 'node:os';
 
 import stripAnsi from 'strip-ansi';
 
-const itIf = (condition: boolean) => (condition ? it : it.skip);
-
 describe('extension reloading', () => {
   let rig: TestRig;
 
@@ -26,141 +22,130 @@ describe('extension reloading', () => {
 
   afterEach(async () => await rig.cleanup());
 
-  const sandboxEnv = env['GEMINI_SANDBOX'];
-  // Fails in linux non-sandbox e2e tests
+  // always fails
   // TODO(#14527): Re-enable this once fixed
-  // Fails in sandbox mode, can't check for local extension updates.
-  itIf(
-    (!sandboxEnv || sandboxEnv === 'false') &&
-      platform() !== 'win32' &&
-      platform() !== 'linux',
-  )(
-    'installs a local extension, updates it, checks it was reloaded properly',
-    async () => {
-      const serverA = new TestMcpServer();
-      const portA = await serverA.start({
-        hello: () => ({ content: [{ type: 'text', text: 'world' }] }),
-      });
-      const extension = {
-        name: 'test-extension',
-        version: '0.0.1',
-        mcpServers: {
-          'test-server': {
-            httpUrl: `http://localhost:${portA}/mcp`,
-          },
+  it.skip('installs a local extension, updates it, checks it was reloaded properly', async () => {
+    const serverA = new TestMcpServer();
+    const portA = await serverA.start({
+      hello: () => ({ content: [{ type: 'text', text: 'world' }] }),
+    });
+    const extension = {
+      name: 'test-extension',
+      version: '0.0.1',
+      mcpServers: {
+        'test-server': {
+          httpUrl: `http://localhost:${portA}/mcp`,
         },
-      };
+      },
+    };
 
-      rig.setup('extension reload test', {
-        settings: {
-          experimental: { extensionReloading: true },
-        },
-      });
-      const testServerPath = join(rig.testDir!, 'gemini-extension.json');
-      writeFileSync(testServerPath, safeJsonStringify(extension, 2));
-      // defensive cleanup from previous tests.
-      try {
-        await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
-      } catch {
-        /* empty */
-      }
-
-      const result = await rig.runCommand(
-        ['--debug', 'extensions', 'install', `${rig.testDir!}`],
-        { stdin: 'y\n' },
-      );
-      expect(result).toContain('test-extension');
-
-      // Now create the update, but its not installed yet
-      const serverB = new TestMcpServer();
-      const portB = await serverB.start({
-        goodbye: () => ({ content: [{ type: 'text', text: 'world' }] }),
-      });
-      extension.version = '0.0.2';
-      extension.mcpServers['test-server'].httpUrl =
-        `http://localhost:${portB}/mcp`;
-      writeFileSync(testServerPath, safeJsonStringify(extension, 2));
-
-      // Start the CLI.
-      const run = await rig.runInteractive({ args: '--debug' });
-      await run.expectText('You have 1 extension with an update available');
-      // See the outdated extension
-      await run.sendText('/extensions list');
-      await run.type('\r');
-      await run.expectText(
-        'test-extension (v0.0.1) - active (update available)',
-      );
-      // Wait for the UI to settle and retry the command until we see the update
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-
-      // Poll for the updated list
-      await rig.pollCommand(
-        async () => {
-          await run.sendText('/mcp list');
-          await run.type('\r');
-        },
-        () => {
-          const output = stripAnsi(run.output);
-          return (
-            output.includes(
-              'test-server (from test-extension) - Ready (1 tool)',
-            ) && output.includes('- mcp_test-server_hello')
-          );
-        },
-        30000, // 30s timeout
-      );
-
-      // Update the extension, expect the list to update, and mcp servers as well.
-      await run.sendKeys('\u0015/extensions update test-extension');
-      await run.expectText('/extensions update test-extension');
-      await run.type('\r');
-      await new Promise((resolve) => setTimeout(resolve, 500));
-      await run.type('\r');
-      await run.expectText(
-        ` * test-server (remote): http://localhost:${portB}/mcp`,
-      );
-      await run.type('\r'); // consent
-      await run.expectText(
-        'Extension "test-extension" successfully updated: 0.0.1 → 0.0.2',
-      );
-
-      // Poll for the updated extension version
-      await rig.pollCommand(
-        async () => {
-          await run.sendText('/extensions list');
-          await run.type('\r');
-        },
-        () =>
-          stripAnsi(run.output).includes(
-            'test-extension (v0.0.2) - active (updated)',
-          ),
-        30000,
-      );
-
-      // Poll for the updated mcp tool
-      await rig.pollCommand(
-        async () => {
-          await run.sendText('/mcp list');
-          await run.type('\r');
-        },
-        () => {
-          const output = stripAnsi(run.output);
-          return (
-            output.includes(
-              'test-server (from test-extension) - Ready (1 tool)',
-            ) && output.includes('- mcp_test-server_goodbye')
-          );
-        },
-        30000,
-      );
-
-      await run.sendText('/quit');
-      await run.type('\r');
-
-      // Clean things up.
-      await serverA.stop();
-      await serverB.stop();
+    rig.setup('extension reload test', {
+      settings: {
+        experimental: { extensionReloading: true },
+      },
+    });
+    const testServerPath = join(rig.testDir!, 'gemini-extension.json');
+    writeFileSync(testServerPath, safeJsonStringify(extension, 2));
+    // defensive cleanup from previous tests.
+    try {
       await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
-    },
-  );
+    } catch {
+      /* empty */
+    }
+
+    const result = await rig.runCommand(
+      ['--debug', 'extensions', 'install', `${rig.testDir!}`],
+      { stdin: 'y\n' },
+    );
+    expect(result).toContain('test-extension');
+
+    // Now create the update, but its not installed yet
+    const serverB = new TestMcpServer();
+    const portB = await serverB.start({
+      goodbye: () => ({ content: [{ type: 'text', text: 'world' }] }),
+    });
+    extension.version = '0.0.2';
+    extension.mcpServers['test-server'].httpUrl =
+      `http://localhost:${portB}/mcp`;
+    writeFileSync(testServerPath, safeJsonStringify(extension, 2));
+
+    // Start the CLI.
+    const run = await rig.runInteractive({ args: '--debug' });
+    await run.expectText('You have 1 extension with an update available');
+    // See the outdated extension
+    await run.sendText('/extensions list');
+    await run.type('\r');
+    await run.expectText('test-extension (v0.0.1) - active (update available)');
+    // Wait for the UI to settle and retry the command until we see the update
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Poll for the updated list
+    await rig.pollCommand(
+      async () => {
+        await run.sendText('/mcp list');
+        await run.type('\r');
+      },
+      () => {
+        const output = stripAnsi(run.output);
+        return (
+          output.includes(
+            'test-server (from test-extension) - Ready (1 tool)',
+          ) && output.includes('- mcp_test-server_hello')
+        );
+      },
+      30000, // 30s timeout
+    );
+
+    // Update the extension, expect the list to update, and mcp servers as well.
+    await run.sendKeys('\u0015/extensions update test-extension');
+    await run.expectText('/extensions update test-extension');
+    await run.type('\r');
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    await run.type('\r');
+    await run.expectText(
+      ` * test-server (remote): http://localhost:${portB}/mcp`,
+    );
+    await run.type('\r'); // consent
+    await run.expectText(
+      'Extension "test-extension" successfully updated: 0.0.1 → 0.0.2',
+    );
+
+    // Poll for the updated extension version
+    await rig.pollCommand(
+      async () => {
+        await run.sendText('/extensions list');
+        await run.type('\r');
+      },
+      () =>
+        stripAnsi(run.output).includes(
+          'test-extension (v0.0.2) - active (updated)',
+        ),
+      30000,
+    );
+
+    // Poll for the updated mcp tool
+    await rig.pollCommand(
+      async () => {
+        await run.sendText('/mcp list');
+        await run.type('\r');
+      },
+      () => {
+        const output = stripAnsi(run.output);
+        return (
+          output.includes(
+            'test-server (from test-extension) - Ready (1 tool)',
+          ) && output.includes('- mcp_test-server_goodbye')
+        );
+      },
+      30000,
+    );
+
+    await run.sendText('/quit');
+    await run.type('\r');
+
+    // Clean things up.
+    await serverA.stop();
+    await serverB.stop();
+    await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
+  });
 });

integration-tests/plan-mode.test.ts

@@ -4,8 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { TestRig, checkModelOutputContent } from './test-helper.js';
+import { GEMINI_DIR, TestRig, checkModelOutputContent } from './test-helper.js';
 
 describe('Plan Mode', () => {
   let rig: TestRig;
@@ -227,4 +229,68 @@ describe('Plan Mode', () => {
       `Expected write_file to succeed, but it failed with error: ${planWrite?.toolRequest.error}`,
     ).toBe(true);
   });
+  it('should switch from a pro model to a flash model after exiting plan mode', async () => {
+    const plansDir = 'plans-folder';
+    const planFilename = 'my-plan.md';
+
+    await rig.setup('should-switch-to-flash', {
+      settings: {
+        model: {
+          name: 'auto-gemini-2.5',
+        },
+        experimental: { plan: true },
+        tools: {
+          core: ['exit_plan_mode', 'run_shell_command'],
+          allowed: ['exit_plan_mode', 'run_shell_command'],
+        },
+        general: {
+          defaultApprovalMode: 'plan',
+          plan: {
+            directory: plansDir,
+          },
+        },
+      },
+    });
+
+    writeFileSync(
+      join(rig.homeDir!, GEMINI_DIR, 'state.json'),
+      JSON.stringify({ terminalSetupPromptShown: true }, null, 2),
+    );
+
+    const fullPlansDir = join(rig.testDir!, plansDir);
+    mkdirSync(fullPlansDir, { recursive: true });
+    writeFileSync(join(fullPlansDir, planFilename), 'Execute echo hello');
+
+    await rig.run({
+      approvalMode: 'plan',
+      stdin: `Exit plan mode using ${planFilename} and then run a shell command \`echo hello\`.`,
+    });
+
+    const exitCallFound = await rig.waitForToolCall('exit_plan_mode');
+    expect(exitCallFound, 'Expected exit_plan_mode to be called').toBe(true);
+
+    const shellCallFound = await rig.waitForToolCall('run_shell_command');
+    expect(shellCallFound, 'Expected run_shell_command to be called').toBe(
+      true,
+    );
+
+    const apiRequests = rig.readAllApiRequest();
+    const modelNames = apiRequests.map((r) => r.attributes?.model || 'unknown');
+
+    const proRequests = apiRequests.filter((r) =>
+      r.attributes?.model?.includes('pro'),
+    );
+    const flashRequests = apiRequests.filter((r) =>
+      r.attributes?.model?.includes('flash'),
+    );
+
+    expect(
+      proRequests.length,
+      `Expected at least one Pro request. Models used: ${modelNames.join(', ')}`,
+    ).toBeGreaterThanOrEqual(1);
+    expect(
+      flashRequests.length,
+      `Expected at least one Flash request after mode switch. Models used: ${modelNames.join(', ')}`,
+    ).toBeGreaterThanOrEqual(1);
+  });
 });

package-lock.json

@@ -11,7 +11,7 @@
         "packages/*"
       ],
       "dependencies": {
-        "ink": "npm:@jrichman/ink@6.4.11",
+        "ink": "npm:@jrichman/ink@6.5.0",
         "latest-version": "^9.0.0",
         "node-fetch-native": "^1.6.7",
         "proper-lockfile": "^4.1.2",
@@ -10089,9 +10089,9 @@
     },
     "node_modules/ink": {
       "name": "@jrichman/ink",
-      "version": "6.4.11",
-      "resolved": "https://registry.npmjs.org/@jrichman/ink/-/ink-6.4.11.tgz",
-      "integrity": "sha512-93LQlzT7vvZ1XJcmOMwN4s+6W334QegendeHOMnEJBlhnpIzr8bws6/aOEHG8ZCuVD/vNeeea5m1msHIdAY6ig==",
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/@jrichman/ink/-/ink-6.5.0.tgz",
+      "integrity": "sha512-S4g/ng7fPZmFwclO82iWkOce8vDLy/FIDgHIfkCWGOehqHe6dexHsmq3kNQD21okh198pA5SAQTCqNQJb/svRQ==",
       "license": "MIT",
       "dependencies": {
         "@alcalzone/ansi-tokenize": "^0.2.1",
@@ -10116,6 +10116,7 @@
         "type-fest": "^4.27.0",
         "wrap-ansi": "^9.0.0",
         "ws": "^8.18.0",
+        "yargs": "^17.7.2",
         "yoga-layout": "~3.2.1"
       },
       "engines": {
@@ -17550,7 +17551,7 @@
         "fzf": "^0.5.2",
         "glob": "^12.0.0",
         "highlight.js": "^11.11.1",
-        "ink": "npm:@jrichman/ink@6.4.11",
+        "ink": "npm:@jrichman/ink@6.5.0",
         "ink-gradient": "^3.0.0",
         "ink-spinner": "^5.0.0",
         "latest-version": "^9.0.0",

package.json

@@ -68,7 +68,7 @@
     "pre-commit": "node scripts/pre-commit.js"
   },
   "overrides": {
-    "ink": "npm:@jrichman/ink@6.4.11",
+    "ink": "npm:@jrichman/ink@6.5.0",
     "wrap-ansi": "9.0.2",
     "cliui": {
       "wrap-ansi": "7.0.0"
@@ -136,7 +136,7 @@
     "yargs": "^17.7.2"
   },
   "dependencies": {
-    "ink": "npm:@jrichman/ink@6.4.11",
+    "ink": "npm:@jrichman/ink@6.5.0",
     "latest-version": "^9.0.0",
     "node-fetch-native": "^1.6.7",
     "proper-lockfile": "^4.1.2",

packages/a2a-server/src/config/config.test.ts

@@ -352,23 +352,37 @@ describe('loadConfig', () => {
     });
 
     describe('interactivity', () => {
-      it('should set interactive true when not headless', async () => {
+      it('should always set interactive true', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(true);
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            interactive: true,
+          }),
+        );
+
         vi.mocked(isHeadlessMode).mockReturnValue(false);
         await loadConfig(mockSettings, mockExtensionLoader, taskId);
         expect(Config).toHaveBeenCalledWith(
           expect.objectContaining({
             interactive: true,
-            enableInteractiveShell: true,
           }),
         );
       });
 
-      it('should set interactive false when headless', async () => {
+      it('should set enableInteractiveShell based on headless mode', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(false);
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            enableInteractiveShell: true,
+          }),
+        );
+
         vi.mocked(isHeadlessMode).mockReturnValue(true);
         await loadConfig(mockSettings, mockExtensionLoader, taskId);
         expect(Config).toHaveBeenCalledWith(
           expect.objectContaining({
-            interactive: false,
             enableInteractiveShell: false,
           }),
         );

packages/a2a-server/src/config/config.ts

@@ -125,7 +125,7 @@ export async function loadConfig(
     trustedFolder: true,
     extensionLoader,
     checkpointing,
-    interactive: !isHeadlessMode(),
+    interactive: true,
     enableInteractiveShell: !isHeadlessMode(),
     ptyInfo: 'auto',
     enableAgents: settings.experimental?.enableAgents ?? true,

packages/cli/package.json

@@ -49,7 +49,7 @@
     "fzf": "^0.5.2",
     "glob": "^12.0.0",
     "highlight.js": "^11.11.1",
-    "ink": "npm:@jrichman/ink@6.4.11",
+    "ink": "npm:@jrichman/ink@6.5.0",
     "ink-gradient": "^3.0.0",
     "ink-spinner": "^5.0.0",
     "latest-version": "^9.0.0",

packages/cli/src/acp/acpClient.test.ts

@@ -99,6 +99,8 @@ vi.mock(
     const actual = await importOriginal();
     return {
       ...actual,
+      updatePolicy: vi.fn(),
+      createPolicyUpdater: vi.fn(),
       ReadManyFilesTool: vi.fn().mockImplementation(() => ({
         name: 'read_many_files',
         kind: 'read',
@@ -181,6 +183,20 @@ describe('GeminiAgent', () => {
       getWorkspaceContext: vi.fn().mockReturnValue({
         addReadOnlyPath: vi.fn(),
       }),
+      getPolicyEngine: vi.fn().mockReturnValue({
+        addRule: vi.fn(),
+      }),
+      messageBus: {
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      },
+      storage: {
+        getWorkspaceAutoSavedPolicyPath: vi.fn(),
+        getAutoSavedPolicyPath: vi.fn(),
+        setClientName: vi.fn(),
+      },
+      setClientName: vi.fn(),
       get config() {
         return this;
       },
@@ -201,7 +217,10 @@ describe('GeminiAgent', () => {
     (loadCliConfig as unknown as Mock).mockResolvedValue(mockConfig);
     (loadSettings as unknown as Mock).mockImplementation(() => ({
       merged: {
-        security: { auth: { selectedType: AuthType.LOGIN_WITH_GOOGLE } },
+        security: {
+          auth: { selectedType: AuthType.LOGIN_WITH_GOOGLE },
+          enablePermanentToolApproval: true,
+        },
         mcpServers: {},
       },
       setValue: vi.fn(),
@@ -687,7 +706,10 @@ describe('Session', () => {
       systemDefaults: { settings: {} },
       user: { settings: {} },
       workspace: { settings: {} },
-      merged: { settings: {} },
+      merged: {
+        security: { enablePermanentToolApproval: true },
+        mcpServers: {},
+      },
       errors: [],
     } as unknown as LoadedSettings);
   });
@@ -1026,6 +1048,166 @@ describe('Session', () => {
     );
   });
 
+  it('should exclude always allow and save permanent option when enablePermanentToolApproval is false', async () => {
+    mockConfig.getDisableAlwaysAllow = vi.fn().mockReturnValue(false);
+    const confirmationDetails = {
+      type: 'edit',
+      onConfirm: vi.fn(),
+    };
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'Test Tool',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi.fn().mockResolvedValue(confirmationDetails),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    const customSettings = {
+      system: { settings: {} },
+      systemDefaults: { settings: {} },
+      user: { settings: {} },
+      workspace: { settings: {} },
+      merged: {
+        security: { enablePermanentToolApproval: false },
+        mcpServers: {},
+      },
+      errors: [],
+    } as unknown as LoadedSettings;
+
+    const localSession = new Session(
+      'session-2',
+      mockChat,
+      mockConfig,
+      mockConnection,
+      customSettings,
+    );
+
+    mockConnection.requestPermission.mockResolvedValueOnce({
+      outcome: {
+        outcome: 'selected',
+        optionId: ToolConfirmationOutcome.ProceedOnce,
+      },
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: StreamEventType.CHUNK,
+        value: {
+          functionCalls: [{ name: 'test_tool', args: {} }],
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: StreamEventType.CHUNK,
+        value: { candidates: [] },
+      },
+    ]);
+
+    mockChat.sendMessageStream
+      .mockResolvedValueOnce(stream1)
+      .mockResolvedValueOnce(stream2);
+
+    await localSession.prompt({
+      sessionId: 'session-2',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockConnection.requestPermission).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.not.arrayContaining([
+          expect.objectContaining({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+          }),
+        ]),
+      }),
+    );
+    expect(mockConnection.requestPermission).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.arrayContaining([
+          expect.objectContaining({
+            optionId: ToolConfirmationOutcome.ProceedAlways,
+          }),
+        ]),
+      }),
+    );
+  });
+
+  it('should include always allow and save permanent option when enablePermanentToolApproval is true', async () => {
+    mockConfig.getDisableAlwaysAllow = vi.fn().mockReturnValue(false);
+    const confirmationDetails = {
+      type: 'edit',
+      onConfirm: vi.fn(),
+    };
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'Test Tool',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi.fn().mockResolvedValue(confirmationDetails),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    const customSettings = {
+      system: { settings: {} },
+      systemDefaults: { settings: {} },
+      user: { settings: {} },
+      workspace: { settings: {} },
+      merged: {
+        security: { enablePermanentToolApproval: true },
+        mcpServers: {},
+      },
+      errors: [],
+    } as unknown as LoadedSettings;
+
+    const localSession = new Session(
+      'session-2',
+      mockChat,
+      mockConfig,
+      mockConnection,
+      customSettings,
+    );
+
+    mockConnection.requestPermission.mockResolvedValueOnce({
+      outcome: {
+        outcome: 'selected',
+        optionId: ToolConfirmationOutcome.ProceedOnce,
+      },
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: StreamEventType.CHUNK,
+        value: {
+          functionCalls: [{ name: 'test_tool', args: {} }],
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: StreamEventType.CHUNK,
+        value: { candidates: [] },
+      },
+    ]);
+
+    mockChat.sendMessageStream
+      .mockResolvedValueOnce(stream1)
+      .mockResolvedValueOnce(stream2);
+
+    await localSession.prompt({
+      sessionId: 'session-2',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockConnection.requestPermission).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.arrayContaining([
+          expect.objectContaining({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow for this file in all future sessions',
+          }),
+        ]),
+      }),
+    );
+  });
+
   it('should use filePath for ACP diff content in permission request', async () => {
     const confirmationDetails = {
       type: 'edit',
@@ -1154,6 +1336,56 @@ describe('Session', () => {
     );
   });
 
+  it('should call updatePolicy when tool permission triggers always allow', async () => {
+    const confirmationDetails = {
+      type: 'info',
+      onConfirm: vi.fn(),
+    };
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'Test Tool',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi.fn().mockResolvedValue(confirmationDetails),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    mockConnection.requestPermission.mockResolvedValue({
+      outcome: {
+        outcome: 'selected',
+        optionId: ToolConfirmationOutcome.ProceedAlways,
+      },
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: StreamEventType.CHUNK,
+        value: {
+          functionCalls: [{ name: 'test_tool', args: {} }],
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: StreamEventType.CHUNK,
+        value: { candidates: [] },
+      },
+    ]);
+
+    mockChat.sendMessageStream
+      .mockResolvedValueOnce(stream1)
+      .mockResolvedValueOnce(stream2);
+
+    const { updatePolicy } = await import('@google/gemini-cli-core');
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(confirmationDetails.onConfirm).toHaveBeenCalled();
+
+    expect(updatePolicy).toHaveBeenCalled();
+  });
+
   it('should use filePath for ACP diff content in tool result', async () => {
     mockTool.build.mockReturnValue({
       getDescription: () => 'Test Tool',

packages/cli/src/acp/acpClient.ts

@@ -49,6 +49,7 @@ import {
   getDisplayString,
   processSingleFileContent,
   type AgentLoopContext,
+  updatePolicy,
 } from '@google/gemini-cli-core';
 import * as acp from '@agentclientprotocol/sdk';
 import { AcpFileSystemService } from './fileSystemService.js';
@@ -64,6 +65,7 @@ import {
   loadSettings,
   type LoadedSettings,
 } from '../config/settings.js';
+import { createPolicyUpdater } from '../config/policy.js';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { z } from 'zod';
@@ -133,6 +135,7 @@ export class GeminiAgent {
     args: acp.InitializeRequest,
   ): Promise<acp.InitializeResponse> {
     this.clientCapabilities = args.clientCapabilities;
+
     const authMethods = [
       {
         id: AuthType.LOGIN_WITH_GOOGLE,
@@ -322,6 +325,7 @@ export class GeminiAgent {
 
     const geminiClient = config.getGeminiClient();
     const chat = await geminiClient.startChat();
+
     const session = new Session(
       sessionId,
       chat,
@@ -512,6 +516,12 @@ export class GeminiAgent {
 
     const config = await loadCliConfig(settings, sessionId, this.argv, { cwd });
 
+    createPolicyUpdater(
+      config.getPolicyEngine(),
+      config.messageBus,
+      config.storage,
+    );
+
     return config;
   }
 
@@ -1012,6 +1022,7 @@ export class Session {
           options: toPermissionOptions(
             confirmationDetails,
             this.context.config,
+            this.settings.merged.security.enablePermanentToolApproval,
           ),
           toolCall: {
             toolCallId: callId,
@@ -1036,6 +1047,16 @@ export class Session {
 
         await confirmationDetails.onConfirm(outcome);
 
+        // Update policy to enable Always Allow persistence
+        await updatePolicy(
+          tool,
+          outcome,
+          confirmationDetails,
+          this.context,
+          this.context.messageBus,
+          invocation,
+        );
+
         switch (outcome) {
           case ToolConfirmationOutcome.Cancel:
             return errorResponse(
@@ -1785,6 +1806,7 @@ const basicPermissionOptions = [
 function toPermissionOptions(
   confirmation: ToolCallConfirmationDetails,
   config: Config,
+  enablePermanentToolApproval: boolean = false,
 ): acp.PermissionOption[] {
   const disableAlwaysAllow = config.getDisableAlwaysAllow();
   const options: acp.PermissionOption[] = [];
@@ -1794,37 +1816,65 @@ function toPermissionOptions(
       case 'edit':
         options.push({
           optionId: ToolConfirmationOutcome.ProceedAlways,
-          name: 'Allow All Edits',
+          name: 'Allow for this session',
           kind: 'allow_always',
         });
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow for this file in all future sessions',
+            kind: 'allow_always',
+          });
+        }
         break;
       case 'exec':
         options.push({
           optionId: ToolConfirmationOutcome.ProceedAlways,
-          name: `Always Allow ${confirmation.rootCommand}`,
+          name: 'Allow for this session',
           kind: 'allow_always',
         });
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow this command for all future sessions',
+            kind: 'allow_always',
+          });
+        }
         break;
       case 'mcp':
         options.push(
           {
             optionId: ToolConfirmationOutcome.ProceedAlwaysServer,
-            name: `Always Allow ${confirmation.serverName}`,
+            name: 'Allow all server tools for this session',
             kind: 'allow_always',
           },
           {
             optionId: ToolConfirmationOutcome.ProceedAlwaysTool,
-            name: `Always Allow ${confirmation.toolName}`,
+            name: 'Allow tool for this session',
             kind: 'allow_always',
           },
         );
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow tool for all future sessions',
+            kind: 'allow_always',
+          });
+        }
         break;
       case 'info':
         options.push({
           optionId: ToolConfirmationOutcome.ProceedAlways,
-          name: `Always Allow`,
+          name: 'Allow for this session',
           kind: 'allow_always',
         });
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow for all future sessions',
+            kind: 'allow_always',
+          });
+        }
         break;
       case 'ask_user':
       case 'exit_plan_mode':

packages/cli/src/acp/acpResume.test.ts

@@ -91,6 +91,14 @@ describe('GeminiAgent Session Resume', () => {
       storage: {
         getProjectTempDir: vi.fn().mockReturnValue('/tmp/project'),
       },
+      getPolicyEngine: vi.fn().mockReturnValue({
+        addRule: vi.fn(),
+      }),
+      messageBus: {
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      },
       getApprovalMode: vi.fn().mockReturnValue('default'),
       isPlanEnabled: vi.fn().mockReturnValue(true),
       getModel: vi.fn().mockReturnValue('gemini-pro'),

packages/cli/src/config/config.test.ts

@@ -143,12 +143,17 @@ vi.mock('@google/gemini-cli-core', async () => {
       respectGeminiIgnore: true,
       customIgnoreFilePaths: [],
     },
-    createPolicyEngineConfig: vi.fn(async () => ({
-      rules: [],
-      checkers: [],
-      defaultDecision: ServerConfig.PolicyDecision.ASK_USER,
-      approvalMode: ServerConfig.ApprovalMode.DEFAULT,
-    })),
+    createPolicyEngineConfig: vi.fn(
+      async (_settings, approvalMode, _workspacePoliciesDir, interactive) => ({
+        rules: [],
+        checkers: [],
+        defaultDecision: interactive
+          ? ServerConfig.PolicyDecision.ASK_USER
+          : ServerConfig.PolicyDecision.DENY,
+        approvalMode: approvalMode ?? ServerConfig.ApprovalMode.DEFAULT,
+        nonInteractive: !interactive,
+      }),
+    ),
     getAdminErrorMessage: vi.fn(
       (_feature) =>
         `YOLO mode is disabled by your administrator. To enable it, please request an update to the settings at: https://goo.gle/manage-gemini-cli`,
@@ -3460,6 +3465,8 @@ describe('Policy Engine Integration in loadCliConfig', () => {
         }),
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -3481,6 +3488,8 @@ describe('Policy Engine Integration in loadCliConfig', () => {
         }),
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -3504,6 +3513,8 @@ describe('Policy Engine Integration in loadCliConfig', () => {
         ],
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 });

packages/cli/src/config/config.ts

@@ -792,8 +792,8 @@ export async function loadCliConfig(
     effectiveSettings,
     approvalMode,
     workspacePoliciesDir,
+    interactive,
   );
-  policyEngineConfig.nonInteractive = !interactive;
 
   const defaultModel = PREVIEW_GEMINI_MODEL_AUTO;
   const specifiedModel =

packages/cli/src/config/policy-engine.integration.test.ts

@@ -605,12 +605,12 @@ describe('Policy Engine Integration Tests', () => {
     it('should verify non-interactive mode transformation', async () => {
       const settings: Settings = {};
 
-      const config = await createPolicyEngineConfig(
+      const engineConfig = await createPolicyEngineConfig(
         settings,
         ApprovalMode.DEFAULT,
+        undefined,
+        false,
       );
-      // Enable non-interactive mode
-      const engineConfig = { ...config, nonInteractive: true };
       const engine = new PolicyEngine(engineConfig);
 
       // ASK_USER should become DENY in non-interactive mode

packages/cli/src/config/policy.ts

@@ -53,6 +53,7 @@ export async function createPolicyEngineConfig(
   settings: Settings,
   approvalMode: ApprovalMode,
   workspacePoliciesDir?: string,
+  interactive: boolean = true,
 ): Promise<PolicyEngineConfig> {
   // Explicitly construct PolicySettings from Settings to ensure type safety
   // and avoid accidental leakage of other settings properties.
@@ -68,7 +69,12 @@ export async function createPolicyEngineConfig(
       settings.admin?.secureModeEnabled,
   };
 
-  return createCorePolicyEngineConfig(policySettings, approvalMode);
+  return createCorePolicyEngineConfig(
+    policySettings,
+    approvalMode,
+    undefined,
+    interactive,
+  );
 }
 
 export function createPolicyUpdater(

packages/cli/src/config/settingsSchema.ts

@@ -261,7 +261,7 @@ const SETTINGS_SCHEMA = {
         requiresRestart: false,
         default: false,
         description:
-          'Enable run-event notifications for action-required prompts and session completion. Currently macOS only.',
+          'Enable run-event notifications for action-required prompts and session completion.',
         showInDialog: true,
       },
       checkpointing: {

packages/cli/src/config/workspace-policy-cli.test.ts

@@ -88,6 +88,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
         ),
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -107,6 +109,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
         workspacePoliciesDir: undefined,
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -131,6 +135,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
         workspacePoliciesDir: undefined,
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -163,6 +169,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
         ),
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -201,6 +209,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
         ),
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -237,6 +247,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
         ),
       }),
       expect.anything(),
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -278,6 +290,8 @@ describe('Workspace-Level Policy CLI Integration', () => {
           workspacePoliciesDir: undefined,
         }),
         expect.anything(),
+        undefined,
+        expect.anything(),
       );
     } finally {
       // Restore for other tests

packages/cli/src/ui/AppContainer.tsx

@@ -726,7 +726,7 @@ export const AppContainer = (props: AppContainerProps) => {
   // Wrap handleDeleteSession to return a Promise for UIActions interface
   const handleDeleteSession = useCallback(
     async (session: SessionInfo): Promise<void> => {
-      handleDeleteSessionSync(session);
+      await handleDeleteSessionSync(session);
     },
     [handleDeleteSessionSync],
   );

packages/cli/src/ui/commands/clearCommand.ts

@@ -9,6 +9,7 @@ import {
   SessionEndReason,
   SessionStartSource,
   flushTelemetry,
+  resetBrowserSession,
 } from '@google/gemini-cli-core';
 import { CommandKind, type SlashCommand } from './types.js';
 import { MessageType } from '../types.js';
@@ -43,6 +44,10 @@ export const clearCommand: SlashCommand = {
 
     if (geminiClient) {
       context.ui.setDebugMessage('Clearing terminal and resetting chat.');
+
+      // Close persistent browser sessions before resetting chat
+      await resetBrowserSession();
+
       // If resetChat fails, the exception will propagate and halt the command,
       // which is the correct behavior to signal a failure to the user.
       await geminiClient.resetChat();

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Initial-Rendering-should-render-settings-list-with-visual-indicators.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-accessibility-settings-enabled-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-all-boolean-settings-disabled-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-default-state-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-file-filtering-settings-configured-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-focused-on-scope-selector-correctly.snap.svg

@@ -60,7 +60,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-mixed-boolean-and-number-settings-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-tools-and-security-settings-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog-SettingsDialog-Snapshot-Tests-should-render-various-boolean-settings-enabled-correctly.snap.svg

@@ -71,7 +71,7 @@
     <text x="828" y="308" fill="#afafaf" textLength="45" lengthAdjust="spacingAndGlyphs">false</text>
     <text x="891" y="308" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
-    <text x="45" y="325" fill="#afafaf" textLength="756" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion. …</text>
+    <text x="45" y="325" fill="#afafaf" textLength="738" lengthAdjust="spacingAndGlyphs">Enable run-event notifications for action-required prompts and session completion.</text>
     <text x="891" y="325" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="0" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>
     <text x="891" y="342" fill="#878787" textLength="9" lengthAdjust="spacingAndGlyphs">│</text>

packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap

@@ -20,7 +20,7 @@ exports[`SettingsDialog > Initial Rendering > should render settings list with v
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -66,7 +66,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'accessibility settings
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -112,7 +112,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'all boolean settings d
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -158,7 +158,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'default state' correct
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -204,7 +204,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'file filtering setting
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -250,7 +250,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'focused on scope selec
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -296,7 +296,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'mixed boolean and numb
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -342,7 +342,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'tools and security set
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
@@ -388,7 +388,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'various boolean settin
 │    Enable automatic updates.                                                                     │
 │                                                                                                  │
 │    Enable Notifications                                                                   false  │
-│    Enable run-event notifications for action-required prompts and session completion. …          │
+│    Enable run-event notifications for action-required prompts and session completion.            │
 │                                                                                                  │
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │

packages/cli/src/ui/components/shared/BaseSelectionList.tsx

@@ -96,8 +96,14 @@ export function BaseSelectionList<
     );
   }
 
+  // Ensure offset is within bounds if items length changed
+  const maxScroll = Math.max(0, items.length - maxItemsToShow);
+  if (effectiveScrollOffset > maxScroll) {
+    effectiveScrollOffset = maxScroll;
+  }
+
   // Synchronize state if it changed during derivation
-  if (effectiveScrollOffset !== scrollOffset) {
+  if (scrollOffset !== effectiveScrollOffset) {
     setScrollOffset(effectiveScrollOffset);
   }
 
@@ -107,21 +113,12 @@ export function BaseSelectionList<
   );
   const numberColumnWidth = String(items.length).length;
 
+  const canScrollUp = effectiveScrollOffset > 0;
+  const canScrollDown = effectiveScrollOffset + maxItemsToShow < items.length;
+  const hasScrollArrows = showScrollArrows && items.length > maxItemsToShow;
+
   return (
     <Box flexDirection="column">
-      {/* Use conditional coloring instead of conditional rendering */}
-      {showScrollArrows && items.length > maxItemsToShow && (
-        <Text
-          color={
-            effectiveScrollOffset > 0
-              ? theme.text.primary
-              : theme.text.secondary
-          }
-        >
-          ▲
-        </Text>
-      )}
-
       {visibleItems.map((item, index) => {
         const itemIndex = effectiveScrollOffset + index;
         const isSelected = activeIndex === itemIndex;
@@ -150,19 +147,35 @@ export function BaseSelectionList<
           numberColumnWidth,
         )}.`;
 
+        // Determine the indicator character for the radio column
+        let indicator = ' ';
+        let indicatorColor = theme.text.primary;
+
+        if (isSelected) {
+          indicator = selectedIndicator;
+          indicatorColor = theme.ui.focus;
+        } else if (hasScrollArrows && index === 0 && canScrollUp) {
+          indicator = '▲';
+          indicatorColor = theme.text.secondary;
+        } else if (
+          hasScrollArrows &&
+          index === visibleItems.length - 1 &&
+          canScrollDown
+        ) {
+          indicator = '▼';
+          indicatorColor = theme.text.secondary;
+        }
+
         return (
           <Box
             key={item.key}
             alignItems="flex-start"
             backgroundColor={isSelected ? theme.background.focus : undefined}
           >
-            {/* Radio button indicator */}
+            {/* Radio button indicator (also shows scroll arrows inline) */}
             <Box minWidth={2} flexShrink={0}>
-              <Text
-                color={isSelected ? theme.ui.focus : theme.text.primary}
-                aria-hidden
-              >
-                {isSelected ? selectedIndicator : ' '}
+              <Text color={indicatorColor} aria-hidden>
+                {indicator}
               </Text>
             </Box>
 
@@ -189,18 +202,6 @@ export function BaseSelectionList<
           </Box>
         );
       })}
-
-      {showScrollArrows && items.length > maxItemsToShow && (
-        <Text
-          color={
-            effectiveScrollOffset + maxItemsToShow < items.length
-              ? theme.text.primary
-              : theme.text.secondary
-          }
-        >
-          ▼
-        </Text>
-      )}
     </Box>
   );
 }

packages/cli/src/ui/components/shared/SearchableList.tsx

@@ -172,11 +172,12 @@ export function SearchableList<T extends GenericListItem>({
     item: T,
     isActive: boolean,
     labelWidth: number,
+    arrowChar?: string,
   ) => (
     <Box flexDirection="row" alignItems="flex-start">
       <Box minWidth={2} flexShrink={0}>
         <Text color={isActive ? theme.status.success : theme.text.secondary}>
-          {isActive ? '●' : ''}
+          {isActive ? '●' : arrowChar || ' '}
         </Text>
       </Box>
       <Box flexDirection="column" flexGrow={1} minWidth={0}>
@@ -226,26 +227,44 @@ export function SearchableList<T extends GenericListItem>({
           </Box>
         ) : (
           <>
-            {filteredItems.length > maxItemsToShow && (
-              <Box marginX={1}>
-                <Text color={theme.text.secondary}>▲</Text>
-              </Box>
-            )}
             {visibleItems.map((item, index) => {
               const isSelected = activeIndex === scrollOffset + index;
+              const hasScrollArrows = filteredItems.length > maxItemsToShow;
+              const canScrollUp = scrollOffset > 0;
+              const canScrollDown =
+                scrollOffset + maxItemsToShow < filteredItems.length;
+
+              // Determine inline scroll arrow for this item position
+              let arrowChar = '';
+              if (
+                hasScrollArrows &&
+                index === 0 &&
+                canScrollUp &&
+                !isSelected
+              ) {
+                arrowChar = '▲';
+              } else if (
+                hasScrollArrows &&
+                index === visibleItems.length - 1 &&
+                canScrollDown &&
+                !isSelected
+              ) {
+                arrowChar = '▼';
+              }
+
               return (
                 <Box key={item.key} marginBottom={1} marginX={1}>
                   {renderItem
                     ? renderItem(item, isSelected, maxLabelWidth)
-                    : defaultRenderItem(item, isSelected, maxLabelWidth)}
+                    : defaultRenderItem(
+                        item,
+                        isSelected,
+                        maxLabelWidth,
+                        arrowChar,
+                      )}
                 </Box>
               );
             })}
-            {filteredItems.length > maxItemsToShow && (
-              <Box marginX={1}>
-                <Text color={theme.text.secondary}>▼</Text>
-              </Box>
-            )}
           </>
         )}
       </Box>

packages/cli/src/ui/components/shared/__snapshots__/BaseSelectionList.test.tsx.snap

@@ -8,28 +8,22 @@ exports[`BaseSelectionList > Scroll Arrows (showScrollArrows) > should not show
 `;
 
 exports[`BaseSelectionList > Scroll Arrows (showScrollArrows) > should show arrows and correct items when scrolled to the end 1`] = `
-"▲
-   8. Item 8
+"▲  8. Item 8
    9. Item 9
 ● 10. Item 10
-▼
 "
 `;
 
 exports[`BaseSelectionList > Scroll Arrows (showScrollArrows) > should show arrows and correct items when scrolled to the middle 1`] = `
-"▲
-   4. Item 4
+"▲  4. Item 4
    5. Item 5
 ●  6. Item 6
-▼
 "
 `;
 
 exports[`BaseSelectionList > Scroll Arrows (showScrollArrows) > should show arrows with correct colors when enabled (at the top) 1`] = `
-"▲
-●  1. Item 1
+"●  1. Item 1
    2. Item 2
-   3. Item 3
-▼
+▼  3. Item 3
 "
 `;

packages/cli/src/ui/components/shared/__snapshots__/SearchableList.test.tsx.snap

@@ -7,10 +7,10 @@ exports[`SearchableList > should match snapshot 1`] = `
  │ Search...                                                                                      │
  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-  ● Item One  
+  ● Item One
     Description for item one
 
-    Item Two  
+    Item Two
     Description for item two
 
     Item Three
@@ -25,10 +25,10 @@ exports[`SearchableList > should reset selection to top when items change if res
  │ Search...                                                                                      │
  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-    Item One  
+    Item One
     Description for item one
 
-  ● Item Two  
+  ● Item Two
     Description for item two
 
     Item Three
@@ -43,7 +43,7 @@ exports[`SearchableList > should reset selection to top when items change if res
  │ One                                                                                            │
  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-  ● Item One  
+  ● Item One
     Description for item one
 "
 `;
@@ -55,10 +55,10 @@ exports[`SearchableList > should reset selection to top when items change if res
  │ Search...                                                                                      │
  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-  ● Item One  
+  ● Item One
     Description for item one
 
-    Item Two  
+    Item Two
     Description for item two
 
     Item Three

packages/cli/src/ui/hooks/shellCommandProcessor.ts

@@ -45,20 +45,18 @@ function addShellCommandToGeminiHistory(
       ? resultText.substring(0, MAX_OUTPUT_LENGTH) + '\n... (truncated)'
       : resultText;
 
+  // Escape backticks to prevent prompt injection breakouts
+  const safeQuery = rawQuery.replace(/\\/g, '\\\\').replace(/\x60/g, '\\\x60');
+  const safeModelContent = modelContent
+    .replace(/\\/g, '\\\\')
+    .replace(/\x60/g, '\\\x60');
+
   // eslint-disable-next-line @typescript-eslint/no-floating-promises
   geminiClient.addHistory({
     role: 'user',
     parts: [
       {
-        text: `I ran the following shell command:
-\`\`\`sh
-${rawQuery}
-\`\`\`
-
-This produced the following result:
-\`\`\`
-${modelContent}
-\`\`\``,
+        text: `I ran the following shell command:\n\`\`\`sh\n${safeQuery}\n\`\`\`\n\nThis produced the following result:\n\`\`\`\n${safeModelContent}\n\`\`\``,
       },
     ],
   });
@@ -444,7 +442,7 @@ export const useShellCommandProcessor = (
           }
 
           let mainContent: string;
-          if (isBinary(result.rawOutput)) {
+          if (isBinaryStream || isBinary(result.rawOutput)) {
             mainContent =
               '[Command produced binary output, which is not shown.]';
           } else {

packages/cli/src/ui/hooks/useSessionBrowser.ts

@@ -98,7 +98,7 @@ export const useSessionBrowser = (
      * Deletes a session by ID using the ChatRecordingService.
      */
     handleDeleteSession: useCallback(
-      (session: SessionInfo) => {
+      async (session: SessionInfo) => {
         // Note: Chat sessions are stored on disk using a filename derived from
         // the session, e.g. "session-<timestamp>-<sessionIdPrefix>.json".
         // The ChatRecordingService.deleteSession API expects this file basename
@@ -108,7 +108,7 @@ export const useSessionBrowser = (
             .getGeminiClient()
             ?.getChatRecordingService();
           if (chatRecordingService) {
-            chatRecordingService.deleteSession(session.file);
+            await chatRecordingService.deleteSession(session.file);
           }
         } catch (error) {
           coreEvents.emitFeedback('error', 'Error deleting session:', error);

packages/cli/src/ui/hooks/useSlashCompletion.test.ts

@@ -691,6 +691,40 @@ describe('useSlashCompletion', () => {
       });
       unmount();
     });
+
+    it('should rank primary name prefix matches higher than alias prefix matches', async () => {
+      const slashCommands = [
+        createTestCommand({
+          name: 'footer',
+          altNames: ['statusline'],
+          description: 'Configure footer',
+        }),
+        createTestCommand({
+          name: 'stats',
+          altNames: ['usage'],
+          description: 'Check stats',
+        }),
+      ];
+
+      const { result, unmount } = await renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/stat',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      await resolveMatch();
+
+      await waitFor(() => {
+        // 'stats' should be first because 'stat' is a prefix match on its name
+        // while 'footer' only matches 'stat' via its alias 'statusline'
+        expect(result.current.suggestions[0].label).toBe('stats');
+        expect(result.current.suggestions[1].label).toBe('footer');
+      });
+      unmount();
+    });
   });
 
   describe('Sub-Commands', () => {

packages/cli/src/ui/hooks/useSlashCompletion.ts

@@ -272,13 +272,45 @@ function useCommandSuggestions(
         }
 
         if (!signal.aborted) {
-          // Sort potentialSuggestions so that exact match (by name or altName) comes first
+          // Sort potentialSuggestions so that exact name/prefix match comes first,
+          // prioritizing primary name over altNames.
+          const lowerPartial = partial.toLowerCase();
           const sortedSuggestions = [...potentialSuggestions].sort((a, b) => {
-            const aIsExact = matchesCommand(a, partial);
-            const bIsExact = matchesCommand(b, partial);
-            if (aIsExact && !bIsExact) return -1;
-            if (!aIsExact && bIsExact) return 1;
-            return 0;
+            // 1. Exact name match
+            const aNameExact = a.name.toLowerCase() === lowerPartial;
+            const bNameExact = b.name.toLowerCase() === lowerPartial;
+            if (aNameExact && !bNameExact) return -1;
+            if (!aNameExact && bNameExact) return 1;
+
+            // 2. Exact altName match
+            const aAltExact =
+              a.altNames?.some((alt) => alt.toLowerCase() === lowerPartial) ||
+              false;
+            const bAltExact =
+              b.altNames?.some((alt) => alt.toLowerCase() === lowerPartial) ||
+              false;
+            if (aAltExact && !bAltExact) return -1;
+            if (!aAltExact && bAltExact) return 1;
+
+            // 3. Prefix name match
+            const aNamePrefix = a.name.toLowerCase().startsWith(lowerPartial);
+            const bNamePrefix = b.name.toLowerCase().startsWith(lowerPartial);
+            if (aNamePrefix && !bNamePrefix) return -1;
+            if (!aNamePrefix && bNamePrefix) return 1;
+
+            // 4. Prefix altName match
+            const aAltPrefix =
+              a.altNames?.some((alt) =>
+                alt.toLowerCase().startsWith(lowerPartial),
+              ) || false;
+            const bAltPrefix =
+              b.altNames?.some((alt) =>
+                alt.toLowerCase().startsWith(lowerPartial),
+              ) || false;
+            if (aAltPrefix && !bAltPrefix) return -1;
+            if (!aAltPrefix && bAltPrefix) return 1;
+
+            return 0; // Maintain FZF score order for other matches
           });
 
           const finalSuggestions = sortedSuggestions.map((cmd) => {

packages/cli/src/utils/cleanup.ts

@@ -11,6 +11,7 @@ import {
   shutdownTelemetry,
   isTelemetrySdkInitialized,
   ExitCodes,
+  resetBrowserSession,
 } from '@google/gemini-cli-core';
 import type { Config } from '@google/gemini-cli-core';
 
@@ -72,6 +73,13 @@ export async function runExitCleanup() {
   }
   cleanupFunctions.length = 0; // Clear the array
 
+  // Close persistent browser sessions before disposing config
+  try {
+    await resetBrowserSession();
+  } catch (_) {
+    // Ignore errors during browser cleanup
+  }
+
   if (configForTelemetry) {
     try {
       await configForTelemetry.dispose();

packages/cli/src/utils/errors.ts

@@ -19,6 +19,7 @@ import {
   debugLogger,
   coreEvents,
   getErrorMessage,
+  getErrorType,
 } from '@google/gemini-cli-core';
 import { runSyncCleanup } from './cleanup.js';
 
@@ -82,7 +83,7 @@ export function handleError(
       timestamp: new Date().toISOString(),
       status: 'error',
       error: {
-        type: error instanceof Error ? error.constructor.name : 'Error',
+        type: getErrorType(error),
         message: errorMessage,
       },
       stats: streamFormatter.convertToStreamStats(metrics, 0),
@@ -177,7 +178,7 @@ export function handleCancellationError(config: Config): never {
       timestamp: new Date().toISOString(),
       status: 'error',
       error: {
-        type: 'FatalCancellationError',
+        type: getErrorType(cancellationError),
         message: cancellationError.message,
       },
       stats: streamFormatter.convertToStreamStats(metrics, 0),
@@ -218,7 +219,7 @@ export function handleMaxTurnsExceededError(config: Config): never {
       timestamp: new Date().toISOString(),
       status: 'error',
       error: {
-        type: 'FatalTurnLimitedError',
+        type: getErrorType(maxTurnsError),
         message: maxTurnsError.message,
       },
       stats: streamFormatter.convertToStreamStats(metrics, 0),

packages/cli/src/utils/sessionCleanup.test.ts

@@ -106,6 +106,8 @@ describe('Session Cleanup (Refactored)', () => {
     );
     // Session directory
     await fs.mkdir(path.join(testTempDir, sessionId), { recursive: true });
+    // Subagent chats directory
+    await fs.mkdir(path.join(chatsDir, sessionId), { recursive: true });
   }
 
   async function seedSessions() {
@@ -274,6 +276,7 @@ describe('Session Cleanup (Refactored)', () => {
         existsSync(path.join(toolOutputsDir, `session-${sessions[1].id}`)),
       ).toBe(false);
       expect(existsSync(path.join(testTempDir, sessions[1].id))).toBe(false); // Session directory should be deleted
+      expect(existsSync(path.join(chatsDir, sessions[1].id))).toBe(false); // Subagent chats directory should be deleted
     });
 
     it('should NOT delete sessions within the cutoff date', async () => {

packages/cli/src/utils/sessionCleanup.ts

@@ -13,6 +13,8 @@ import {
   Storage,
   TOOL_OUTPUTS_DIR,
   type Config,
+  deleteSessionArtifactsAsync,
+  deleteSubagentSessionDirAndArtifactsAsync,
 } from '@google/gemini-cli-core';
 import type { Settings, SessionRetentionSettings } from '../config/settings.js';
 import { getAllSessionFiles, type SessionFileEntry } from './sessionUtils.js';
@@ -59,48 +61,18 @@ function deriveShortIdFromFileName(fileName: string): string | null {
   return null;
 }
 
-/**
- * Gets the log path for a session ID.
- */
-function getSessionLogPath(tempDir: string, safeSessionId: string): string {
-  return path.join(tempDir, 'logs', `session-${safeSessionId}.jsonl`);
-}
-
 /**
  * Cleans up associated artifacts (logs, tool-outputs, directory) for a session.
  */
-async function deleteSessionArtifactsAsync(
+async function cleanupSessionAndSubagentsAsync(
   sessionId: string,
   config: Config,
 ): Promise<void> {
   const tempDir = config.storage.getProjectTempDir();
+  const chatsDir = path.join(tempDir, 'chats');
 
-  // Cleanup logs
-  const logsDir = path.join(tempDir, 'logs');
-  const safeSessionId = sanitizeFilenamePart(sessionId);
-  const logPath = getSessionLogPath(tempDir, safeSessionId);
-  if (logPath.startsWith(logsDir)) {
-    await fs.unlink(logPath).catch(() => {});
-  }
-
-  // Cleanup tool outputs
-  const toolOutputDir = path.join(
-    tempDir,
-    TOOL_OUTPUTS_DIR,
-    `session-${safeSessionId}`,
-  );
-  const toolOutputsBase = path.join(tempDir, TOOL_OUTPUTS_DIR);
-  if (toolOutputDir.startsWith(toolOutputsBase)) {
-    await fs
-      .rm(toolOutputDir, { recursive: true, force: true })
-      .catch(() => {});
-  }
-
-  // Cleanup session directory
-  const sessionDir = path.join(tempDir, safeSessionId);
-  if (safeSessionId && sessionDir.startsWith(tempDir + path.sep)) {
-    await fs.rm(sessionDir, { recursive: true, force: true }).catch(() => {});
-  }
+  await deleteSessionArtifactsAsync(sessionId, tempDir);
+  await deleteSubagentSessionDirAndArtifactsAsync(sessionId, chatsDir, tempDir);
 }
 
 /**
@@ -201,7 +173,7 @@ export async function cleanupExpiredSessions(
                 await fs.unlink(filePath);
 
                 if (fullSessionId) {
-                  await deleteSessionArtifactsAsync(fullSessionId, config);
+                  await cleanupSessionAndSubagentsAsync(fullSessionId, config);
                 }
                 result.deleted++;
               } else {
@@ -230,7 +202,7 @@ export async function cleanupExpiredSessions(
 
           const sessionId = sessionToDelete.sessionInfo?.id;
           if (sessionId) {
-            await deleteSessionArtifactsAsync(sessionId, config);
+            await cleanupSessionAndSubagentsAsync(sessionId, config);
           }
 
           if (config.getDebugMode()) {

packages/cli/src/utils/sessions.ts

@@ -97,7 +97,7 @@ export async function deleteSession(
   try {
     // Use ChatRecordingService to delete the session
     const chatRecordingService = new ChatRecordingService(config);
-    chatRecordingService.deleteSession(sessionToDelete.file);
+    await chatRecordingService.deleteSession(sessionToDelete.file);
 
     const time = formatRelativeTime(sessionToDelete.lastUpdated);
     writeToStdout(

packages/cli/src/utils/terminalNotifications.test.ts

@@ -43,7 +43,7 @@ describe('terminal notifications', () => {
     });
   });
 
-  it('returns false without writing on non-macOS platforms', async () => {
+  it('emits notification on non-macOS platforms', async () => {
     Object.defineProperty(process, 'platform', {
       value: 'linux',
       configurable: true,
@@ -54,8 +54,8 @@ describe('terminal notifications', () => {
       body: 'b',
     });
 
-    expect(shown).toBe(false);
-    expect(writeToStdout).not.toHaveBeenCalled();
+    expect(shown).toBe(true);
+    expect(writeToStdout).toHaveBeenCalled();
   });
 
   it('returns false without writing when disabled', async () => {
@@ -69,6 +69,7 @@ describe('terminal notifications', () => {
   });
 
   it('emits OSC 9 notification when supported terminal is detected', async () => {
+    vi.stubEnv('WT_SESSION', '');
     vi.stubEnv('TERM_PROGRAM', 'iTerm.app');
 
     const shown = await notifyViaTerminal(true, {
@@ -126,6 +127,7 @@ describe('terminal notifications', () => {
   });
 
   it('strips terminal control sequences and newlines from payload text', async () => {
+    vi.stubEnv('WT_SESSION', '');
     vi.stubEnv('TERM_PROGRAM', 'iTerm.app');
 
     const shown = await notifyViaTerminal(true, {

packages/cli/src/utils/terminalNotifications.ts

@@ -75,17 +75,10 @@ export function buildRunEventNotificationContent(
 
 export function isNotificationsEnabled(settings: LoadedSettings): boolean {
   const general = settings.merged.general as
-    | {
-        enableNotifications?: boolean;
-        enableMacOsNotifications?: boolean;
-      }
+    | { enableNotifications?: boolean }
     | undefined;
 
-  return (
-    process.platform === 'darwin' &&
-    (general?.enableNotifications === true ||
-      general?.enableMacOsNotifications === true)
-  );
+  return general?.enableNotifications === true;
 }
 
 function buildTerminalNotificationMessage(
@@ -112,7 +105,7 @@ export async function notifyViaTerminal(
   notificationsEnabled: boolean,
   content: RunEventNotificationContent,
 ): Promise<boolean> {
-  if (!notificationsEnabled || process.platform !== 'darwin') {
+  if (!notificationsEnabled) {
     return false;
   }
 

packages/core/src/agents/browser/browserAgentFactory.test.ts

@@ -7,7 +7,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   createBrowserAgentDefinition,
-  cleanupBrowserAgent,
+  resetBrowserSession,
 } from './browserAgentFactory.js';
 import { injectAutomationOverlay } from './automationOverlay.js';
 import { makeFakeConfig } from '../../test-utils/config.js';
@@ -15,7 +15,6 @@ import { PolicyDecision, PRIORITY_SUBAGENT_TOOL } from '../../policy/types.js';
 import type { Config } from '../../config/config.js';
 import type { MessageBus } from '../../confirmation-bus/message-bus.js';
 import type { PolicyEngine } from '../../policy/policy-engine.js';
-import type { BrowserManager } from './browserManager.js';
 
 // Create mock browser manager
 const mockBrowserManager = {
@@ -35,9 +34,17 @@ const mockBrowserManager = {
 };
 
 // Mock dependencies
-vi.mock('./browserManager.js', () => ({
-  BrowserManager: vi.fn(() => mockBrowserManager),
-}));
+vi.mock('./browserManager.js', () => {
+  const instancesMap = new Map();
+  const MockBrowserManager = vi.fn() as unknown as Record<string, unknown>;
+  // Add static methods — use mockImplementation for lazy eval (hoisting-safe)
+  MockBrowserManager['getInstance'] = vi.fn();
+  MockBrowserManager['resetAll'] = vi.fn().mockResolvedValue(undefined);
+  MockBrowserManager['instances'] = instancesMap;
+  return {
+    BrowserManager: MockBrowserManager,
+  };
+});
 
 vi.mock('./automationOverlay.js', () => ({
   injectAutomationOverlay: vi.fn().mockResolvedValue(undefined),
@@ -60,9 +67,16 @@ describe('browserAgentFactory', () => {
   let mockConfig: Config;
   let mockMessageBus: MessageBus;
 
-  beforeEach(() => {
+  beforeEach(async () => {
     vi.clearAllMocks();
 
+    // Set up getInstance to return mockBrowserManager
+    // (Can't do this in vi.mock factory due to hoisting)
+    const { BrowserManager: MockBM } = await import('./browserManager.js');
+    (MockBM as unknown as Record<string, ReturnType<typeof vi.fn>>)[
+      'getInstance'
+    ].mockReturnValue(mockBrowserManager);
+
     vi.mocked(injectAutomationOverlay).mockClear();
 
     // Reset mock implementations
@@ -99,7 +113,7 @@ describe('browserAgentFactory', () => {
     } as unknown as MessageBus;
   });
 
-  afterEach(() => {
+  afterEach(async () => {
     vi.restoreAllMocks();
   });
 
@@ -302,6 +316,23 @@ describe('browserAgentFactory', () => {
     });
   });
 
+  describe('resetBrowserSession', () => {
+    it('should delegate to BrowserManager.resetAll', async () => {
+      const { BrowserManager: MockBrowserManager } = await import(
+        './browserManager.js'
+      );
+      await resetBrowserSession();
+      expect(
+        (
+          MockBrowserManager as unknown as Record<
+            string,
+            ReturnType<typeof vi.fn>
+          >
+        )['resetAll'],
+      ).toHaveBeenCalled();
+    });
+  });
+
   describe('Policy Registration', () => {
     let mockPolicyEngine: {
       addRule: ReturnType<typeof vi.fn>;
@@ -421,25 +452,6 @@ describe('browserAgentFactory', () => {
       );
     });
   });
-
-  describe('cleanupBrowserAgent', () => {
-    it('should call close on browser manager', async () => {
-      await cleanupBrowserAgent(
-        mockBrowserManager as unknown as BrowserManager,
-      );
-
-      expect(mockBrowserManager.close).toHaveBeenCalled();
-    });
-
-    it('should handle errors during cleanup gracefully', async () => {
-      const errorManager = {
-        close: vi.fn().mockRejectedValue(new Error('Close failed')),
-      } as unknown as BrowserManager;
-
-      // Should not throw
-      await expect(cleanupBrowserAgent(errorManager)).resolves.toBeUndefined();
-    });
-  });
 });
 
 describe('buildBrowserSystemPrompt', () => {

packages/core/src/agents/browser/browserAgentFactory.ts

@@ -62,8 +62,8 @@ export async function createBrowserAgentDefinition(
     'Creating browser agent definition with isolated MCP tools...',
   );
 
-  // Create and initialize browser manager with isolated MCP client
-  const browserManager = new BrowserManager(config);
+  // Get or create browser manager singleton for this session mode/profile
+  const browserManager = BrowserManager.getInstance(config);
   await browserManager.ensureConnection();
 
   if (printOutput) {
@@ -242,19 +242,10 @@ export async function createBrowserAgentDefinition(
 }
 
 /**
- * Cleans up browser resources after agent execution.
+ * Closes all persistent browser sessions and cleans up resources.
  *
- * @param browserManager The browser manager to clean up
+ * Call this on /clear commands and CLI exit to reset browser state.
  */
-export async function cleanupBrowserAgent(
-  browserManager: BrowserManager,
-): Promise<void> {
-  try {
-    await browserManager.close();
-    debugLogger.log('Browser agent cleanup complete');
-  } catch (error) {
-    debugLogger.error(
-      `Error during browser cleanup: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
+export async function resetBrowserSession(): Promise<void> {
+  await BrowserManager.resetAll();
 }

packages/core/src/agents/browser/browserAgentInvocation.test.ts

@@ -26,7 +26,10 @@ vi.mock('../../utils/debugLogger.js', () => ({
 
 vi.mock('./browserAgentFactory.js', () => ({
   createBrowserAgentDefinition: vi.fn(),
-  cleanupBrowserAgent: vi.fn(),
+}));
+
+vi.mock('./inputBlocker.js', () => ({
+  removeInputBlocker: vi.fn(),
 }));
 
 vi.mock('../local-executor.js', () => ({
@@ -35,10 +38,8 @@ vi.mock('../local-executor.js', () => ({
   },
 }));
 
-import {
-  createBrowserAgentDefinition,
-  cleanupBrowserAgent,
-} from './browserAgentFactory.js';
+import { createBrowserAgentDefinition } from './browserAgentFactory.js';
+import { removeInputBlocker } from './inputBlocker.js';
 import { LocalAgentExecutor } from '../local-executor.js';
 import type { ToolLiveOutput } from '../../tools/tools.js';
 
@@ -190,7 +191,7 @@ describe('BrowserAgentInvocation', () => {
       vi.mocked(LocalAgentExecutor.create).mockResolvedValue(
         mockExecutor as never,
       );
-      vi.mocked(cleanupBrowserAgent).mockClear();
+      vi.mocked(removeInputBlocker).mockClear();
     });
 
     it('should return result text and call cleanup on success', async () => {
@@ -209,7 +210,7 @@ describe('BrowserAgentInvocation', () => {
       expect((result.llmContent as Array<{ text: string }>)[0].text).toContain(
         'Browser agent finished',
       );
-      expect(cleanupBrowserAgent).toHaveBeenCalled();
+      expect(removeInputBlocker).toHaveBeenCalled();
     });
 
     it('should work without updateOutput (fire-and-forget)', async () => {
@@ -239,7 +240,7 @@ describe('BrowserAgentInvocation', () => {
       const result = await invocation.execute(controller.signal);
 
       expect(result.error).toBeDefined();
-      expect(cleanupBrowserAgent).toHaveBeenCalled();
+      expect(removeInputBlocker).toHaveBeenCalled();
     });
 
     // ─── Structured SubagentProgress emission tests ───────────────────────

packages/core/src/agents/browser/browserAgentInvocation.ts

@@ -33,10 +33,7 @@ import {
   isToolActivityError,
 } from '../types.js';
 import type { MessageBus } from '../../confirmation-bus/message-bus.js';
-import {
-  createBrowserAgentDefinition,
-  cleanupBrowserAgent,
-} from './browserAgentFactory.js';
+import { createBrowserAgentDefinition } from './browserAgentFactory.js';
 import { removeInputBlocker } from './inputBlocker.js';
 import {
   sanitizeThoughtContent,
@@ -368,10 +365,9 @@ ${displayResult}
         },
       };
     } finally {
-      // Always cleanup browser resources
+      // Clean up input blocker, but keep browserManager alive for persistent sessions
       if (browserManager) {
         await removeInputBlocker(browserManager);
-        await cleanupBrowserAgent(browserManager);
       }
     }
   }

packages/core/src/agents/browser/browserManager.test.ts

@@ -9,6 +9,7 @@ import { BrowserManager } from './browserManager.js';
 import { makeFakeConfig } from '../../test-utils/config.js';
 import type { Config } from '../../config/config.js';
 import { injectAutomationOverlay } from './automationOverlay.js';
+import { injectInputBlocker } from './inputBlocker.js';
 import { coreEvents } from '../../utils/events.js';
 
 // Mock the MCP SDK
@@ -54,6 +55,13 @@ vi.mock('./automationOverlay.js', () => ({
   injectAutomationOverlay: vi.fn().mockResolvedValue(undefined),
 }));
 
+vi.mock('./inputBlocker.js', () => ({
+  injectInputBlocker: vi.fn().mockResolvedValue(undefined),
+  removeInputBlocker: vi.fn().mockResolvedValue(undefined),
+  suspendInputBlocker: vi.fn().mockResolvedValue(undefined),
+  resumeInputBlocker: vi.fn().mockResolvedValue(undefined),
+}));
+
 vi.mock('node:fs', async (importOriginal) => {
   const actual = await importOriginal<typeof import('node:fs')>();
   return {
@@ -78,6 +86,7 @@ describe('BrowserManager', () => {
   beforeEach(() => {
     vi.resetAllMocks();
     vi.mocked(injectAutomationOverlay).mockClear();
+    vi.mocked(injectInputBlocker).mockClear();
     vi.spyOn(coreEvents, 'emitFeedback').mockImplementation(() => {});
 
     // Re-establish consent mock after resetAllMocks
@@ -118,8 +127,10 @@ describe('BrowserManager', () => {
     );
   });
 
-  afterEach(() => {
+  afterEach(async () => {
     vi.restoreAllMocks();
+    // Clear singleton cache to avoid cross-test leakage
+    await BrowserManager.resetAll();
   });
 
   describe('MCP bundled path resolution', () => {
@@ -691,22 +702,198 @@ describe('BrowserManager', () => {
     });
   });
 
+  describe('getInstance', () => {
+    it('should return the same instance for the same session mode', () => {
+      const instance1 = BrowserManager.getInstance(mockConfig);
+      const instance2 = BrowserManager.getInstance(mockConfig);
+
+      expect(instance1).toBe(instance2);
+    });
+
+    it('should return different instances for different session modes', () => {
+      const isolatedConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'isolated' },
+        },
+      });
+
+      const instance1 = BrowserManager.getInstance(mockConfig);
+      const instance2 = BrowserManager.getInstance(isolatedConfig);
+
+      expect(instance1).not.toBe(instance2);
+    });
+
+    it('should return different instances for different profile paths', () => {
+      const config1 = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { profilePath: '/path/a' },
+        },
+      });
+      const config2 = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { profilePath: '/path/b' },
+        },
+      });
+
+      const instance1 = BrowserManager.getInstance(config1);
+      const instance2 = BrowserManager.getInstance(config2);
+
+      expect(instance1).not.toBe(instance2);
+    });
+  });
+
+  describe('resetAll', () => {
+    it('should close all instances and clear the cache', async () => {
+      const instance1 = BrowserManager.getInstance(mockConfig);
+      await instance1.ensureConnection();
+
+      const isolatedConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'isolated' },
+        },
+      });
+      const instance2 = BrowserManager.getInstance(isolatedConfig);
+      await instance2.ensureConnection();
+
+      await BrowserManager.resetAll();
+
+      // After resetAll, getInstance should return new instances
+      const instance3 = BrowserManager.getInstance(mockConfig);
+      expect(instance3).not.toBe(instance1);
+    });
+
+    it('should handle errors during cleanup gracefully', async () => {
+      const instance = BrowserManager.getInstance(mockConfig);
+      await instance.ensureConnection();
+
+      // Make close throw by overriding the client's close method
+      const client = await instance.getRawMcpClient();
+      vi.mocked(client.close).mockRejectedValueOnce(new Error('close failed'));
+
+      // Should not throw
+      await expect(BrowserManager.resetAll()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('isConnected', () => {
+    it('should return false before connection', () => {
+      const manager = new BrowserManager(mockConfig);
+      expect(manager.isConnected()).toBe(false);
+    });
+
+    it('should return true after successful connection', async () => {
+      const manager = new BrowserManager(mockConfig);
+      await manager.ensureConnection();
+      expect(manager.isConnected()).toBe(true);
+    });
+
+    it('should return false after close', async () => {
+      const manager = new BrowserManager(mockConfig);
+      await manager.ensureConnection();
+      await manager.close();
+      expect(manager.isConnected()).toBe(false);
+    });
+  });
+
+  describe('reconnection', () => {
+    it('should reconnect after unexpected disconnect', async () => {
+      const manager = new BrowserManager(mockConfig);
+      await manager.ensureConnection();
+
+      // Simulate transport closing unexpectedly via the onclose callback
+      const transportInstance =
+        vi.mocked(StdioClientTransport).mock.results[0]?.value;
+      if (transportInstance?.onclose) {
+        transportInstance.onclose();
+      }
+
+      // Manager should recognize disconnection
+      expect(manager.isConnected()).toBe(false);
+
+      // ensureConnection should reconnect
+      await manager.ensureConnection();
+      expect(manager.isConnected()).toBe(true);
+    });
+  });
+
+  describe('concurrency', () => {
+    it('should not call connectMcp twice when ensureConnection is called concurrently', async () => {
+      const manager = new BrowserManager(mockConfig);
+
+      // Call ensureConnection twice simultaneously without awaiting the first
+      const [p1, p2] = [manager.ensureConnection(), manager.ensureConnection()];
+      await Promise.all([p1, p2]);
+
+      // connectMcp (via StdioClientTransport constructor) should only have been called once
+      // Each connection attempt creates a new StdioClientTransport
+    });
+  });
+
   describe('overlay re-injection in callTool', () => {
-    it('should re-inject overlay after click in non-headless mode', async () => {
+    it('should re-inject overlay and input blocker after click in non-headless mode when input disabling is enabled', async () => {
+      // Enable input disabling in config
+      mockConfig = makeFakeConfig({
+        agents: {
+          overrides: {
+            browser_agent: {
+              enabled: true,
+            },
+          },
+          browser: {
+            headless: false,
+            disableUserInput: true,
+          },
+        },
+      });
+
       const manager = new BrowserManager(mockConfig);
       await manager.callTool('click', { uid: '1_2' });
 
       expect(injectAutomationOverlay).toHaveBeenCalledWith(manager, undefined);
+      expect(injectInputBlocker).toHaveBeenCalledWith(manager, undefined);
     });
 
-    it('should re-inject overlay after navigate_page in non-headless mode', async () => {
+    it('should re-inject overlay and input blocker after navigate_page in non-headless mode when input disabling is enabled', async () => {
+      mockConfig = makeFakeConfig({
+        agents: {
+          overrides: {
+            browser_agent: {
+              enabled: true,
+            },
+          },
+          browser: {
+            headless: false,
+            disableUserInput: true,
+          },
+        },
+      });
+
       const manager = new BrowserManager(mockConfig);
       await manager.callTool('navigate_page', { url: 'https://example.com' });
 
       expect(injectAutomationOverlay).toHaveBeenCalledWith(manager, undefined);
+      expect(injectInputBlocker).toHaveBeenCalledWith(manager, undefined);
     });
 
-    it('should re-inject overlay after click_at, new_page, press_key, handle_dialog', async () => {
+    it('should re-inject overlay and input blocker after click_at, new_page, press_key, handle_dialog when input disabling is enabled', async () => {
+      mockConfig = makeFakeConfig({
+        agents: {
+          overrides: {
+            browser_agent: {
+              enabled: true,
+            },
+          },
+          browser: {
+            headless: false,
+            disableUserInput: true,
+          },
+        },
+      });
+
       const manager = new BrowserManager(mockConfig);
       for (const tool of [
         'click_at',
@@ -715,12 +902,15 @@ describe('BrowserManager', () => {
         'handle_dialog',
       ]) {
         vi.mocked(injectAutomationOverlay).mockClear();
+        vi.mocked(injectInputBlocker).mockClear();
         await manager.callTool(tool, {});
         expect(injectAutomationOverlay).toHaveBeenCalledTimes(1);
+        expect(injectInputBlocker).toHaveBeenCalledTimes(1);
+        expect(injectInputBlocker).toHaveBeenCalledWith(manager, undefined);
       }
     });
 
-    it('should NOT re-inject overlay after read-only tools', async () => {
+    it('should NOT re-inject overlay or input blocker after read-only tools', async () => {
       const manager = new BrowserManager(mockConfig);
       for (const tool of [
         'take_snapshot',
@@ -729,8 +919,10 @@ describe('BrowserManager', () => {
         'fill',
       ]) {
         vi.mocked(injectAutomationOverlay).mockClear();
+        vi.mocked(injectInputBlocker).mockClear();
         await manager.callTool(tool, {});
         expect(injectAutomationOverlay).not.toHaveBeenCalled();
+        expect(injectInputBlocker).not.toHaveBeenCalled();
       }
     });
 
@@ -763,8 +955,6 @@ describe('BrowserManager', () => {
 
       const manager = new BrowserManager(mockConfig);
       await manager.callTool('click', { uid: 'bad' });
-
-      expect(injectAutomationOverlay).not.toHaveBeenCalled();
     });
   });
 

packages/core/src/agents/browser/browserManager.ts

@@ -40,6 +40,12 @@ const BROWSER_PROFILE_DIR = 'cli-browser-profile';
 // Default timeout for MCP operations
 const MCP_TIMEOUT_MS = 60_000;
 
+// Maximum reconnection attempts before giving up
+const MAX_RECONNECT_RETRIES = 3;
+
+// Base delay (ms) for exponential backoff between reconnection attempts
+const RECONNECT_BASE_DELAY_MS = 500;
+
 /**
  * Tools that can cause a full-page navigation (explicitly or implicitly).
  *
@@ -92,10 +98,73 @@ export interface McpToolCallResult {
  * in the main ToolRegistry. Tools are kept local to the browser agent.
  */
 export class BrowserManager {
+  // --- Static singleton management ---
+  private static instances = new Map<string, BrowserManager>();
+
+  /**
+   * Returns the cache key for a given config.
+   * Uses `sessionMode:profilePath` so different profiles get separate instances.
+   */
+  private static getInstanceKey(config: Config): string {
+    const browserConfig = config.getBrowserAgentConfig();
+    const sessionMode = browserConfig.customConfig.sessionMode ?? 'persistent';
+    const profilePath = browserConfig.customConfig.profilePath ?? 'default';
+    return `${sessionMode}:${profilePath}`;
+  }
+
+  /**
+   * Returns an existing BrowserManager for the current config's session mode
+   * and profile, or creates a new one.
+   */
+  static getInstance(config: Config): BrowserManager {
+    const key = BrowserManager.getInstanceKey(config);
+    let instance = BrowserManager.instances.get(key);
+    if (!instance) {
+      instance = new BrowserManager(config);
+      BrowserManager.instances.set(key, instance);
+      debugLogger.log(`Created new BrowserManager singleton (key: ${key})`);
+    } else {
+      debugLogger.log(
+        `Reusing existing BrowserManager singleton (key: ${key})`,
+      );
+    }
+    return instance;
+  }
+
+  /**
+   * Closes all cached BrowserManager instances and clears the cache.
+   * Called on /clear commands and CLI exit.
+   */
+  static async resetAll(): Promise<void> {
+    const results = await Promise.allSettled(
+      Array.from(BrowserManager.instances.values()).map((instance) =>
+        instance.close(),
+      ),
+    );
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        debugLogger.error(
+          `Error during BrowserManager cleanup: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`,
+        );
+      }
+    }
+    BrowserManager.instances.clear();
+  }
+
+  /**
+   * Alias for resetAll — used by CLI exit cleanup for clarity.
+   */
+  static async closeAll(): Promise<void> {
+    await BrowserManager.resetAll();
+  }
+
+  // --- Instance state ---
   // Raw MCP SDK Client - NOT the wrapper McpClient
   private rawMcpClient: Client | undefined;
   private mcpTransport: StdioClientTransport | undefined;
   private discoveredTools: McpTool[] = [];
+  private disconnected = false;
+  private connectionPromise: Promise<void> | undefined;
 
   /** State for action rate limiting */
   private actionCounter = 0;
@@ -215,6 +284,10 @@ export class BrowserManager {
     // Re-inject the automation overlay and input blocker after tools that
     // can cause a full-page navigation. chrome-devtools-mcp emits no MCP
     // notifications, so callTool() is the only interception point.
+    //
+    // The input blocker injection is idempotent: the injected function
+    // reuses the existing DOM element when present and only recreates
+    // it when navigation has actually replaced the page DOM.
     if (
       !result.isError &&
       POTENTIALLY_NAVIGATING_TOOLS.has(toolName) &&
@@ -224,17 +297,8 @@ export class BrowserManager {
         if (this.shouldInjectOverlay) {
           await injectAutomationOverlay(this, signal);
         }
-        // Only re-inject the input blocker for tools that *reliably*
-        // replace the page DOM (navigate_page, new_page, select_page).
-        // click/click_at are handled by pointer-events suspend/resume
-        // in mcpToolWrapper — no full re-inject roundtrip needed.
-        // press_key/handle_dialog only sometimes navigate.
-        const reliableNavigation =
-          toolName === 'navigate_page' ||
-          toolName === 'new_page' ||
-          toolName === 'select_page';
-        if (this.shouldDisableInput && reliableNavigation) {
-          await injectInputBlocker(this);
+        if (this.shouldDisableInput) {
+          await injectInputBlocker(this, signal);
         }
       } catch {
         // Never let overlay/blocker failures interrupt the tool result
@@ -271,14 +335,53 @@ export class BrowserManager {
     };
   }
 
+  /**
+   * Returns whether the MCP client is currently connected and healthy.
+   */
+  isConnected(): boolean {
+    return this.rawMcpClient !== undefined && !this.disconnected;
+  }
+
   /**
    * Ensures browser and MCP client are connected.
+   * If a previous connection was lost (e.g., user closed the browser),
+   * this will reconnect with exponential backoff (up to MAX_RECONNECT_RETRIES).
+   *
+   * Concurrent callers share a single in-flight connection promise so that
+   * two subagents racing at startup do not trigger duplicate connectMcp() calls.
    */
   async ensureConnection(): Promise<void> {
-    if (this.rawMcpClient) {
+    // Already connected and healthy — nothing to do
+    if (this.rawMcpClient && !this.disconnected) {
       return;
     }
 
+    // A connection is already being established — wait for it instead of racing
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+
+    // If previously connected but transport died, clean up before reconnecting
+    if (this.disconnected) {
+      debugLogger.log(
+        'Previous browser connection was lost. Cleaning up before reconnecting...',
+      );
+      await this.close();
+      this.disconnected = false;
+    }
+
+    // Start connecting; store the promise so concurrent callers can join it
+    this.connectionPromise = this.connectWithRetry().finally(() => {
+      this.connectionPromise = undefined;
+    });
+
+    return this.connectionPromise;
+  }
+
+  /**
+   * Connects to chrome-devtools-mcp with exponential backoff retry.
+   */
+  private async connectWithRetry(): Promise<void> {
     // Request browser consent if needed (first-run privacy notice)
     const consentGranted = await getBrowserConsentIfNeeded();
     if (!consentGranted) {
@@ -288,7 +391,23 @@ export class BrowserManager {
       );
     }
 
-    await this.connectMcp();
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt < MAX_RECONNECT_RETRIES; attempt++) {
+      try {
+        await this.connectMcp();
+        return;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < MAX_RECONNECT_RETRIES - 1) {
+          const delay = RECONNECT_BASE_DELAY_MS * Math.pow(2, attempt);
+          debugLogger.log(
+            `Connection attempt ${attempt + 1} failed, retrying in ${delay}ms...`,
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastError!;
   }
 
   /**
@@ -322,6 +441,7 @@ export class BrowserManager {
     }
 
     this.discoveredTools = [];
+    this.connectionPromise = undefined;
   }
 
   /**
@@ -447,7 +567,7 @@ export class BrowserManager {
         'chrome-devtools-mcp transport closed unexpectedly. ' +
           'The MCP server process may have crashed.',
       );
-      this.rawMcpClient = undefined;
+      this.disconnected = true;
     };
     this.mcpTransport.onerror = (error: Error) => {
       debugLogger.error(

packages/core/src/agents/browser/inputBlocker.test.ts

@@ -5,7 +5,12 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { injectInputBlocker, removeInputBlocker } from './inputBlocker.js';
+import {
+  injectInputBlocker,
+  removeInputBlocker,
+  suspendInputBlocker,
+  resumeInputBlocker,
+} from './inputBlocker.js';
 import type { BrowserManager } from './browserManager.js';
 
 describe('inputBlocker', () => {
@@ -28,6 +33,7 @@ describe('inputBlocker', () => {
         {
           function: expect.stringContaining('__gemini_input_blocker'),
         },
+        undefined,
       );
     });
 
@@ -77,6 +83,29 @@ describe('inputBlocker', () => {
         injectInputBlocker(mockBrowserManager),
       ).resolves.toBeUndefined();
     });
+
+    it('should be safe to call multiple times (idempotent injection)', async () => {
+      await injectInputBlocker(mockBrowserManager);
+      await injectInputBlocker(mockBrowserManager);
+
+      expect(mockBrowserManager.callTool).toHaveBeenCalledTimes(2);
+      expect(mockBrowserManager.callTool).toHaveBeenNthCalledWith(
+        1,
+        'evaluate_script',
+        expect.objectContaining({
+          function: expect.stringContaining('__gemini_input_blocker'),
+        }),
+        undefined,
+      );
+      expect(mockBrowserManager.callTool).toHaveBeenNthCalledWith(
+        2,
+        'evaluate_script',
+        expect.objectContaining({
+          function: expect.stringContaining('__gemini_input_blocker'),
+        }),
+        undefined,
+      );
+    });
   });
 
   describe('removeInputBlocker', () => {
@@ -88,6 +117,7 @@ describe('inputBlocker', () => {
         {
           function: expect.stringContaining('__gemini_input_blocker'),
         },
+        undefined,
       );
     });
 
@@ -110,4 +140,38 @@ describe('inputBlocker', () => {
       ).resolves.toBeUndefined();
     });
   });
+
+  describe('suspendInputBlocker and resumeInputBlocker', () => {
+    it('should not throw when blocker element is missing', async () => {
+      // Simulate evaluate_script resolving successfully even if the DOM element is absent.
+      mockBrowserManager.callTool = vi.fn().mockResolvedValue({
+        content: [{ type: 'text', text: 'Script ran on page and returned:' }],
+      });
+
+      await expect(
+        suspendInputBlocker(mockBrowserManager),
+      ).resolves.toBeUndefined();
+      await expect(
+        resumeInputBlocker(mockBrowserManager),
+      ).resolves.toBeUndefined();
+
+      expect(mockBrowserManager.callTool).toHaveBeenCalledTimes(2);
+      expect(mockBrowserManager.callTool).toHaveBeenNthCalledWith(
+        1,
+        'evaluate_script',
+        expect.objectContaining({
+          function: expect.stringContaining('__gemini_input_blocker'),
+        }),
+        undefined,
+      );
+      expect(mockBrowserManager.callTool).toHaveBeenNthCalledWith(
+        2,
+        'evaluate_script',
+        expect.objectContaining({
+          function: expect.stringContaining('__gemini_input_blocker'),
+        }),
+        undefined,
+      );
+    });
+  });
 });

packages/core/src/agents/browser/inputBlocker.ts

@@ -198,11 +198,14 @@ const RESUME_BLOCKER_FUNCTION = `() => {
  */
 export async function injectInputBlocker(
   browserManager: BrowserManager,
+  signal?: AbortSignal,
 ): Promise<void> {
   try {
-    await browserManager.callTool('evaluate_script', {
-      function: INPUT_BLOCKER_FUNCTION,
-    });
+    await browserManager.callTool(
+      'evaluate_script',
+      { function: INPUT_BLOCKER_FUNCTION },
+      signal,
+    );
     debugLogger.log('Input blocker injected successfully');
   } catch (error) {
     // Log but don't throw - input blocker is a UX enhancement, not critical functionality
@@ -222,11 +225,14 @@ export async function injectInputBlocker(
  */
 export async function removeInputBlocker(
   browserManager: BrowserManager,
+  signal?: AbortSignal,
 ): Promise<void> {
   try {
-    await browserManager.callTool('evaluate_script', {
-      function: REMOVE_BLOCKER_FUNCTION,
-    });
+    await browserManager.callTool(
+      'evaluate_script',
+      { function: REMOVE_BLOCKER_FUNCTION },
+      signal,
+    );
     debugLogger.log('Input blocker removed successfully');
   } catch (error) {
     // Log but don't throw - removal failure is not critical
@@ -244,11 +250,14 @@ export async function removeInputBlocker(
  */
 export async function suspendInputBlocker(
   browserManager: BrowserManager,
+  signal?: AbortSignal,
 ): Promise<void> {
   try {
-    await browserManager.callTool('evaluate_script', {
-      function: SUSPEND_BLOCKER_FUNCTION,
-    });
+    await browserManager.callTool(
+      'evaluate_script',
+      { function: SUSPEND_BLOCKER_FUNCTION },
+      signal,
+    );
   } catch {
     // Non-critical — tool call will still attempt to proceed
   }
@@ -260,11 +269,14 @@ export async function suspendInputBlocker(
  */
 export async function resumeInputBlocker(
   browserManager: BrowserManager,
+  signal?: AbortSignal,
 ): Promise<void> {
   try {
-    await browserManager.callTool('evaluate_script', {
-      function: RESUME_BLOCKER_FUNCTION,
-    });
+    await browserManager.callTool(
+      'evaluate_script',
+      { function: RESUME_BLOCKER_FUNCTION },
+      signal,
+    );
   } catch {
     // Non-critical
   }

packages/core/src/agents/browser/mcpToolWrapper.test.ts

@@ -224,6 +224,7 @@ describe('mcpToolWrapper', () => {
         expect.objectContaining({
           function: expect.stringContaining('__gemini_input_blocker'),
         }),
+        expect.any(AbortSignal),
       );
 
       // Second call: click
@@ -241,6 +242,7 @@ describe('mcpToolWrapper', () => {
         expect.objectContaining({
           function: expect.stringContaining('__gemini_input_blocker'),
         }),
+        expect.any(AbortSignal),
       );
     });
 

packages/core/src/agents/browser/mcpToolWrapper.ts

@@ -129,7 +129,7 @@ class McpToolInvocation extends BaseToolInvocation<
       // chrome-devtools-mcp's interactability checks pass.
       // Only toggles pointer-events CSS — no DOM change, no flicker.
       if (this.needsBlockerSuspend) {
-        await suspendInputBlocker(this.browserManager);
+        await suspendInputBlocker(this.browserManager, signal);
       }
 
       const result: McpToolCallResult = await this.browserManager.callTool(
@@ -155,7 +155,7 @@ class McpToolInvocation extends BaseToolInvocation<
 
       // Resume input blocker after interactive tool completes.
       if (this.needsBlockerSuspend) {
-        await resumeInputBlocker(this.browserManager);
+        await resumeInputBlocker(this.browserManager, signal);
       }
 
       if (result.isError) {
@@ -181,7 +181,7 @@ class McpToolInvocation extends BaseToolInvocation<
 
       // Resume on error path too so the blocker is always restored
       if (this.needsBlockerSuspend) {
-        await resumeInputBlocker(this.browserManager).catch(() => {});
+        await resumeInputBlocker(this.browserManager, signal).catch(() => {});
       }
 
       debugLogger.error(`MCP tool ${this.toolName} failed: ${errorMsg}`);

packages/core/src/agents/local-executor.test.ts

@@ -69,6 +69,10 @@ import {
   type FunctionDeclaration,
 } from '@google/genai';
 import type { Config } from '../config/config.js';
+import type { AgentLoopContext } from '../config/agent-loop-context.js';
+import type { GeminiClient } from '../core/client.js';
+import type { SandboxManager } from '../services/sandboxManager.js';
+import type { MessageBus } from '../confirmation-bus/message-bus.js';
 import { MockTool } from '../test-utils/mock-tool.js';
 import { getDirectoryContextString } from '../utils/environmentContext.js';
 import { z } from 'zod';
@@ -377,10 +381,8 @@ describe('LocalAgentExecutor', () => {
   describe('create (Initialization and Validation)', () => {
     it('should explicitly map execution context properties to prevent unintended propagation', async () => {
       const definition = createTestDefinition([LS_TOOL_NAME]);
-      const mockGeminiClient =
-        {} as unknown as import('../core/client.js').GeminiClient;
-      const mockSandboxManager =
-        {} as unknown as import('../services/sandboxManager.js').SandboxManager;
+      const mockGeminiClient = {} as unknown as GeminiClient;
+      const mockSandboxManager = {} as unknown as SandboxManager;
       const extendedContext = {
         config: mockConfig,
         promptId: mockConfig.promptId,
@@ -391,7 +393,7 @@ describe('LocalAgentExecutor', () => {
         geminiClient: mockGeminiClient,
         sandboxManager: mockSandboxManager,
         unintendedProperty: 'should not be here',
-      } as unknown as import('../config/agent-loop-context.js').AgentLoopContext;
+      } as unknown as AgentLoopContext;
 
       const executor = await LocalAgentExecutor.create(
         definition,
@@ -414,7 +416,7 @@ describe('LocalAgentExecutor', () => {
 
       expect(executionContext).toBeDefined();
       expect(executionContext.config).toBe(extendedContext.config);
-      expect(executionContext.promptId).toBe(extendedContext.promptId);
+      expect(executionContext.promptId).toBeDefined();
       expect(executionContext.geminiClient).toBe(extendedContext.geminiClient);
       expect(executionContext.sandboxManager).toBe(
         extendedContext.sandboxManager,
@@ -445,7 +447,99 @@ describe('LocalAgentExecutor', () => {
       expect(executionContext.messageBus).not.toBe(extendedContext.messageBus);
     });
 
-    it('should create successfully with allowed tools', async () => {
+    it('should propagate parentSessionId from context when creating executionContext', async () => {
+      const parentSessionId = 'top-level-session-id';
+      const currentPromptId = 'subagent-a-id';
+      const mockGeminiClient = {} as unknown as GeminiClient;
+      const mockSandboxManager = {} as unknown as SandboxManager;
+      const mockMessageBus = {
+        derive: () => ({}),
+      } as unknown as MessageBus;
+      const mockToolRegistry = {
+        getMessageBus: () => mockMessageBus,
+        getAllToolNames: () => [],
+        sortTools: () => {},
+      } as unknown as ToolRegistry;
+
+      const context = {
+        config: mockConfig,
+        promptId: currentPromptId,
+        parentSessionId,
+        toolRegistry: mockToolRegistry,
+        promptRegistry: {} as unknown as PromptRegistry,
+        resourceRegistry: {} as unknown as ResourceRegistry,
+        geminiClient: mockGeminiClient,
+        sandboxManager: mockSandboxManager,
+        messageBus: mockMessageBus,
+      } as unknown as AgentLoopContext;
+
+      const definition = createTestDefinition([]);
+      const executor = await LocalAgentExecutor.create(definition, context);
+
+      mockModelResponse([
+        {
+          name: TASK_COMPLETE_TOOL_NAME,
+          args: { finalResult: 'done' },
+          id: 'call1',
+        },
+      ]);
+
+      await executor.run({ goal: 'test' }, signal);
+
+      const chatConstructorArgs =
+        MockedGeminiChat.mock.calls[MockedGeminiChat.mock.calls.length - 1];
+      const executionContext = chatConstructorArgs[0];
+
+      expect(executionContext.parentSessionId).toBe(parentSessionId);
+      expect(executionContext.promptId).toBe(executor['agentId']);
+    });
+
+    it('should fall back to promptId if parentSessionId is missing (top-level subagent)', async () => {
+      const rootSessionId = 'root-session-id';
+      const mockGeminiClient = {} as unknown as GeminiClient;
+      const mockSandboxManager = {} as unknown as SandboxManager;
+      const mockMessageBus = {
+        derive: () => ({}),
+      } as unknown as MessageBus;
+      const mockToolRegistry = {
+        getMessageBus: () => mockMessageBus,
+        getAllToolNames: () => [],
+        sortTools: () => {},
+      } as unknown as ToolRegistry;
+
+      const context = {
+        config: mockConfig,
+        promptId: rootSessionId,
+        // parentSessionId is undefined
+        toolRegistry: mockToolRegistry,
+        promptRegistry: {} as unknown as PromptRegistry,
+        resourceRegistry: {} as unknown as ResourceRegistry,
+        geminiClient: mockGeminiClient,
+        sandboxManager: mockSandboxManager,
+        messageBus: mockMessageBus,
+      } as unknown as AgentLoopContext;
+
+      const definition = createTestDefinition([]);
+      const executor = await LocalAgentExecutor.create(definition, context);
+
+      mockModelResponse([
+        {
+          name: TASK_COMPLETE_TOOL_NAME,
+          args: { finalResult: 'done' },
+          id: 'call1',
+        },
+      ]);
+
+      await executor.run({ goal: 'test' }, signal);
+
+      const chatConstructorArgs =
+        MockedGeminiChat.mock.calls[MockedGeminiChat.mock.calls.length - 1];
+      const executionContext = chatConstructorArgs[0];
+
+      expect(executionContext.parentSessionId).toBe(rootSessionId);
+      expect(executionContext.promptId).toBe(executor['agentId']);
+    });
+    it('should successfully with allowed tools', async () => {
       const definition = createTestDefinition([LS_TOOL_NAME]);
       const executor = await LocalAgentExecutor.create(
         definition,
@@ -500,9 +594,7 @@ describe('LocalAgentExecutor', () => {
         onActivity,
       );
 
-      expect(executor['agentId']).toMatch(
-        new RegExp(`^${parentId}-${definition.name}-`),
-      );
+      expect(executor['agentId']).toBeDefined();
     });
 
     it('should correctly apply templates to initialMessages', async () => {

packages/core/src/agents/local-executor.ts

@@ -121,7 +121,8 @@ export class LocalAgentExecutor<TOutput extends z.ZodTypeAny> {
   private get executionContext(): AgentLoopContext {
     return {
       config: this.context.config,
-      promptId: this.context.promptId,
+      promptId: this.agentId,
+      parentSessionId: this.context.parentSessionId || this.context.promptId, // Always preserve the main agent session ID
       geminiClient: this.context.geminiClient,
       sandboxManager: this.context.sandboxManager,
       toolRegistry: this.toolRegistry,
@@ -255,9 +256,6 @@ export class LocalAgentExecutor<TOutput extends z.ZodTypeAny> {
 
     agentToolRegistry.sortTools();
 
-    // Get the parent prompt ID from context
-    const parentPromptId = context.promptId;
-
     // Get the parent tool call ID from context
     const toolContext = getToolCallContext();
     const parentCallId = toolContext?.callId;
@@ -265,7 +263,6 @@ export class LocalAgentExecutor<TOutput extends z.ZodTypeAny> {
     return new LocalAgentExecutor(
       definition,
       context,
-      parentPromptId,
       agentToolRegistry,
       agentPromptRegistry,
       agentResourceRegistry,
@@ -283,7 +280,6 @@ export class LocalAgentExecutor<TOutput extends z.ZodTypeAny> {
   private constructor(
     definition: LocalAgentDefinition<TOutput>,
     context: AgentLoopContext,
-    parentPromptId: string | undefined,
     toolRegistry: ToolRegistry,
     promptRegistry: PromptRegistry,
     resourceRegistry: ResourceRegistry,
@@ -299,11 +295,7 @@ export class LocalAgentExecutor<TOutput extends z.ZodTypeAny> {
     this.compressionService = new ChatCompressionService();
     this.parentCallId = parentCallId;
 
-    const randomIdPart = Math.random().toString(36).slice(2, 8);
-    // parentPromptId will be undefined if this agent is invoked directly
-    // (top-level), rather than as a sub-agent.
-    const parentPrefix = parentPromptId ? `${parentPromptId}-` : '';
-    this.agentId = `${parentPrefix}${this.definition.name}-${randomIdPart}`;
+    this.agentId = Math.random().toString(36).slice(2, 8);
   }
 
   /**

packages/core/src/code_assist/setup.ts

@@ -32,6 +32,7 @@ export class ProjectIdRequiredError extends Error {
     super(
       'This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID env var. See https://goo.gle/gemini-cli-auth-docs#workspace-gca',
     );
+    this.name = 'ProjectIdRequiredError';
   }
 }
 
@@ -42,6 +43,7 @@ export class ProjectIdRequiredError extends Error {
 export class ValidationCancelledError extends Error {
   constructor() {
     super('User cancelled account validation');
+    this.name = 'ValidationCancelledError';
   }
 }
 
@@ -51,6 +53,7 @@ export class IneligibleTierError extends Error {
   constructor(ineligibleTiers: IneligibleTier[]) {
     const reasons = ineligibleTiers.map((t) => t.reasonMessage).join(', ');
     super(reasons);
+    this.name = 'IneligibleTierError';
     this.ineligibleTiers = ineligibleTiers;
   }
 }

packages/core/src/config/agent-loop-context.ts

@@ -23,6 +23,9 @@ export interface AgentLoopContext {
   /** The unique ID for the current user turn or agent thought loop. */
   readonly promptId: string;
 
+  /** The unique ID for the parent session if this is a subagent. */
+  readonly parentSessionId?: string;
+
   /** The registry of tools available to the agent in this context. */
   readonly toolRegistry: ToolRegistry;
 

packages/core/src/config/config.ts

@@ -10,6 +10,8 @@ import { SandboxPolicyManager } from '../policy/sandboxPolicyManager.js';
 import { inspect } from 'node:util';
 import process from 'node:process';
 import { z } from 'zod';
+import type { ConversationRecord } from '../services/chatRecordingService.js';
+export type { ConversationRecord };
 import {
   AuthType,
   createContentGenerator,
@@ -231,6 +233,25 @@ export interface ResolvedExtensionSetting {
   source?: string;
 }
 
+export interface TrajectoryProvider {
+  /** Prefix used to identify sessions from this provider (e.g., 'ext:') */
+  prefix: string;
+  /** Optional display name for UI Tabs */
+  displayName?: string;
+  /** Return an array of conversational tags/ids */
+  listSessions(workspaceUri?: string): Promise<
+    Array<{
+      id: string;
+      mtime: string;
+      name?: string;
+      displayName?: string;
+      messageCount?: number;
+    }>
+  >;
+  /** Load a single conversation payload */
+  loadSession(id: string): Promise<ConversationRecord | null>;
+}
+
 export interface AgentRunConfig {
   maxTimeMinutes?: number;
   maxTurns?: number;
@@ -386,6 +407,8 @@ export interface GeminiCLIExtension {
    * Used to migrate an extension to a new repository source.
    */
   migratedTo?: string;
+  /** Loaded JS module for trajectory decoding */
+  trajectoryProviderModule?: TrajectoryProvider;
 }
 
 export interface ExtensionInstallMetadata {
@@ -921,7 +944,9 @@ export class Config implements McpContext, AgentLoopContext {
           networkAccess: false,
         };
 
-    this._sandboxManager = createSandboxManager(this.sandbox, params.targetDir);
+    this._sandboxManager = createSandboxManager(this.sandbox, {
+      workspace: params.targetDir,
+    });
 
     if (
       !(this._sandboxManager instanceof NoopSandboxManager) &&
@@ -942,8 +967,10 @@ export class Config implements McpContext, AgentLoopContext {
       'default';
     this._sandboxManager = createSandboxManager(
       this.sandbox,
-      params.targetDir,
-      this._sandboxPolicyManager,
+      {
+        workspace: params.targetDir,
+        policyManager: this._sandboxPolicyManager,
+      },
       initialApprovalMode,
     );
 
@@ -1595,8 +1622,10 @@ export class Config implements McpContext, AgentLoopContext {
   private refreshSandboxManager(): void {
     this._sandboxManager = createSandboxManager(
       this.sandbox,
-      this.targetDir,
-      this._sandboxPolicyManager,
+      {
+        workspace: this.targetDir,
+        policyManager: this._sandboxPolicyManager,
+      },
       this.getApprovalMode(),
     );
     this.shellExecutionConfig.sandboxManager = this._sandboxManager;
@@ -2413,6 +2442,7 @@ export class Config implements McpContext, AgentLoopContext {
 
     if (isPlanModeTransition || isYoloModeTransition) {
       if (this._geminiClient?.isInitialized()) {
+        this._geminiClient.clearCurrentSequenceModel();
         this._geminiClient.setTools().catch((err) => {
           debugLogger.error('Failed to update tools', err);
         });

packages/core/src/core/client.ts

@@ -132,6 +132,10 @@ export class GeminiClient {
     this.updateSystemInstruction();
   };
 
+  clearCurrentSequenceModel(): void {
+    this.currentSequenceModel = null;
+  }
+
   // Hook state to deduplicate BeforeAgent calls and track response for
   // AfterAgent
   private hookStateMap = new Map<

packages/core/src/core/contentGenerator.test.ts

@@ -10,7 +10,6 @@ import {
   AuthType,
   createContentGeneratorConfig,
   type ContentGenerator,
-  validateBaseUrl,
 } from './contentGenerator.js';
 import { createCodeAssistContentGenerator } from '../code_assist/codeAssist.js';
 import { GoogleGenAI } from '@google/genai';
@@ -605,122 +604,6 @@ describe('createContentGenerator', () => {
     );
   });
 
-  it('should pass GOOGLE_GEMINI_BASE_URL as httpOptions.baseUrl for Gemini API', async () => {
-    const mockConfig = {
-      getModel: vi.fn().mockReturnValue('gemini-pro'),
-      getProxy: vi.fn().mockReturnValue(undefined),
-      getUsageStatisticsEnabled: () => false,
-      getClientName: vi.fn().mockReturnValue(undefined),
-    } as unknown as Config;
-
-    const mockGenerator = {
-      models: {},
-    } as unknown as GoogleGenAI;
-    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
-    vi.stubEnv('GOOGLE_GEMINI_BASE_URL', 'https://my-gemini-proxy.example.com');
-
-    await createContentGenerator(
-      {
-        apiKey: 'test-api-key',
-        authType: AuthType.USE_GEMINI,
-      },
-      mockConfig,
-    );
-
-    expect(GoogleGenAI).toHaveBeenCalledWith(
-      expect.objectContaining({
-        httpOptions: expect.objectContaining({
-          baseUrl: 'https://my-gemini-proxy.example.com',
-        }),
-      }),
-    );
-  });
-
-  it('should pass GOOGLE_VERTEX_BASE_URL as httpOptions.baseUrl for Vertex AI', async () => {
-    const mockConfig = {
-      getModel: vi.fn().mockReturnValue('gemini-pro'),
-      getProxy: vi.fn().mockReturnValue(undefined),
-      getUsageStatisticsEnabled: () => false,
-      getClientName: vi.fn().mockReturnValue(undefined),
-    } as unknown as Config;
-
-    const mockGenerator = {
-      models: {},
-    } as unknown as GoogleGenAI;
-    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
-    vi.stubEnv('GOOGLE_VERTEX_BASE_URL', 'https://my-vertex-proxy.example.com');
-
-    await createContentGenerator(
-      {
-        apiKey: 'test-api-key',
-        vertexai: true,
-        authType: AuthType.USE_VERTEX_AI,
-      },
-      mockConfig,
-    );
-
-    expect(GoogleGenAI).toHaveBeenCalledWith(
-      expect.objectContaining({
-        httpOptions: expect.objectContaining({
-          baseUrl: 'https://my-vertex-proxy.example.com',
-        }),
-      }),
-    );
-  });
-
-  it('should not include baseUrl in httpOptions when GOOGLE_GEMINI_BASE_URL is not set', async () => {
-    vi.stubEnv('GOOGLE_GEMINI_BASE_URL', '');
-
-    const mockConfig = {
-      getModel: vi.fn().mockReturnValue('gemini-pro'),
-      getProxy: vi.fn().mockReturnValue(undefined),
-      getUsageStatisticsEnabled: () => false,
-      getClientName: vi.fn().mockReturnValue(undefined),
-    } as unknown as Config;
-
-    const mockGenerator = {
-      models: {},
-    } as unknown as GoogleGenAI;
-    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
-
-    await createContentGenerator(
-      {
-        apiKey: 'test-api-key',
-        authType: AuthType.USE_GEMINI,
-      },
-      mockConfig,
-    );
-
-    expect(GoogleGenAI).toHaveBeenCalledWith(
-      expect.not.objectContaining({
-        httpOptions: expect.objectContaining({
-          baseUrl: expect.any(String),
-        }),
-      }),
-    );
-  });
-
-  it('should reject an insecure GOOGLE_GEMINI_BASE_URL for non-local hosts', async () => {
-    const mockConfig = {
-      getModel: vi.fn().mockReturnValue('gemini-pro'),
-      getProxy: vi.fn().mockReturnValue(undefined),
-      getUsageStatisticsEnabled: () => false,
-      getClientName: vi.fn().mockReturnValue(undefined),
-    } as unknown as Config;
-
-    vi.stubEnv('GOOGLE_GEMINI_BASE_URL', 'http://evil-proxy.example.com');
-
-    await expect(
-      createContentGenerator(
-        {
-          apiKey: 'test-api-key',
-          authType: AuthType.USE_GEMINI,
-        },
-        mockConfig,
-      ),
-    ).rejects.toThrow('Custom base URL must use HTTPS unless it is localhost.');
-  });
-
   it('should pass apiVersion for Vertex AI when GOOGLE_GENAI_API_VERSION is set', async () => {
     const mockConfig = {
       getModel: vi.fn().mockReturnValue('gemini-pro'),
@@ -861,33 +744,3 @@ describe('createContentGeneratorConfig', () => {
     expect(config.vertexai).toBe(false);
   });
 });
-
-describe('validateBaseUrl', () => {
-  it('should accept a valid HTTPS URL', () => {
-    expect(() => validateBaseUrl('https://my-proxy.example.com')).not.toThrow();
-  });
-
-  it('should accept HTTP for localhost', () => {
-    expect(() => validateBaseUrl('http://localhost:8080')).not.toThrow();
-  });
-
-  it('should accept HTTP for 127.0.0.1', () => {
-    expect(() => validateBaseUrl('http://127.0.0.1:3000')).not.toThrow();
-  });
-
-  it('should accept HTTP for ::1', () => {
-    expect(() => validateBaseUrl('http://[::1]:8080')).not.toThrow();
-  });
-
-  it('should reject HTTP for non-local hosts', () => {
-    expect(() => validateBaseUrl('http://my-proxy.example.com')).toThrow(
-      'Custom base URL must use HTTPS unless it is localhost.',
-    );
-  });
-
-  it('should reject an invalid URL', () => {
-    expect(() => validateBaseUrl('not-a-url')).toThrow(
-      'Invalid custom base URL: not-a-url',
-    );
-  });
-});

packages/core/src/core/contentGenerator.ts

@@ -273,25 +273,13 @@ export async function createContentGenerator(
           'x-gemini-api-privileged-user-id': `${installationId}`,
         };
       }
-      let baseUrl = config.baseUrl;
-      if (!baseUrl) {
-        const envBaseUrl = config.vertexai
-          ? process.env['GOOGLE_VERTEX_BASE_URL']
-          : process.env['GOOGLE_GEMINI_BASE_URL'];
-        if (envBaseUrl) {
-          validateBaseUrl(envBaseUrl);
-          baseUrl = envBaseUrl;
-        }
-      } else {
-        validateBaseUrl(baseUrl);
-      }
       const httpOptions: {
         baseUrl?: string;
         headers: Record<string, string>;
       } = { headers };
 
-      if (baseUrl) {
-        httpOptions.baseUrl = baseUrl;
+      if (config.baseUrl) {
+        httpOptions.baseUrl = config.baseUrl;
       }
 
       const googleGenAI = new GoogleGenAI({
@@ -313,17 +301,3 @@ export async function createContentGenerator(
 
   return generator;
 }
-
-const LOCAL_HOSTNAMES = ['localhost', '127.0.0.1', '[::1]'];
-
-export function validateBaseUrl(baseUrl: string): void {
-  let url: URL;
-  try {
-    url = new URL(baseUrl);
-  } catch {
-    throw new Error(`Invalid custom base URL: ${baseUrl}`);
-  }
-  if (url.protocol !== 'https:' && !LOCAL_HOSTNAMES.includes(url.hostname)) {
-    throw new Error('Custom base URL must use HTTPS unless it is localhost.');
-  }
-}

packages/core/src/index.ts

@@ -46,6 +46,7 @@ export * from './core/geminiRequest.js';
 export * from './scheduler/scheduler.js';
 export * from './scheduler/types.js';
 export * from './scheduler/tool-executor.js';
+export * from './scheduler/policy.js';
 export * from './core/recordingContentGenerator.js';
 
 export * from './fallback/types.js';
@@ -83,6 +84,7 @@ export * from './utils/authConsent.js';
 export * from './utils/googleQuotaErrors.js';
 export * from './utils/googleErrors.js';
 export * from './utils/fileUtils.js';
+export * from './utils/sessionOperations.js';
 export * from './utils/planUtils.js';
 export * from './utils/approvalModeUtils.js';
 export * from './utils/fileDiffUtils.js';
@@ -184,6 +186,8 @@ export * from './agents/agentLoader.js';
 export * from './agents/local-executor.js';
 export * from './agents/agent-scheduler.js';
 
+// Export browser session management
+export { resetBrowserSession } from './agents/browser/browserAgentFactory.js';
 // Export agent session interface
 export * from './agent/agent-session.js';
 export * from './agent/legacy-agent-session.js';

packages/core/src/policy/config.ts

@@ -285,6 +285,7 @@ export async function createPolicyEngineConfig(
   settings: PolicySettings,
   approvalMode: ApprovalMode,
   defaultPoliciesDir?: string,
+  interactive: boolean = true,
 ): Promise<PolicyEngineConfig> {
   const systemPoliciesDir = path.resolve(Storage.getSystemPoliciesDir());
   const userPoliciesDir = path.resolve(Storage.getUserPoliciesDir());
@@ -524,7 +525,10 @@ export async function createPolicyEngineConfig(
   return {
     rules,
     checkers,
-    defaultDecision: PolicyDecision.ASK_USER,
+    defaultDecision: interactive
+      ? PolicyDecision.ASK_USER
+      : PolicyDecision.DENY,
+    nonInteractive: !interactive,
     approvalMode,
     disableAlwaysAllow: settings.disableAlwaysAllow,
   };

packages/core/src/policy/policies/discovered.toml

@@ -6,3 +6,10 @@
 toolName = "discovered_tool_*"
 decision = "ask_user"
 priority = 10
+interactive = true
+
+[[rule]]
+toolName = "discovered_tool_*"
+decision = "deny"
+priority = 10
+interactive = false

packages/core/src/policy/policies/non-interactive.toml

@@ -0,0 +1,7 @@
+# Policy for non-interactive mode.
+# ASK_USER is strictly forbidden here.
+[[rule]]
+toolName = "ask_user"
+decision = "deny"
+priority = 999
+interactive = false

packages/core/src/policy/policies/plan.toml

@@ -86,6 +86,16 @@ toolAnnotations = { readOnlyHint = true }
 decision = "ask_user"
 priority = 70
 modes = ["plan"]
+interactive = true
+
+[[rule]]
+toolName = "*"
+mcpName = "*"
+toolAnnotations = { readOnlyHint = true }
+decision = "deny"
+priority = 70
+modes = ["plan"]
+interactive = false
 
 [[rule]]
 toolName = [
@@ -108,6 +118,14 @@ toolName = ["ask_user", "save_memory"]
 decision = "ask_user"
 priority = 70
 modes = ["plan"]
+interactive = true
+
+[[rule]]
+toolName = ["ask_user", "save_memory"]
+decision = "deny"
+priority = 70
+modes = ["plan"]
+interactive = false
 
 # Allow write_file and replace for .md files in the plans directory (cross-platform)
 # We split this into two rules to avoid ReDoS checker issues with nested optional segments.

packages/core/src/policy/policies/write.toml

@@ -31,6 +31,7 @@
 toolName = "replace"
 decision = "ask_user"
 priority = 10
+interactive = true
 
 [[rule]]
 toolName = "replace"
@@ -47,21 +48,25 @@ required_context = ["environment"]
 toolName = "save_memory"
 decision = "ask_user"
 priority = 10
+interactive = true
 
 [[rule]]
 toolName = "run_shell_command"
 decision = "ask_user"
 priority = 10
+interactive = true
 
 [[rule]]
 toolName = "write_file"
 decision = "ask_user"
 priority = 10
+interactive = true
 
 [[rule]]
 toolName = "activate_skill"
 decision = "ask_user"
 priority = 10
+interactive = true
 
 [[rule]]
 toolName = "write_file"
@@ -84,3 +89,19 @@ modes = ["autoEdit"]
 toolName = "web_fetch"
 decision = "ask_user"
 priority = 10
+interactive = true
+
+# Headless Denial Rule (Priority 10)
+# Ensures that tools that normally default to ASK_USER are denied in non-interactive mode.
+[[rule]]
+toolName = [
+  "replace",
+  "save_memory",
+  "run_shell_command",
+  "write_file",
+  "activate_skill",
+  "web_fetch"
+]
+decision = "deny"
+priority = 10
+interactive = false

packages/core/src/policy/policies/yolo.toml

@@ -30,12 +30,12 @@
 
 # Ask-user tool always requires user interaction, even in YOLO mode.
 # This ensures the model can gather user preferences/decisions when needed.
-# Note: In non-interactive mode, this decision is converted to DENY by the policy engine.
 [[rule]]
 toolName = "ask_user"
 decision = "ask_user"
 priority = 999
 modes = ["yolo"]
+interactive = true
 
 # Plan mode transitions are blocked in YOLO mode to maintain state consistency
 # and because planning currently requires human interaction (plan approval),

packages/core/src/policy/policy-engine.test.ts

@@ -293,8 +293,22 @@ describe('PolicyEngine', () => {
       const config: PolicyEngineConfig = {
         nonInteractive: true,
         rules: [
-          { toolName: 'interactive-tool', decision: PolicyDecision.ASK_USER },
+          {
+            toolName: 'interactive-tool',
+            decision: PolicyDecision.ASK_USER,
+            interactive: true,
+          },
+          {
+            toolName: 'interactive-tool',
+            decision: PolicyDecision.DENY,
+            interactive: false,
+          },
           { toolName: 'allowed-tool', decision: PolicyDecision.ALLOW },
+          {
+            toolName: 'ask_user',
+            decision: PolicyDecision.DENY,
+            interactive: false,
+          },
         ],
       };
 
@@ -361,6 +375,7 @@ describe('PolicyEngine', () => {
         isKnownSafeCommand: vi
           .fn()
           .mockImplementation((args) => args[0] === 'npm'),
+        parseDenials: vi.fn().mockReturnValue(undefined),
       } as unknown as SandboxManager;
 
       engine = new PolicyEngine({
@@ -1258,6 +1273,51 @@ describe('PolicyEngine', () => {
       ).toBe(PolicyDecision.ALLOW);
     });
 
+    it('should NOT automatically DENY redirected shell commands in non-interactive mode if rules permit it', async () => {
+      const toolName = 'run_shell_command';
+      const command = 'ls > out.txt';
+
+      const rules: PolicyRule[] = [
+        {
+          toolName,
+          decision: PolicyDecision.ALLOW,
+          allowRedirection: true,
+        },
+      ];
+
+      engine = new PolicyEngine({ rules, nonInteractive: true });
+
+      expect(
+        (await engine.check({ name: toolName, args: { command } }, undefined))
+          .decision,
+      ).toBe(PolicyDecision.ALLOW);
+    });
+
+    it('should respect DENY rules for redirected shell commands in non-interactive mode', async () => {
+      const toolName = 'run_shell_command';
+      const command = 'ls > out.txt';
+
+      const rules: PolicyRule[] = [
+        {
+          toolName,
+          decision: PolicyDecision.ASK_USER,
+          interactive: true,
+        },
+        {
+          toolName,
+          decision: PolicyDecision.DENY,
+          interactive: false,
+        },
+      ];
+
+      engine = new PolicyEngine({ rules, nonInteractive: true });
+
+      expect(
+        (await engine.check({ name: toolName, args: { command } }, undefined))
+          .decision,
+      ).toBe(PolicyDecision.DENY);
+    });
+
     it('should NOT downgrade ALLOW to ASK_USER for quoted redirection chars', async () => {
       const rules: PolicyRule[] = [
         {
@@ -1423,21 +1483,25 @@ describe('PolicyEngine', () => {
       expect(result.decision).toBe(PolicyDecision.DENY);
     });
 
-    it('should DENY redirected shell commands in non-interactive mode', async () => {
+    it('should respect explicit DENY rules for redirected shell commands in non-interactive mode', async () => {
       const config: PolicyEngineConfig = {
         nonInteractive: true,
         rules: [
           {
             toolName: 'run_shell_command',
             decision: PolicyDecision.ALLOW,
+            interactive: true,
+          },
+          {
+            toolName: 'run_shell_command',
+            decision: PolicyDecision.DENY,
+            interactive: false,
           },
         ],
       };
 
       engine = new PolicyEngine(config);
 
-      // Redirected command should be DENIED in non-interactive mode
-      // (Normally ASK_USER, but ASK_USER -> DENY in non-interactive)
       expect(
         (
           await engine.check(
@@ -2215,34 +2279,6 @@ describe('PolicyEngine', () => {
       const result = await engine.check({ name: 'tool' }, undefined);
       expect(result.decision).toBe(PolicyDecision.ASK_USER);
     });
-
-    it('should DENY if checker returns ASK_USER in non-interactive mode', async () => {
-      const rules: PolicyRule[] = [
-        { toolName: 'tool', decision: PolicyDecision.ALLOW },
-      ];
-      const checkers: SafetyCheckerRule[] = [
-        {
-          toolName: '*',
-          checker: {
-            type: 'in-process',
-            name: InProcessCheckerType.ALLOWED_PATH,
-          },
-        },
-      ];
-
-      engine = new PolicyEngine(
-        { rules, checkers, nonInteractive: true },
-        mockCheckerRunner,
-      );
-
-      vi.mocked(mockCheckerRunner.runChecker).mockResolvedValue({
-        decision: SafetyCheckDecision.ASK_USER,
-        reason: 'Suspicious path',
-      });
-
-      const result = await engine.check({ name: 'tool' }, undefined);
-      expect(result.decision).toBe(PolicyDecision.DENY);
-    });
   });
 
   describe('getExcludedTools', () => {
@@ -2345,18 +2381,42 @@ describe('PolicyEngine', () => {
         expected: [],
       },
       {
-        name: 'should NOT include ASK_USER tools even in non-interactive mode',
+        name: 'should include tools in exclusion list only if explicitly denied in non-interactive mode',
         rules: [
           {
             toolName: 'tool1',
             decision: PolicyDecision.ASK_USER,
             modes: [ApprovalMode.DEFAULT],
+            interactive: true,
+          },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            modes: [ApprovalMode.DEFAULT],
+            interactive: false,
           },
         ],
         nonInteractive: true,
         allToolNames: ['tool1'],
         expected: ['tool1'],
       },
+      {
+        name: 'should specifically exclude ask_user tool in non-interactive mode',
+        rules: [
+          {
+            toolName: 'ask_user',
+            decision: PolicyDecision.DENY,
+            interactive: false,
+          },
+          {
+            toolName: 'read_file',
+            decision: PolicyDecision.ALLOW,
+          },
+        ],
+        nonInteractive: true,
+        allToolNames: ['ask_user', 'read_file'],
+        expected: ['ask_user'],
+      },
       {
         name: 'should ignore rules with argsPattern',
         rules: [

packages/core/src/policy/policy-engine.ts

@@ -244,8 +244,10 @@ export class PolicyEngine {
       }
     }
 
-    this.defaultDecision = config.defaultDecision ?? PolicyDecision.ASK_USER;
     this.nonInteractive = config.nonInteractive ?? false;
+    this.defaultDecision =
+      config.defaultDecision ??
+      (this.nonInteractive ? PolicyDecision.DENY : PolicyDecision.ASK_USER);
     this.disableAlwaysAllow = config.disableAlwaysAllow ?? false;
     this.checkerRunner = checkerRunner;
     this.approvalMode = config.approvalMode ?? ApprovalMode.DEFAULT;
@@ -340,7 +342,7 @@ export class PolicyEngine {
   ): Promise<CheckResult> {
     if (!command) {
       return {
-        decision: this.applyNonInteractiveMode(ruleDecision),
+        decision: ruleDecision,
         rule,
       };
     }
@@ -363,13 +365,13 @@ export class PolicyEngine {
       }
 
       debugLogger.debug(
-        `[PolicyEngine.check] Command parsing failed for: ${command}. Falling back to ASK_USER.`,
+        `[PolicyEngine.check] Command parsing failed for: ${command}. Falling back to ${this.defaultDecision}.`,
       );
 
-      // Parsing logic failed, we can't trust it. Force ASK_USER (or DENY).
+      // Parsing logic failed, we can't trust it. Use default decision ASK_USER (or DENY in non-interactive).
       // We return the rule that matched so the evaluation loop terminates.
       return {
-        decision: this.applyNonInteractiveMode(PolicyDecision.ASK_USER),
+        decision: this.defaultDecision,
         rule,
       };
     }
@@ -466,7 +468,7 @@ export class PolicyEngine {
       }
 
       return {
-        decision: this.applyNonInteractiveMode(aggregateDecision),
+        decision: aggregateDecision,
         // If we stayed at ALLOW, we return the original rule (if any).
         // If we downgraded, we return the responsible rule (or undefined if implicit).
         rule: aggregateDecision === ruleDecision ? rule : responsibleRule,
@@ -474,7 +476,7 @@ export class PolicyEngine {
     }
 
     return {
-      decision: this.applyNonInteractiveMode(ruleDecision),
+      decision: ruleDecision,
       rule,
     };
   }
@@ -597,7 +599,7 @@ export class PolicyEngine {
             break;
           }
         } else {
-          decision = this.applyNonInteractiveMode(rule.decision);
+          decision = rule.decision;
           matchedRule = rule;
           break;
         }
@@ -641,7 +643,7 @@ export class PolicyEngine {
         decision = shellResult.decision;
         matchedRule = shellResult.rule;
       } else {
-        decision = this.applyNonInteractiveMode(this.defaultDecision);
+        decision = this.defaultDecision;
       }
     }
 
@@ -697,7 +699,7 @@ export class PolicyEngine {
     }
 
     return {
-      decision: this.applyNonInteractiveMode(decision),
+      decision,
       rule: matchedRule,
     };
   }
@@ -866,7 +868,7 @@ export class PolicyEngine {
             continue;
           } else {
             // Unconditional rule for this tool
-            const decision = this.applyNonInteractiveMode(rule.decision);
+            const decision = rule.decision;
             staticallyExcluded = decision === PolicyDecision.DENY;
             matchFound = true;
             break;
@@ -876,7 +878,7 @@ export class PolicyEngine {
 
       if (!matchFound) {
         // Fallback to default decision if no rule matches
-        const defaultDec = this.applyNonInteractiveMode(this.defaultDecision);
+        const defaultDec = this.defaultDecision;
         if (defaultDec === PolicyDecision.DENY) {
           staticallyExcluded = true;
         }
@@ -889,12 +891,4 @@ export class PolicyEngine {
 
     return excludedTools;
   }
-
-  private applyNonInteractiveMode(decision: PolicyDecision): PolicyDecision {
-    // In non-interactive mode, ASK_USER becomes DENY
-    if (this.nonInteractive && decision === PolicyDecision.ASK_USER) {
-      return PolicyDecision.DENY;
-    }
-    return decision;
-  }
 }

packages/core/src/sandbox/linux/LinuxSandboxManager.test.ts

@@ -6,9 +6,9 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { LinuxSandboxManager } from './LinuxSandboxManager.js';
-import * as sandboxManager from '../../services/sandboxManager.js';
 import type { SandboxRequest } from '../../services/sandboxManager.js';
 import fs from 'node:fs';
+import * as shellUtils from '../../utils/shell-utils.js';
 
 vi.mock('node:fs', async () => {
   const actual = await vi.importActual<typeof import('node:fs')>('node:fs');
@@ -18,18 +18,43 @@ vi.mock('node:fs', async () => {
       // @ts-expect-error - Property 'default' does not exist on type 'typeof import("node:fs")'
       ...actual.default,
       existsSync: vi.fn(() => true),
-      realpathSync: vi.fn((p: string | Buffer) => p.toString()),
+      realpathSync: vi.fn((p) => p.toString()),
+      statSync: vi.fn(() => ({ isDirectory: () => true }) as fs.Stats),
       mkdirSync: vi.fn(),
+      mkdtempSync: vi.fn((prefix: string) => prefix + 'mocked'),
       openSync: vi.fn(),
       closeSync: vi.fn(),
       writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+      chmodSync: vi.fn(),
+      unlinkSync: vi.fn(),
+      rmSync: vi.fn(),
     },
     existsSync: vi.fn(() => true),
-    realpathSync: vi.fn((p: string | Buffer) => p.toString()),
+    realpathSync: vi.fn((p) => p.toString()),
+    statSync: vi.fn(() => ({ isDirectory: () => true }) as fs.Stats),
     mkdirSync: vi.fn(),
+    mkdtempSync: vi.fn((prefix: string) => prefix + 'mocked'),
     openSync: vi.fn(),
     closeSync: vi.fn(),
     writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    chmodSync: vi.fn(),
+    unlinkSync: vi.fn(),
+    rmSync: vi.fn(),
+  };
+});
+
+vi.mock('../../utils/shell-utils.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../../utils/shell-utils.js')>();
+  return {
+    ...actual,
+    spawnAsync: vi.fn(() =>
+      Promise.resolve({ status: 0, stdout: Buffer.from('') }),
+    ),
+    initializeShellParsers: vi.fn(),
+    isStrictlyApproved: vi.fn().mockResolvedValue(true),
   };
 });
 
@@ -48,8 +73,12 @@ describe('LinuxSandboxManager', () => {
     vi.restoreAllMocks();
   });
 
-  const getBwrapArgs = async (req: SandboxRequest) => {
-    const result = await manager.prepareCommand(req);
+  const getBwrapArgs = async (
+    req: SandboxRequest,
+    customManager?: LinuxSandboxManager,
+  ) => {
+    const mgr = customManager || manager;
+    const result = await mgr.prepareCommand(req);
     expect(result.program).toBe('sh');
     expect(result.args[0]).toBe('-c');
     expect(result.args[1]).toBe(
@@ -60,41 +89,6 @@ describe('LinuxSandboxManager', () => {
     return result.args.slice(4);
   };
 
-  /**
-   * Helper to verify only the dynamic, policy-based binds (e.g. allowedPaths, forbiddenPaths).
-   * It asserts that the base workspace and governance files are present exactly once,
-   * then strips them away, leaving only the dynamic binds for a focused, non-brittle assertion.
-   */
-  const expectDynamicBinds = (
-    bwrapArgs: string[],
-    expectedDynamicBinds: string[],
-  ) => {
-    const bindsIndex = bwrapArgs.indexOf('--seccomp');
-    const allBinds = bwrapArgs.slice(bwrapArgs.indexOf('--bind'), bindsIndex);
-
-    const baseBinds = [
-      '--bind',
-      workspace,
-      workspace,
-      '--ro-bind',
-      `${workspace}/.gitignore`,
-      `${workspace}/.gitignore`,
-      '--ro-bind',
-      `${workspace}/.geminiignore`,
-      `${workspace}/.geminiignore`,
-      '--ro-bind',
-      `${workspace}/.git`,
-      `${workspace}/.git`,
-    ];
-
-    // Verify the base binds are present exactly at the beginning
-    expect(allBinds.slice(0, baseBinds.length)).toEqual(baseBinds);
-
-    // Extract the remaining dynamic binds
-    const dynamicBinds = allBinds.slice(baseBinds.length);
-    expect(dynamicBinds).toEqual(expectedDynamicBinds);
-  };
-
   describe('prepareCommand', () => {
     it('should correctly format the base command and args', async () => {
       const bwrapArgs = await getBwrapArgs({
@@ -117,7 +111,7 @@ describe('LinuxSandboxManager', () => {
         '/proc',
         '--tmpfs',
         '/tmp',
-        '--bind',
+        '--ro-bind-try',
         workspace,
         workspace,
         '--ro-bind',
@@ -137,6 +131,73 @@ describe('LinuxSandboxManager', () => {
       ]);
     });
 
+    it('binds workspace read-write when readonly is false', async () => {
+      const customManager = new LinuxSandboxManager({
+        workspace,
+        modeConfig: { readonly: false },
+      });
+      const bwrapArgs = await getBwrapArgs(
+        {
+          command: 'ls',
+          args: [],
+          cwd: workspace,
+          env: {},
+        },
+        customManager,
+      );
+
+      expect(bwrapArgs).toContain('--bind-try');
+      expect(bwrapArgs).toContain(workspace);
+    });
+
+    it('maps network permissions to --share-net', async () => {
+      const bwrapArgs = await getBwrapArgs({
+        command: 'curl',
+        args: [],
+        cwd: workspace,
+        env: {},
+        policy: { additionalPermissions: { network: true } },
+      });
+
+      expect(bwrapArgs).toContain('--share-net');
+    });
+
+    it('maps explicit write permissions to --bind-try', async () => {
+      const bwrapArgs = await getBwrapArgs({
+        command: 'touch',
+        args: [],
+        cwd: workspace,
+        env: {},
+        policy: {
+          additionalPermissions: {
+            fileSystem: { write: ['/home/user/workspace/out/dir'] },
+          },
+        },
+      });
+
+      const index = bwrapArgs.indexOf('--bind-try');
+      expect(index).not.toBe(-1);
+      expect(bwrapArgs[index + 1]).toBe('/home/user/workspace/out/dir');
+    });
+
+    it('rejects overrides in plan mode', async () => {
+      const customManager = new LinuxSandboxManager({
+        workspace,
+        modeConfig: { allowOverrides: false },
+      });
+      await expect(
+        customManager.prepareCommand({
+          command: 'ls',
+          args: [],
+          cwd: workspace,
+          env: {},
+          policy: { additionalPermissions: { network: true } },
+        }),
+      ).rejects.toThrow(
+        /Cannot override readonly\/network\/filesystem restrictions in Plan mode/,
+      );
+    });
+
     it('should correctly pass through the cwd to the resulting command', async () => {
       const req: SandboxRequest = {
         command: 'ls',
@@ -184,12 +245,7 @@ describe('LinuxSandboxManager', () => {
         },
       });
 
-      expect(bwrapArgs).toContain('--unshare-user');
-      expect(bwrapArgs).toContain('--unshare-ipc');
-      expect(bwrapArgs).toContain('--unshare-pid');
-      expect(bwrapArgs).toContain('--unshare-uts');
-      expect(bwrapArgs).toContain('--unshare-cgroup');
-      expect(bwrapArgs).not.toContain('--unshare-all');
+      expect(bwrapArgs).toContain('--share-net');
     });
 
     describe('governance files', () => {
@@ -252,15 +308,32 @@ describe('LinuxSandboxManager', () => {
           },
         });
 
-        // Verify the specific bindings were added correctly
-        expectDynamicBinds(bwrapArgs, [
+        expect(bwrapArgs).toContain('--bind-try');
+        expect(bwrapArgs[bwrapArgs.indexOf('/tmp/cache') - 1]).toBe(
           '--bind-try',
-          '/tmp/cache',
-          '/tmp/cache',
+        );
+        expect(bwrapArgs[bwrapArgs.indexOf('/opt/tools') - 1]).toBe(
           '--bind-try',
-          '/opt/tools',
-          '/opt/tools',
-        ]);
+        );
+      });
+
+      it('should not grant read-write access to allowedPaths inside the workspace when readonly mode is active', async () => {
+        const manager = new LinuxSandboxManager({
+          workspace,
+          modeConfig: { readonly: true },
+        });
+        const result = await manager.prepareCommand({
+          command: 'ls',
+          args: [],
+          cwd: workspace,
+          env: {},
+          policy: {
+            allowedPaths: [workspace + '/subdirectory'],
+          },
+        });
+        const bwrapArgs = result.args;
+        const bindIndex = bwrapArgs.indexOf(workspace + '/subdirectory');
+        expect(bwrapArgs[bindIndex - 1]).toBe('--ro-bind-try');
       });
 
       it('should not bind the workspace twice even if it has a trailing slash in allowedPaths', async () => {
@@ -274,164 +347,200 @@ describe('LinuxSandboxManager', () => {
           },
         });
 
-        // Should only contain the primary workspace bind and governance files, not the second workspace bind with a trailing slash
-        expectDynamicBinds(bwrapArgs, []);
+        const binds = bwrapArgs.filter((a) => a === workspace);
+        expect(binds.length).toBe(2);
       });
     });
 
     describe('forbiddenPaths', () => {
       it('should parameterize forbidden paths and explicitly deny them', async () => {
-        vi.spyOn(fs.promises, 'stat').mockImplementation(async (p) => {
-          // Mock /tmp/cache as a directory, and /opt/secret.txt as a file
+        vi.mocked(fs.statSync).mockImplementation((p) => {
           if (p.toString().includes('cache')) {
             return { isDirectory: () => true } as fs.Stats;
           }
           return { isDirectory: () => false } as fs.Stats;
         });
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(async (p) =>
-          p.toString(),
-        );
+        vi.mocked(fs.realpathSync).mockImplementation((p) => p.toString());
 
-        const bwrapArgs = await getBwrapArgs({
-          command: 'ls',
-          args: ['-la'],
-          cwd: workspace,
-          env: {},
-          policy: {
-            forbiddenPaths: ['/tmp/cache', '/opt/secret.txt'],
-          },
+        const customManager = new LinuxSandboxManager({
+          workspace,
+          forbiddenPaths: ['/tmp/cache', '/opt/secret.txt'],
         });
 
-        expectDynamicBinds(bwrapArgs, [
-          '--tmpfs',
-          '/tmp/cache',
-          '--remount-ro',
-          '/tmp/cache',
-          '--ro-bind-try',
-          '/dev/null',
-          '/opt/secret.txt',
-        ]);
+        const bwrapArgs = await getBwrapArgs(
+          {
+            command: 'ls',
+            args: ['-la'],
+            cwd: workspace,
+            env: {},
+          },
+          customManager,
+        );
+
+        const cacheIndex = bwrapArgs.indexOf('/tmp/cache');
+        expect(bwrapArgs[cacheIndex - 1]).toBe('--tmpfs');
+
+        const secretIndex = bwrapArgs.indexOf('/opt/secret.txt');
+        expect(bwrapArgs[secretIndex - 2]).toBe('--ro-bind');
+        expect(bwrapArgs[secretIndex - 1]).toBe('/dev/null');
       });
 
       it('resolves forbidden symlink paths to their real paths', async () => {
-        vi.spyOn(fs.promises, 'stat').mockImplementation(
-          async () => ({ isDirectory: () => false }) as fs.Stats,
+        vi.mocked(fs.statSync).mockImplementation(
+          () => ({ isDirectory: () => false }) as fs.Stats,
         );
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => {
-            if (p === '/tmp/forbidden-symlink') return '/opt/real-target.txt';
-            return p.toString();
-          },
-        );
-
-        const bwrapArgs = await getBwrapArgs({
-          command: 'ls',
-          args: ['-la'],
-          cwd: workspace,
-          env: {},
-          policy: {
-            forbiddenPaths: ['/tmp/forbidden-symlink'],
-          },
+        vi.mocked(fs.realpathSync).mockImplementation((p) => {
+          if (p === '/tmp/forbidden-symlink') return '/opt/real-target.txt';
+          return p.toString();
         });
 
-        // Should explicitly mask both the resolved path and the original symlink path
-        expectDynamicBinds(bwrapArgs, [
-          '--ro-bind-try',
-          '/dev/null',
-          '/opt/real-target.txt',
-          '--ro-bind-try',
-          '/dev/null',
-          '/tmp/forbidden-symlink',
-        ]);
+        const customManager = new LinuxSandboxManager({
+          workspace,
+          forbiddenPaths: ['/tmp/forbidden-symlink'],
+        });
+
+        const bwrapArgs = await getBwrapArgs(
+          {
+            command: 'ls',
+            args: ['-la'],
+            cwd: workspace,
+            env: {},
+          },
+          customManager,
+        );
+
+        const secretIndex = bwrapArgs.indexOf('/opt/real-target.txt');
+        expect(bwrapArgs[secretIndex - 2]).toBe('--ro-bind');
+        expect(bwrapArgs[secretIndex - 1]).toBe('/dev/null');
       });
 
       it('explicitly denies non-existent forbidden paths to prevent creation', async () => {
         const error = new Error('File not found') as NodeJS.ErrnoException;
         error.code = 'ENOENT';
-        vi.spyOn(fs.promises, 'stat').mockRejectedValue(error);
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(async (p) =>
-          p.toString(),
-        );
+        vi.mocked(fs.statSync).mockImplementation(() => {
+          throw error;
+        });
+        vi.mocked(fs.realpathSync).mockImplementation((p) => p.toString());
 
-        const bwrapArgs = await getBwrapArgs({
-          command: 'ls',
-          args: [],
-          cwd: workspace,
-          env: {},
-          policy: {
-            forbiddenPaths: ['/tmp/not-here.txt'],
-          },
+        const customManager = new LinuxSandboxManager({
+          workspace,
+          forbiddenPaths: ['/tmp/not-here.txt'],
         });
 
-        expectDynamicBinds(bwrapArgs, [
-          '--symlink',
-          '/.forbidden',
-          '/tmp/not-here.txt',
-        ]);
+        const bwrapArgs = await getBwrapArgs(
+          {
+            command: 'ls',
+            args: [],
+            cwd: workspace,
+            env: {},
+          },
+          customManager,
+        );
+
+        const idx = bwrapArgs.indexOf('/tmp/not-here.txt');
+        expect(bwrapArgs[idx - 2]).toBe('--symlink');
+        expect(bwrapArgs[idx - 1]).toBe('/dev/null');
       });
 
       it('masks directory symlinks with tmpfs for both paths', async () => {
-        vi.spyOn(fs.promises, 'stat').mockImplementation(
-          async () => ({ isDirectory: () => true }) as fs.Stats,
+        vi.mocked(fs.statSync).mockImplementation(
+          () => ({ isDirectory: () => true }) as fs.Stats,
         );
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => {
-            if (p === '/tmp/dir-link') return '/opt/real-dir';
-            return p.toString();
-          },
-        );
-
-        const bwrapArgs = await getBwrapArgs({
-          command: 'ls',
-          args: [],
-          cwd: workspace,
-          env: {},
-          policy: {
-            forbiddenPaths: ['/tmp/dir-link'],
-          },
+        vi.mocked(fs.realpathSync).mockImplementation((p) => {
+          if (p === '/tmp/dir-link') return '/opt/real-dir';
+          return p.toString();
         });
 
-        expectDynamicBinds(bwrapArgs, [
-          '--tmpfs',
-          '/opt/real-dir',
-          '--remount-ro',
-          '/opt/real-dir',
-          '--tmpfs',
-          '/tmp/dir-link',
-          '--remount-ro',
-          '/tmp/dir-link',
-        ]);
+        const customManager = new LinuxSandboxManager({
+          workspace,
+          forbiddenPaths: ['/tmp/dir-link'],
+        });
+
+        const bwrapArgs = await getBwrapArgs(
+          {
+            command: 'ls',
+            args: [],
+            cwd: workspace,
+            env: {},
+          },
+          customManager,
+        );
+
+        const idx = bwrapArgs.indexOf('/opt/real-dir');
+        expect(bwrapArgs[idx - 1]).toBe('--tmpfs');
       });
 
       it('should override allowed paths if a path is also in forbidden paths', async () => {
-        vi.spyOn(fs.promises, 'stat').mockImplementation(
-          async () => ({ isDirectory: () => true }) as fs.Stats,
-        );
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(async (p) =>
-          p.toString(),
+        vi.mocked(fs.statSync).mockImplementation(
+          () => ({ isDirectory: () => true }) as fs.Stats,
         );
+        vi.mocked(fs.realpathSync).mockImplementation((p) => p.toString());
 
-        const bwrapArgs = await getBwrapArgs({
-          command: 'ls',
-          args: ['-la'],
-          cwd: workspace,
-          env: {},
-          policy: {
-            allowedPaths: ['/tmp/conflict'],
-            forbiddenPaths: ['/tmp/conflict'],
-          },
+        const customManager = new LinuxSandboxManager({
+          workspace,
+          forbiddenPaths: ['/tmp/conflict'],
         });
 
-        expectDynamicBinds(bwrapArgs, [
-          '--bind-try',
-          '/tmp/conflict',
-          '/tmp/conflict',
-          '--tmpfs',
-          '/tmp/conflict',
-          '--remount-ro',
-          '/tmp/conflict',
-        ]);
+        const bwrapArgs = await getBwrapArgs(
+          {
+            command: 'ls',
+            args: ['-la'],
+            cwd: workspace,
+            env: {},
+            policy: {
+              allowedPaths: ['/tmp/conflict'],
+            },
+          },
+          customManager,
+        );
+
+        const bindTryIdx = bwrapArgs.indexOf('--bind-try');
+        const tmpfsIdx = bwrapArgs.lastIndexOf('--tmpfs');
+
+        expect(bwrapArgs[bindTryIdx + 1]).toBe('/tmp/conflict');
+        expect(bwrapArgs[tmpfsIdx + 1]).toBe('/tmp/conflict');
+        expect(tmpfsIdx).toBeGreaterThan(bindTryIdx);
       });
     });
   });
+
+  it('blocks .env and .env.* files in the workspace root', async () => {
+    vi.mocked(shellUtils.spawnAsync).mockImplementation((cmd, args) => {
+      if (cmd === 'find' && args?.[0] === workspace) {
+        // Assert that find is NOT excluding dotfiles
+        expect(args).not.toContain('-not');
+        expect(args).toContain('-prune');
+
+        return Promise.resolve({
+          status: 0,
+          stdout: Buffer.from(
+            `${workspace}/.env\0${workspace}/.env.local\0${workspace}/.env.test\0`,
+          ),
+        } as unknown as ReturnType<typeof shellUtils.spawnAsync>);
+      }
+      return Promise.resolve({
+        status: 0,
+        stdout: Buffer.from(''),
+      } as unknown as ReturnType<typeof shellUtils.spawnAsync>);
+    });
+
+    const bwrapArgs = await getBwrapArgs({
+      command: 'ls',
+      args: [],
+      cwd: workspace,
+      env: {},
+    });
+
+    const bindsIndex = bwrapArgs.indexOf('--seccomp');
+    const binds = bwrapArgs.slice(0, bindsIndex);
+
+    expect(binds).toContain(`${workspace}/.env`);
+    expect(binds).toContain(`${workspace}/.env.local`);
+    expect(binds).toContain(`${workspace}/.env.test`);
+
+    // Verify they are bound to a mask file
+    const envIndex = binds.indexOf(`${workspace}/.env`);
+    expect(binds[envIndex - 2]).toBe('--bind');
+    expect(binds[envIndex - 1]).toMatch(/gemini-cli-mask-file-.*mocked\/mask/);
+  });
 });

packages/core/src/sandbox/linux/LinuxSandboxManager.ts

@@ -12,15 +12,34 @@ import {
   type GlobalSandboxOptions,
   type SandboxRequest,
   type SandboxedCommand,
+  type SandboxPermissions,
   GOVERNANCE_FILES,
+  getSecretFileFindArgs,
   sanitizePaths,
-  tryRealpath,
+  type ParsedSandboxDenial,
 } from '../../services/sandboxManager.js';
+import type { ShellExecutionResult } from '../../services/shellExecutionService.js';
 import {
   sanitizeEnvironment,
   getSecureSanitizationConfig,
 } from '../../services/environmentSanitization.js';
-import { isNodeError } from '../../utils/errors.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { spawnAsync } from '../../utils/shell-utils.js';
+import {
+  isStrictlyApproved,
+  verifySandboxOverrides,
+  getCommandName,
+} from '../utils/commandUtils.js';
+import {
+  tryRealpath,
+  resolveGitWorktreePaths,
+  isErrnoException,
+} from '../utils/fsUtils.js';
+import {
+  isKnownSafeCommand,
+  isDangerousCommand,
+} from '../utils/commandSafety.js';
+import { parsePosixSandboxDenials } from '../utils/sandboxDenialUtils.js';
 
 let cachedBpfPath: string | undefined;
 
@@ -74,9 +93,20 @@ function getSeccompBpfPath(): string {
     buf.writeUInt32LE(inst.k, offset + 4);
   }
 
-  const bpfPath = join(os.tmpdir(), `gemini-cli-seccomp-${process.pid}.bpf`);
+  const tempDir = fs.mkdtempSync(join(os.tmpdir(), 'gemini-cli-seccomp-'));
+  const bpfPath = join(tempDir, 'seccomp.bpf');
   fs.writeFileSync(bpfPath, buf);
   cachedBpfPath = bpfPath;
+
+  // Cleanup on exit
+  process.on('exit', () => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore errors
+    }
+  });
+
   return bpfPath;
 }
 
@@ -99,15 +129,13 @@ function touch(filePath: string, isDirectory: boolean) {
   }
 }
 
-import {
-  isKnownSafeCommand,
-  isDangerousCommand,
-} from '../macos/commandSafety.js';
-
 /**
  * A SandboxManager implementation for Linux that uses Bubblewrap (bwrap).
  */
+
 export class LinuxSandboxManager implements SandboxManager {
+  private static maskFilePath: string | undefined;
+
   constructor(private readonly options: GlobalSandboxOptions) {}
 
   isKnownSafeCommand(args: string[]): boolean {
@@ -118,7 +146,71 @@ export class LinuxSandboxManager implements SandboxManager {
     return isDangerousCommand(args);
   }
 
+  parseDenials(result: ShellExecutionResult): ParsedSandboxDenial | undefined {
+    return parsePosixSandboxDenials(result);
+  }
+
+  private getMaskFilePath(): string {
+    if (
+      LinuxSandboxManager.maskFilePath &&
+      fs.existsSync(LinuxSandboxManager.maskFilePath)
+    ) {
+      return LinuxSandboxManager.maskFilePath;
+    }
+    const tempDir = fs.mkdtempSync(join(os.tmpdir(), 'gemini-cli-mask-file-'));
+    const maskPath = join(tempDir, 'mask');
+    fs.writeFileSync(maskPath, '');
+    fs.chmodSync(maskPath, 0);
+    LinuxSandboxManager.maskFilePath = maskPath;
+
+    // Cleanup on exit
+    process.on('exit', () => {
+      try {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      } catch {
+        // Ignore errors
+      }
+    });
+
+    return maskPath;
+  }
+
   async prepareCommand(req: SandboxRequest): Promise<SandboxedCommand> {
+    const isReadonlyMode = this.options.modeConfig?.readonly ?? true;
+    const allowOverrides = this.options.modeConfig?.allowOverrides ?? true;
+
+    verifySandboxOverrides(allowOverrides, req.policy);
+
+    const commandName = await getCommandName(req);
+    const isApproved = allowOverrides
+      ? await isStrictlyApproved(req, this.options.modeConfig?.approvedTools)
+      : false;
+    const workspaceWrite = !isReadonlyMode || isApproved;
+    const networkAccess =
+      this.options.modeConfig?.network ?? req.policy?.networkAccess ?? false;
+
+    const persistentPermissions = allowOverrides
+      ? this.options.policyManager?.getCommandPermissions(commandName)
+      : undefined;
+
+    const mergedAdditional: SandboxPermissions = {
+      fileSystem: {
+        read: [
+          ...(persistentPermissions?.fileSystem?.read ?? []),
+          ...(req.policy?.additionalPermissions?.fileSystem?.read ?? []),
+        ],
+        write: [
+          ...(persistentPermissions?.fileSystem?.write ?? []),
+          ...(req.policy?.additionalPermissions?.fileSystem?.write ?? []),
+        ],
+      },
+      network:
+        networkAccess ||
+        persistentPermissions?.network ||
+        req.policy?.additionalPermissions?.network ||
+        false,
+    };
+
     const sanitizationConfig = getSecureSanitizationConfig(
       req.policy?.sanitizationConfig,
     );
@@ -126,13 +218,147 @@ export class LinuxSandboxManager implements SandboxManager {
     const sanitizedEnv = sanitizeEnvironment(req.env, sanitizationConfig);
 
     const bwrapArgs: string[] = [
-      ...this.getNetworkArgs(req),
-      ...this.getBaseArgs(),
-      ...this.getGovernanceArgs(),
-      ...this.getAllowedPathsArgs(req.policy?.allowedPaths),
-      ...(await this.getForbiddenPathsArgs(req.policy?.forbiddenPaths)),
+      '--unshare-all',
+      '--new-session', // Isolate session
+      '--die-with-parent', // Prevent orphaned runaway processes
     ];
 
+    if (mergedAdditional.network) {
+      bwrapArgs.push('--share-net');
+    }
+
+    bwrapArgs.push(
+      '--ro-bind',
+      '/',
+      '/',
+      '--dev', // Creates a safe, minimal /dev (replaces --dev-bind)
+      '/dev',
+      '--proc', // Creates a fresh procfs for the unshared PID namespace
+      '/proc',
+      '--tmpfs', // Provides an isolated, writable /tmp directory
+      '/tmp',
+    );
+
+    const workspacePath = tryRealpath(this.options.workspace);
+
+    const bindFlag = workspaceWrite ? '--bind-try' : '--ro-bind-try';
+
+    if (workspaceWrite) {
+      bwrapArgs.push(
+        '--bind-try',
+        this.options.workspace,
+        this.options.workspace,
+      );
+      if (workspacePath !== this.options.workspace) {
+        bwrapArgs.push('--bind-try', workspacePath, workspacePath);
+      }
+    } else {
+      bwrapArgs.push(
+        '--ro-bind-try',
+        this.options.workspace,
+        this.options.workspace,
+      );
+      if (workspacePath !== this.options.workspace) {
+        bwrapArgs.push('--ro-bind-try', workspacePath, workspacePath);
+      }
+    }
+
+    const { worktreeGitDir, mainGitDir } =
+      resolveGitWorktreePaths(workspacePath);
+    if (worktreeGitDir) {
+      bwrapArgs.push(bindFlag, worktreeGitDir, worktreeGitDir);
+    }
+    if (mainGitDir) {
+      bwrapArgs.push(bindFlag, mainGitDir, mainGitDir);
+    }
+
+    const allowedPaths = sanitizePaths(req.policy?.allowedPaths) || [];
+    const normalizedWorkspace = normalize(workspacePath).replace(/\/$/, '');
+    for (const allowedPath of allowedPaths) {
+      const resolved = tryRealpath(allowedPath);
+      if (!fs.existsSync(resolved)) continue;
+      const normalizedAllowedPath = normalize(resolved).replace(/\/$/, '');
+      if (normalizedAllowedPath !== normalizedWorkspace) {
+        if (
+          !workspaceWrite &&
+          normalizedAllowedPath.startsWith(normalizedWorkspace + '/')
+        ) {
+          bwrapArgs.push('--ro-bind-try', resolved, resolved);
+        } else {
+          bwrapArgs.push('--bind-try', resolved, resolved);
+        }
+      }
+    }
+
+    const additionalReads =
+      sanitizePaths(mergedAdditional.fileSystem?.read) || [];
+    for (const p of additionalReads) {
+      try {
+        const safeResolvedPath = tryRealpath(p);
+        bwrapArgs.push('--ro-bind-try', safeResolvedPath, safeResolvedPath);
+      } catch (e: unknown) {
+        debugLogger.warn(e instanceof Error ? e.message : String(e));
+      }
+    }
+
+    const additionalWrites =
+      sanitizePaths(mergedAdditional.fileSystem?.write) || [];
+    for (const p of additionalWrites) {
+      try {
+        const safeResolvedPath = tryRealpath(p);
+        bwrapArgs.push('--bind-try', safeResolvedPath, safeResolvedPath);
+      } catch (e: unknown) {
+        debugLogger.warn(e instanceof Error ? e.message : String(e));
+      }
+    }
+
+    for (const file of GOVERNANCE_FILES) {
+      const filePath = join(this.options.workspace, file.path);
+      touch(filePath, file.isDirectory);
+      const realPath = tryRealpath(filePath);
+      bwrapArgs.push('--ro-bind', filePath, filePath);
+      if (realPath !== filePath) {
+        bwrapArgs.push('--ro-bind', realPath, realPath);
+      }
+    }
+
+    const forbiddenPaths = sanitizePaths(this.options.forbiddenPaths) || [];
+    for (const p of forbiddenPaths) {
+      let resolved: string;
+      try {
+        resolved = tryRealpath(p); // Forbidden paths should still resolve to block the real path
+        if (!fs.existsSync(resolved)) continue;
+      } catch (e: unknown) {
+        debugLogger.warn(
+          `Failed to resolve forbidden path ${p}: ${e instanceof Error ? e.message : String(e)}`,
+        );
+        bwrapArgs.push('--ro-bind', '/dev/null', p);
+        continue;
+      }
+      try {
+        const stat = fs.statSync(resolved);
+        if (stat.isDirectory()) {
+          bwrapArgs.push('--tmpfs', resolved, '--remount-ro', resolved);
+        } else {
+          bwrapArgs.push('--ro-bind', '/dev/null', resolved);
+        }
+      } catch (e: unknown) {
+        if (isErrnoException(e) && e.code === 'ENOENT') {
+          bwrapArgs.push('--symlink', '/dev/null', resolved);
+        } else {
+          debugLogger.warn(
+            `Failed to stat forbidden path ${resolved}: ${e instanceof Error ? e.message : String(e)}`,
+          );
+          bwrapArgs.push('--ro-bind', '/dev/null', resolved);
+        }
+      }
+    }
+
+    // Mask secret files (.env, .env.*)
+    bwrapArgs.push(
+      ...(await this.getSecretFilesArgs(req.policy?.allowedPaths)),
+    );
+
     const bpfPath = getSeccompBpfPath();
 
     bwrapArgs.push('--seccomp', '9');
@@ -155,140 +381,66 @@ export class LinuxSandboxManager implements SandboxManager {
   }
 
   /**
-   * Generates arguments for network isolation.
+   * Generates bubblewrap arguments to mask secret files.
    */
-  private getNetworkArgs(req: SandboxRequest): string[] {
-    return req.policy?.networkAccess
-      ? [
-          '--unshare-user',
-          '--unshare-ipc',
-          '--unshare-pid',
-          '--unshare-uts',
-          '--unshare-cgroup',
-        ]
-      : ['--unshare-all'];
-  }
-
-  /**
-   * Generates the base bubblewrap arguments for isolation.
-   */
-  private getBaseArgs(): string[] {
-    return [
-      '--new-session', // Isolate session
-      '--die-with-parent', // Prevent orphaned runaway processes
-      '--ro-bind',
-      '/',
-      '/',
-      '--dev', // Creates a safe, minimal /dev (replaces --dev-bind)
-      '/dev',
-      '--proc', // Creates a fresh procfs for the unshared PID namespace
-      '/proc',
-      '--tmpfs', // Provides an isolated, writable /tmp directory
-      '/tmp',
-      // Note: --dev /dev sets up /dev/pts automatically
-      '--bind',
-      this.options.workspace,
-      this.options.workspace,
-    ];
-  }
-
-  /**
-   * Generates arguments for protected governance files.
-   */
-  private getGovernanceArgs(): string[] {
-    const args: string[] = [];
-    // Protected governance files are bind-mounted as read-only, even if the workspace is RW.
-    // We ensure they exist on the host and resolve real paths to prevent symlink bypasses.
-    // In bwrap, later binds override earlier ones for the same path.
-    for (const file of GOVERNANCE_FILES) {
-      const filePath = join(this.options.workspace, file.path);
-      touch(filePath, file.isDirectory);
-
-      const realPath = fs.realpathSync(filePath);
-
-      args.push('--ro-bind', filePath, filePath);
-      if (realPath !== filePath) {
-        args.push('--ro-bind', realPath, realPath);
-      }
-    }
-    return args;
-  }
-
-  /**
-   * Generates arguments for allowed paths.
-   */
-  private getAllowedPathsArgs(allowedPaths?: string[]): string[] {
+  private async getSecretFilesArgs(allowedPaths?: string[]): Promise<string[]> {
     const args: string[] = [];
+    const maskPath = this.getMaskFilePath();
     const paths = sanitizePaths(allowedPaths) || [];
-    const normalizedWorkspace = this.normalizePath(this.options.workspace);
+    const searchDirs = new Set([this.options.workspace, ...paths]);
+    const findPatterns = getSecretFileFindArgs();
 
-    for (const p of paths) {
-      if (this.normalizePath(p) !== normalizedWorkspace) {
-        args.push('--bind-try', p, p);
-      }
-    }
-    return args;
-  }
-
-  /**
-   * Generates arguments for forbidden paths.
-   */
-  private async getForbiddenPathsArgs(
-    forbiddenPaths?: string[],
-  ): Promise<string[]> {
-    const args: string[] = [];
-    const paths = sanitizePaths(forbiddenPaths) || [];
-
-    for (const p of paths) {
+    for (const dir of searchDirs) {
       try {
-        const originalPath = this.normalizePath(p);
-        const resolvedPath = await tryRealpath(originalPath);
+        // Use the native 'find' command for performance and to catch nested secrets.
+        // We limit depth to 3 to keep it fast while covering common nested structures.
+        // We use -prune to skip heavy directories efficiently while matching dotfiles.
+        const findResult = await spawnAsync('find', [
+          dir,
+          '-maxdepth',
+          '3',
+          '-type',
+          'd',
+          '(',
+          '-name',
+          '.git',
+          '-o',
+          '-name',
+          'node_modules',
+          '-o',
+          '-name',
+          '.venv',
+          '-o',
+          '-name',
+          '__pycache__',
+          '-o',
+          '-name',
+          'dist',
+          '-o',
+          '-name',
+          'build',
+          ')',
+          '-prune',
+          '-o',
+          '-type',
+          'f',
+          ...findPatterns,
+          '-print0',
+        ]);
 
-        // Mask the resolved path to prevent access to the underlying file.
-        const resolvedMask = await this.getMaskArgs(resolvedPath);
-        args.push(...resolvedMask);
-
-        // If the original path was a symlink, mask it as well to prevent access
-        // through the link itself.
-        if (resolvedPath !== originalPath) {
-          const originalMask = await this.getMaskArgs(originalPath);
-          args.push(...originalMask);
+        const files = findResult.stdout.toString().split('\0');
+        for (const file of files) {
+          if (file.trim()) {
+            args.push('--bind', maskPath, file.trim());
+          }
         }
       } catch (e) {
-        throw new Error(
-          `Failed to deny access to forbidden path: ${p}. ${
-            e instanceof Error ? e.message : String(e)
-          }`,
+        debugLogger.log(
+          `LinuxSandboxManager: Failed to find or mask secret files in ${dir}`,
+          e,
         );
       }
     }
     return args;
   }
-
-  /**
-   * Generates bubblewrap arguments to mask a forbidden path.
-   */
-  private async getMaskArgs(path: string): Promise<string[]> {
-    try {
-      const stats = await fs.promises.stat(path);
-
-      if (stats.isDirectory()) {
-        // Directories are masked by mounting an empty, read-only tmpfs.
-        return ['--tmpfs', path, '--remount-ro', path];
-      }
-      // Existing files are masked by binding them to /dev/null.
-      return ['--ro-bind-try', '/dev/null', path];
-    } catch (e) {
-      if (isNodeError(e) && e.code === 'ENOENT') {
-        // Non-existent paths are masked by a broken symlink. This prevents
-        // creation within the sandbox while avoiding host remnants.
-        return ['--symlink', '/.forbidden', path];
-      }
-      throw e;
-    }
-  }
-
-  private normalizePath(p: string): string {
-    return normalize(p).replace(/\/$/, '');
-  }
 }

packages/core/src/sandbox/macos/MacOsSandboxManager.test.ts

@@ -35,10 +35,13 @@ describe('MacOsSandboxManager', () => {
       networkAccess: mockNetworkAccess,
     };
 
-    manager = new MacOsSandboxManager({ workspace: mockWorkspace });
+    manager = new MacOsSandboxManager({
+      workspace: mockWorkspace,
+      forbiddenPaths: [],
+    });
 
     // Mock the seatbelt args builder to isolate manager tests
-    vi.spyOn(seatbeltArgsBuilder, 'buildSeatbeltArgs').mockResolvedValue([
+    vi.spyOn(seatbeltArgsBuilder, 'buildSeatbeltArgs').mockReturnValue([
       '-p',
       '(mock profile)',
       '-D',
@@ -68,7 +71,7 @@ describe('MacOsSandboxManager', () => {
         workspace: mockWorkspace,
         allowedPaths: mockAllowedPaths,
         networkAccess: mockNetworkAccess,
-        forbiddenPaths: undefined,
+        forbiddenPaths: [],
         workspaceWrite: true,
         additionalPermissions: {
           fileSystem: {
@@ -112,7 +115,10 @@ describe('MacOsSandboxManager', () => {
           SAFE_VAR: '1',
           GITHUB_TOKEN: 'sensitive',
         },
-        policy: mockPolicy,
+        policy: {
+          ...mockPolicy,
+          sanitizationConfig: { enableEnvironmentVariableRedaction: true },
+        },
       });
 
       expect(result.env['SAFE_VAR']).toBe('1');
@@ -174,15 +180,16 @@ describe('MacOsSandboxManager', () => {
 
     describe('forbiddenPaths', () => {
       it('should parameterize forbidden paths and explicitly deny them', async () => {
-        await manager.prepareCommand({
+        const managerWithForbidden = new MacOsSandboxManager({
+          workspace: mockWorkspace,
+          forbiddenPaths: ['/tmp/forbidden1'],
+        });
+        await managerWithForbidden.prepareCommand({
           command: 'echo',
           args: [],
           cwd: mockWorkspace,
           env: {},
-          policy: {
-            ...mockPolicy,
-            forbiddenPaths: ['/tmp/forbidden1'],
-          },
+          policy: mockPolicy,
         });
 
         expect(seatbeltArgsBuilder.buildSeatbeltArgs).toHaveBeenCalledWith(
@@ -193,15 +200,16 @@ describe('MacOsSandboxManager', () => {
       });
 
       it('explicitly denies non-existent forbidden paths to prevent creation', async () => {
-        await manager.prepareCommand({
+        const managerWithForbidden = new MacOsSandboxManager({
+          workspace: mockWorkspace,
+          forbiddenPaths: ['/tmp/does-not-exist'],
+        });
+        await managerWithForbidden.prepareCommand({
           command: 'echo',
           args: [],
           cwd: mockWorkspace,
           env: {},
-          policy: {
-            ...mockPolicy,
-            forbiddenPaths: ['/tmp/does-not-exist'],
-          },
+          policy: mockPolicy,
         });
 
         expect(seatbeltArgsBuilder.buildSeatbeltArgs).toHaveBeenCalledWith(
@@ -212,7 +220,11 @@ describe('MacOsSandboxManager', () => {
       });
 
       it('should override allowed paths if a path is also in forbidden paths', async () => {
-        await manager.prepareCommand({
+        const managerWithForbidden = new MacOsSandboxManager({
+          workspace: mockWorkspace,
+          forbiddenPaths: ['/tmp/conflict'],
+        });
+        await managerWithForbidden.prepareCommand({
           command: 'echo',
           args: [],
           cwd: mockWorkspace,
@@ -220,7 +232,6 @@ describe('MacOsSandboxManager', () => {
           policy: {
             ...mockPolicy,
             allowedPaths: ['/tmp/conflict'],
-            forbiddenPaths: ['/tmp/conflict'],
           },
         });
 

packages/core/src/sandbox/macos/MacOsSandboxManager.ts

@@ -10,7 +10,9 @@ import {
   type SandboxedCommand,
   type SandboxPermissions,
   type GlobalSandboxOptions,
+  type ParsedSandboxDenial,
 } from '../../services/sandboxManager.js';
+import type { ShellExecutionResult } from '../../services/shellExecutionService.js';
 import {
   sanitizeEnvironment,
   getSecureSanitizationConfig,
@@ -24,26 +26,15 @@ import {
   isKnownSafeCommand,
   isDangerousCommand,
   isStrictlyApproved,
-} from './commandSafety.js';
-import { type SandboxPolicyManager } from '../../policy/sandboxPolicyManager.js';
-
-export interface MacOsSandboxOptions extends GlobalSandboxOptions {
-  /** The current sandbox mode behavior from config. */
-  modeConfig?: {
-    readonly?: boolean;
-    network?: boolean;
-    approvedTools?: string[];
-    allowOverrides?: boolean;
-  };
-  /** The policy manager for persistent approvals. */
-  policyManager?: SandboxPolicyManager;
-}
+} from '../utils/commandSafety.js';
+import { verifySandboxOverrides } from '../utils/commandUtils.js';
+import { parsePosixSandboxDenials } from '../utils/sandboxDenialUtils.js';
 
 /**
  * A SandboxManager implementation for macOS that uses Seatbelt.
  */
 export class MacOsSandboxManager implements SandboxManager {
-  constructor(private readonly options: MacOsSandboxOptions) {}
+  constructor(private readonly options: GlobalSandboxOptions) {}
 
   isKnownSafeCommand(args: string[]): boolean {
     const toolName = args[0];
@@ -58,6 +49,10 @@ export class MacOsSandboxManager implements SandboxManager {
     return isDangerousCommand(args);
   }
 
+  parseDenials(result: ShellExecutionResult): ParsedSandboxDenial | undefined {
+    return parsePosixSandboxDenials(result);
+  }
+
   async prepareCommand(req: SandboxRequest): Promise<SandboxedCommand> {
     await initializeShellParsers();
     const sanitizationConfig = getSecureSanitizationConfig(
@@ -70,17 +65,7 @@ export class MacOsSandboxManager implements SandboxManager {
     const allowOverrides = this.options.modeConfig?.allowOverrides ?? true;
 
     // Reject override attempts in plan mode
-    if (!allowOverrides && req.policy?.additionalPermissions) {
-      const perms = req.policy.additionalPermissions;
-      if (
-        perms.network ||
-        (perms.fileSystem?.write && perms.fileSystem.write.length > 0)
-      ) {
-        throw new Error(
-          'Sandbox request rejected: Cannot override readonly/network restrictions in Plan mode.',
-        );
-      }
-    }
+    verifySandboxOverrides(allowOverrides, req.policy);
 
     // If not in readonly mode OR it's a strictly approved pipeline, allow workspace writes
     const isApproved = allowOverrides
@@ -120,10 +105,10 @@ export class MacOsSandboxManager implements SandboxManager {
         false,
     };
 
-    const sandboxArgs = await buildSeatbeltArgs({
+    const sandboxArgs = buildSeatbeltArgs({
       workspace: this.options.workspace,
       allowedPaths: [...(req.policy?.allowedPaths || [])],
-      forbiddenPaths: req.policy?.forbiddenPaths,
+      forbiddenPaths: this.options.forbiddenPaths,
       networkAccess: mergedAdditional.network,
       workspaceWrite,
       additionalPermissions: mergedAdditional,

packages/core/src/sandbox/macos/seatbeltArgsBuilder.test.ts

@@ -3,25 +3,31 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import { buildSeatbeltArgs } from './seatbeltArgsBuilder.js';
-import * as sandboxManager from '../../services/sandboxManager.js';
+import * as fsUtils from '../utils/fsUtils.js';
 import fs from 'node:fs';
 import os from 'node:os';
 
+vi.mock('../utils/fsUtils.js', async () => {
+  const actual = await vi.importActual('../utils/fsUtils.js');
+  return {
+    ...actual,
+    tryRealpath: vi.fn((p) => p),
+    resolveGitWorktreePaths: vi.fn(() => ({})),
+  };
+});
+
 describe('seatbeltArgsBuilder', () => {
-  beforeEach(() => {
+  afterEach(() => {
     vi.restoreAllMocks();
   });
 
   describe('buildSeatbeltArgs', () => {
-    it('should build a strict allowlist profile allowing the workspace via param', async () => {
-      // Mock tryRealpath to just return the path for testing
-      vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-        async (p) => p,
-      );
+    it('should build a strict allowlist profile allowing the workspace via param', () => {
+      vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => p);
 
-      const args = await buildSeatbeltArgs({
+      const args = buildSeatbeltArgs({
         workspace: '/Users/test/workspace',
       });
 
@@ -38,11 +44,9 @@ describe('seatbeltArgsBuilder', () => {
       expect(args).toContain(`TMPDIR=${os.tmpdir()}`);
     });
 
-    it('should allow network when networkAccess is true', async () => {
-      vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-        async (p) => p,
-      );
-      const args = await buildSeatbeltArgs({
+    it('should allow network when networkAccess is true', () => {
+      vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => p);
+      const args = buildSeatbeltArgs({
         workspace: '/test',
         networkAccess: true,
       });
@@ -51,10 +55,8 @@ describe('seatbeltArgsBuilder', () => {
     });
 
     describe('governance files', () => {
-      it('should inject explicit deny rules for governance files', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(async (p) =>
-          p.toString(),
-        );
+      it('should inject explicit deny rules for governance files', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => p.toString());
         vi.spyOn(fs, 'existsSync').mockReturnValue(true);
         vi.spyOn(fs, 'lstatSync').mockImplementation(
           (p) =>
@@ -64,35 +66,29 @@ describe('seatbeltArgsBuilder', () => {
             }) as unknown as fs.Stats,
         );
 
-        const args = await buildSeatbeltArgs({
-          workspace: '/Users/test/workspace',
+        const args = buildSeatbeltArgs({
+          workspace: '/test/workspace',
         });
         const profile = args[1];
 
-        // .gitignore should be a literal deny
         expect(args).toContain('-D');
-        expect(args).toContain(
-          'GOVERNANCE_FILE_0=/Users/test/workspace/.gitignore',
-        );
+        expect(args).toContain('GOVERNANCE_FILE_0=/test/workspace/.gitignore');
         expect(profile).toContain(
           '(deny file-write* (literal (param "GOVERNANCE_FILE_0")))',
         );
 
-        // .git should be a subpath deny
-        expect(args).toContain('GOVERNANCE_FILE_2=/Users/test/workspace/.git');
+        expect(args).toContain('GOVERNANCE_FILE_2=/test/workspace/.git');
         expect(profile).toContain(
           '(deny file-write* (subpath (param "GOVERNANCE_FILE_2")))',
         );
       });
 
-      it('should protect both the symlink and the real path if they differ', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => {
-            if (p === '/test/workspace/.gitignore')
-              return '/test/real/.gitignore';
-            return p.toString();
-          },
-        );
+      it('should protect both the symlink and the real path if they differ', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => {
+          if (p === '/test/workspace/.gitignore')
+            return '/test/real/.gitignore';
+          return p.toString();
+        });
         vi.spyOn(fs, 'existsSync').mockReturnValue(true);
         vi.spyOn(fs, 'lstatSync').mockImplementation(
           () =>
@@ -102,7 +98,7 @@ describe('seatbeltArgsBuilder', () => {
             }) as unknown as fs.Stats,
         );
 
-        const args = await buildSeatbeltArgs({ workspace: '/test/workspace' });
+        const args = buildSeatbeltArgs({ workspace: '/test/workspace' });
         const profile = args[1];
 
         expect(args).toContain('GOVERNANCE_FILE_0=/test/workspace/.gitignore');
@@ -117,15 +113,13 @@ describe('seatbeltArgsBuilder', () => {
     });
 
     describe('allowedPaths', () => {
-      it('should parameterize allowed paths and normalize them', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => {
-            if (p === '/test/symlink') return '/test/real_path';
-            return p;
-          },
-        );
+      it('should parameterize allowed paths and normalize them', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => {
+          if (p === '/test/symlink') return '/test/real_path';
+          return p;
+        });
 
-        const args = await buildSeatbeltArgs({
+        const args = buildSeatbeltArgs({
           workspace: '/test',
           allowedPaths: ['/custom/path1', '/test/symlink'],
         });
@@ -141,12 +135,10 @@ describe('seatbeltArgsBuilder', () => {
     });
 
     describe('forbiddenPaths', () => {
-      it('should parameterize forbidden paths and explicitly deny them', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => p,
-        );
+      it('should parameterize forbidden paths and explicitly deny them', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => p);
 
-        const args = await buildSeatbeltArgs({
+        const args = buildSeatbeltArgs({
           workspace: '/test',
           forbiddenPaths: ['/secret/path'],
         });
@@ -161,22 +153,21 @@ describe('seatbeltArgsBuilder', () => {
         );
       });
 
-      it('resolves forbidden symlink paths to their real paths', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => {
-            if (p === '/test/symlink') return '/test/real_path';
-            return p;
-          },
-        );
+      it('resolves forbidden symlink paths to their real paths', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => {
+          if (p === '/test/symlink' || p === '/test/missing-dir') {
+            return '/test/real_path';
+          }
+          return p;
+        });
 
-        const args = await buildSeatbeltArgs({
+        const args = buildSeatbeltArgs({
           workspace: '/test',
           forbiddenPaths: ['/test/symlink'],
         });
 
         const profile = args[1];
 
-        // The builder should resolve the symlink and explicitly deny the real target path
         expect(args).toContain('-D');
         expect(args).toContain('FORBIDDEN_PATH_0=/test/real_path');
         expect(profile).toContain(
@@ -184,12 +175,10 @@ describe('seatbeltArgsBuilder', () => {
         );
       });
 
-      it('explicitly denies non-existent forbidden paths to prevent creation', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => p,
-        );
+      it('explicitly denies non-existent forbidden paths to prevent creation', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => p);
 
-        const args = await buildSeatbeltArgs({
+        const args = buildSeatbeltArgs({
           workspace: '/test',
           forbiddenPaths: ['/test/missing-dir/missing-file.txt'],
         });
@@ -205,12 +194,10 @@ describe('seatbeltArgsBuilder', () => {
         );
       });
 
-      it('should override allowed paths if a path is also in forbidden paths', async () => {
-        vi.spyOn(sandboxManager, 'tryRealpath').mockImplementation(
-          async (p) => p,
-        );
+      it('should override allowed paths if a path is also in forbidden paths', () => {
+        vi.mocked(fsUtils.tryRealpath).mockImplementation((p) => p);
 
-        const args = await buildSeatbeltArgs({
+        const args = buildSeatbeltArgs({
           workspace: '/test',
           allowedPaths: ['/custom/path1'],
           forbiddenPaths: ['/custom/path1'],
@@ -226,8 +213,6 @@ describe('seatbeltArgsBuilder', () => {
         expect(profile).toContain(allowString);
         expect(profile).toContain(denyString);
 
-        // Verify ordering: The explicit deny must appear AFTER the explicit allow in the profile string
-        // Seatbelt rules are evaluated in order where the latest rule matching a path wins
         const allowIndex = profile.indexOf(allowString);
         const denyIndex = profile.indexOf(denyString);
         expect(denyIndex).toBeGreaterThan(allowIndex);

packages/core/src/sandbox/macos/seatbeltArgsBuilder.ts

@@ -15,8 +15,9 @@ import {
   type SandboxPermissions,
   sanitizePaths,
   GOVERNANCE_FILES,
-  tryRealpath,
+  SECRET_FILES,
 } from '../../services/sandboxManager.js';
+import { tryRealpath, resolveGitWorktreePaths } from '../utils/fsUtils.js';
 
 /**
  * Options for building macOS Seatbelt arguments.
@@ -44,13 +45,11 @@ export interface SeatbeltArgsOptions {
  * Returns arguments up to the end of sandbox-exec configuration (e.g. ['-p', '<profile>', '-D', ...])
  * Does not include the final '--' separator or the command to run.
  */
-export async function buildSeatbeltArgs(
-  options: SeatbeltArgsOptions,
-): Promise<string[]> {
+export function buildSeatbeltArgs(options: SeatbeltArgsOptions): string[] {
   let profile = BASE_SEATBELT_PROFILE + '\n';
   const args: string[] = [];
 
-  const workspacePath = await tryRealpath(options.workspace);
+  const workspacePath = tryRealpath(options.workspace);
   args.push('-D', `WORKSPACE=${workspacePath}`);
   args.push('-D', `WORKSPACE_RAW=${options.workspace}`);
   profile += `(allow file-read* (subpath (param "WORKSPACE_RAW")))\n`;
@@ -67,7 +66,7 @@ export async function buildSeatbeltArgs(
   // (Seatbelt evaluates rules in order, later rules win for same path).
   for (let i = 0; i < GOVERNANCE_FILES.length; i++) {
     const governanceFile = path.join(workspacePath, GOVERNANCE_FILES[i].path);
-    const realGovernanceFile = await tryRealpath(governanceFile);
+    const realGovernanceFile = tryRealpath(governanceFile);
 
     // Determine if it should be treated as a directory (subpath) or a file (literal).
     // .git is generally a directory, while ignore files are literals.
@@ -91,43 +90,49 @@ export async function buildSeatbeltArgs(
     }
   }
 
-  // Auto-detect and support git worktrees by granting read and write access to the underlying git directory
-  try {
-    const gitPath = path.join(workspacePath, '.git');
-    const gitStat = fs.lstatSync(gitPath);
-    if (gitStat.isFile()) {
-      const gitContent = fs.readFileSync(gitPath, 'utf8');
-      const match = gitContent.match(/^gitdir:\s*(.+)$/m);
-      if (match && match[1]) {
-        let worktreeGitDir = match[1].trim();
-        if (!path.isAbsolute(worktreeGitDir)) {
-          worktreeGitDir = path.resolve(workspacePath, worktreeGitDir);
-        }
-        const resolvedWorktreeGitDir = await tryRealpath(worktreeGitDir);
+  // Add explicit deny rules for secret files (.env, .env.*) in the workspace and allowed paths.
+  // We use regex rules to avoid expensive file discovery scans.
+  // Anchoring to workspace/allowed paths to avoid over-blocking.
+  const searchPaths = sanitizePaths([
+    options.workspace,
+    ...(options.allowedPaths || []),
+  ]) || [options.workspace];
 
-        // Grant write access to the worktree's specific .git directory
-        args.push('-D', `WORKTREE_GIT_DIR=${resolvedWorktreeGitDir}`);
-        profile += `(allow file-read* file-write* (subpath (param "WORKTREE_GIT_DIR")))\n`;
-
-        // Grant write access to the main repository's .git directory (objects, refs, etc. are shared)
-        // resolvedWorktreeGitDir is usually like: /path/to/main-repo/.git/worktrees/worktree-name
-        const mainGitDir = await tryRealpath(
-          path.dirname(path.dirname(resolvedWorktreeGitDir)),
-        );
-        if (mainGitDir && mainGitDir.endsWith('.git')) {
-          args.push('-D', `MAIN_GIT_DIR=${mainGitDir}`);
-          profile += `(allow file-read* file-write* (subpath (param "MAIN_GIT_DIR")))\n`;
-        }
+  for (const basePath of searchPaths) {
+    const resolvedBase = tryRealpath(basePath);
+    for (const secret of SECRET_FILES) {
+      // Map pattern to Seatbelt regex
+      let regexPattern: string;
+      const escapedBase = escapeRegex(resolvedBase);
+      if (secret.pattern.endsWith('*')) {
+        // .env.* -> .env\..+ (match .env followed by dot and something)
+        // We anchor the secret file name to either a directory separator or the start of the relative path.
+        const basePattern = secret.pattern.slice(0, -1).replace(/\./g, '\\\\.');
+        regexPattern = `^${escapedBase}/(.*/)?${basePattern}[^/]+$`;
+      } else {
+        // .env -> \.env$
+        const basePattern = secret.pattern.replace(/\./g, '\\\\.');
+        regexPattern = `^${escapedBase}/(.*/)?${basePattern}$`;
       }
+      profile += `(deny file-read* file-write* (regex #"${regexPattern}"))\n`;
     }
-  } catch (_e) {
-    // Ignore if .git doesn't exist, isn't readable, etc.
   }
 
-  const tmpPath = await tryRealpath(os.tmpdir());
+  // Auto-detect and support git worktrees by granting read and write access to the underlying git directory
+  const { worktreeGitDir, mainGitDir } = resolveGitWorktreePaths(workspacePath);
+  if (worktreeGitDir) {
+    args.push('-D', `WORKTREE_GIT_DIR=${worktreeGitDir}`);
+    profile += `(allow file-read* file-write* (subpath (param "WORKTREE_GIT_DIR")))\n`;
+  }
+  if (mainGitDir) {
+    args.push('-D', `MAIN_GIT_DIR=${mainGitDir}`);
+    profile += `(allow file-read* file-write* (subpath (param "MAIN_GIT_DIR")))\n`;
+  }
+
+  const tmpPath = tryRealpath(os.tmpdir());
   args.push('-D', `TMPDIR=${tmpPath}`);
 
-  const nodeRootPath = await tryRealpath(
+  const nodeRootPath = tryRealpath(
     path.dirname(path.dirname(process.execPath)),
   );
   args.push('-D', `NODE_ROOT=${nodeRootPath}`);
@@ -142,7 +147,7 @@ export async function buildSeatbeltArgs(
     for (const p of paths) {
       if (!p.trim()) continue;
       try {
-        let resolved = await tryRealpath(p);
+        let resolved = tryRealpath(p);
 
         // If this is a 'bin' directory (like /usr/local/bin or homebrew/bin),
         // also grant read access to its parent directory so that symlinked
@@ -165,8 +170,10 @@ export async function buildSeatbeltArgs(
 
   // Handle allowedPaths
   const allowedPaths = sanitizePaths(options.allowedPaths) || [];
+  const resolvedAllowedPaths: string[] = [];
   for (let i = 0; i < allowedPaths.length; i++) {
-    const allowedPath = await tryRealpath(allowedPaths[i]);
+    const allowedPath = tryRealpath(allowedPaths[i]);
+    resolvedAllowedPaths.push(allowedPath);
     args.push('-D', `ALLOWED_PATH_${i}=${allowedPath}`);
     profile += `(allow file-read* file-write* (subpath (param "ALLOWED_PATH_${i}")))\n`;
   }
@@ -176,7 +183,7 @@ export async function buildSeatbeltArgs(
     const { read, write } = options.additionalPermissions.fileSystem;
     if (read) {
       for (let i = 0; i < read.length; i++) {
-        const resolved = await tryRealpath(read[i]);
+        const resolved = tryRealpath(read[i]);
         const paramName = `ADDITIONAL_READ_${i}`;
         args.push('-D', `${paramName}=${resolved}`);
         let isFile = false;
@@ -194,7 +201,7 @@ export async function buildSeatbeltArgs(
     }
     if (write) {
       for (let i = 0; i < write.length; i++) {
-        const resolved = await tryRealpath(write[i]);
+        const resolved = tryRealpath(write[i]);
         const paramName = `ADDITIONAL_WRITE_${i}`;
         args.push('-D', `${paramName}=${resolved}`);
         let isFile = false;
@@ -215,7 +222,7 @@ export async function buildSeatbeltArgs(
   // Handle forbiddenPaths
   const forbiddenPaths = sanitizePaths(options.forbiddenPaths) || [];
   for (let i = 0; i < forbiddenPaths.length; i++) {
-    const forbiddenPath = await tryRealpath(forbiddenPaths[i]);
+    const forbiddenPath = tryRealpath(forbiddenPaths[i]);
     args.push('-D', `FORBIDDEN_PATH_${i}=${forbiddenPath}`);
     profile += `(deny file-read* file-write* (subpath (param "FORBIDDEN_PATH_${i}")))\n`;
   }
@@ -228,3 +235,23 @@ export async function buildSeatbeltArgs(
 
   return args;
 }
+
+/**
+ * Escapes a string for use within a Seatbelt regex literal #"..."
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\"]/g, (c) => {
+    if (c === '"') {
+      // Escape double quotes for the Scheme string literal
+      return '\\"';
+    }
+    if (c === '\\') {
+      // A literal backslash needs to be \\ in the regex.
+      // To get \\ in the regex engine, we need \\\\ in the Scheme string literal.
+      return '\\\\\\\\';
+    }
+    // For other regex special characters (like .), we need \c in the regex.
+    // To get \c in the regex engine, we need \\c in the Scheme string literal.
+    return '\\\\' + c;
+  });
+}