Update package.json from 0.54.1 to 0.54.2

chore(release): v0.54.1
fix(patch): cherry-pick 56f9688 to release/v0.54.0-pr-28700 to patch version v0.54.0 and create version 0.54.1 (#28710 )
2026-08-10 08:56:29 -07:00 · 2026-08-06 13:14:13 -04:00 · 2026-08-06 16:13:54 +00:00 · 2026-08-06 14:54:28 +00:00 · 2026-08-06 01:28:51 +00:00 · 2026-07-31 21:33:01 +00:00
109 changed files with 15281 additions and 858 deletions
@@ -421,9 +421,9 @@ To debug the CLI's React-based UI, you can use React DevTools.

 On macOS, `gemini` uses Seatbelt (`sandbox-exec`) under a `permissive-open`
 profile (see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) that
-restricts writes to the project folder but otherwise allows all other operations
-and outbound network traffic ("open") by default. You can switch to a
-`strict-open` profile (see
+denies operations by default, confining writes to the project folder while
+allowing broad file reads and outbound network traffic ("open") by default. You
+can switch to a `strict-open` profile (see
 `packages/cli/src/utils/sandbox-macos-strict-open.sb`) that restricts both reads
 and writes to the working directory while allowing outbound network traffic by
 setting `SEATBELT_PROFILE=strict-open` in your environment or `.env` file.
@@ -18,6 +18,26 @@ on GitHub.
 | [Preview](preview.md) | Experimental features ready for early feedback. |
 | [Stable](latest.md)   | Stable, recommended for general use.            |

+## Announcements: v0.52.0 - 2026-07-22
+
+- **Caretaker Triage & Egress Services:** Implemented the core triage worker
+  foundational modules, main worker execution loops, and egress action
+  publishers alongside the octokit GitHub Action handler for egress services
+  ([#28163](https://github.com/google-gemini/gemini-cli/pull/28163),
+  [#28306](https://github.com/google-gemini/gemini-cli/pull/28306) by @chadd28).
+- **Core Tool Enhancements:** Bypassed LLM correction for JSON and IPYNB files
+  in `write_file` and `replace` tools, and simplified plan mode write policy to
+  support relative paths
+  ([#28223](https://github.com/google-gemini/gemini-cli/pull/28223) by
+  @amelidev, [#28398](https://github.com/google-gemini/gemini-cli/pull/28398) by
+  @DavidAPierce).
+- **Auth & Privacy Improvements:** Displayed clear error messages when user
+  account has no Code Assist tier, and bumped `google-auth-library` to version
+  10.9.0 ([#28304](https://github.com/google-gemini/gemini-cli/pull/28304) by
+  @ompatel-aiml,
+  [#28385](https://github.com/google-gemini/gemini-cli/pull/28385) by
+  @jerrylin3321).
+
 ## Announcements: v0.50.0 - 2026-07-08

 - **Tool Registry Discovery:** Introduced tool registry discovery capabilities
@@ -1,6 +1,6 @@
-# Latest stable release: v0.50.0
+# Latest stable release: v0.52.0

-Released: July 08, 2026
+Released: July 22, 2026

 For most users, our latest stable release is the recommended release. Install
 the latest stable version with:
@@ -11,24 +11,59 @@ npm install -g @google/gemini-cli

 ## Highlights

- **Tool Registry Discovery:** Introduced tool registry discovery capabilities,
-  enabling automatic detection and registration of tools to improve
-  extensibility.
- **Release Verification Improvements:** Enhanced release verification by
-  ignoring scripts during `npm ci` and preventing workspace binary shadowing.
- **CI Pipeline Safeguards:** Strengthened the CI pipeline to prevent bad NPM
-  releases and ensure promote job failures are correctly surfaced.
+- **Caretaker Services:** Introduced a new caretaker triage worker including
+  core foundational modules, main worker execution loops, egress action
+  publishers, and octokit GitHub Action handlers.
+- **Robust File Editing:** Core tools like `write_file` and `replace` now bypass
+  LLM corrections for JSON and IPYNB files to ensure accurate and direct file
+  modifications.
+- **Plan Mode Improvements:** Simplified plan mode write policies to natively
+  support writing to relative paths, enhancing project directory navigation.
+- **Enhanced Account Visibility:** Improved clear user-facing messages when the
+  user account does not have a Code Assist tier, and enriched shared project
+  quota limit errors with setup instructions.

 ## What's Changed

- fix/verify release npm ci ignore scripts by @rmedranollamas in
-  [#28116](https://github.com/google-gemini/gemini-cli/pull/28116)
- fix(ci): prevent workspace binary shadowing in release verification by
-  @galdawave in [#28132](https://github.com/google-gemini/gemini-cli/pull/28132)
- Feat/tool registry discovery by @ved015 in
-  [#28113](https://github.com/google-gemini/gemini-cli/pull/28113)
- fix(ci): prevent bad NPM releases and promote job crashes by @galdawave in
-  [#28147](https://github.com/google-gemini/gemini-cli/pull/28147)
+- Refactor: exclude transient CI configuration files from workspace context by
+  @DavidAPierce in
+  [#28216](https://github.com/google-gemini/gemini-cli/pull/28216)
+- feat(caretaker-triage): add triage worker core foundational modules by
+  @chadd28 in [#28163](https://github.com/google-gemini/gemini-cli/pull/28163)
+- feat(caretaker-egress): implement octokit github action handler for egress
+  service by @chadd28 in
+  [#28303](https://github.com/google-gemini/gemini-cli/pull/28303)
+- chore(release): bump version to 0.52.0-nightly.20260707.g27a3da3e8 by
+  @gemini-cli-robot in
+  [#28323](https://github.com/google-gemini/gemini-cli/pull/28323)
+- Changelog for v0.51.0-preview.0 by @gemini-cli-robot in
+  [#28320](https://github.com/google-gemini/gemini-cli/pull/28320)
+- Changelog for v0.50.0 by @gemini-cli-robot in
+  [#28322](https://github.com/google-gemini/gemini-cli/pull/28322)
+- fix(core-tools): bypass LLM correction for JSON and IPYNB files in write_file
+  and replace by @amelidev in
+  [#28223](https://github.com/google-gemini/gemini-cli/pull/28223)
+- fix(core): use unambiguous previous intent label in fallback summary by
+  @amelidev in [#28343](https://github.com/google-gemini/gemini-cli/pull/28343)
+- feat(caretaker-triage): implement main worker execution loop and egress action
+  publisher by @chadd28 in
+  [#28306](https://github.com/google-gemini/gemini-cli/pull/28306)
+- fix(privacy): show a clear message when the account has no Code Assist tier by
+  @ompatel-aiml in
+  [#28304](https://github.com/google-gemini/gemini-cli/pull/28304)
+- fix(core): enrich shared project quota limit errors with setup hint by
+  @amelidev in [#28391](https://github.com/google-gemini/gemini-cli/pull/28391)
+- fix(a2a-server): ensure task cancellation aborts execution loop by
+  @luisfelipe-alt in
+  [#28316](https://github.com/google-gemini/gemini-cli/pull/28316)
+- fix(core): simplify plan mode write policy to support relative paths by
+  @DavidAPierce in
+  [#28398](https://github.com/google-gemini/gemini-cli/pull/28398)
+- feat(core): Bump node google-auth-library version to 10.9.0 by @jerrylin3321
+  in [#28385](https://github.com/google-gemini/gemini-cli/pull/28385)
+- chore/release: bump version to 0.52.0-nightly.20260715.gfa975395b by
+  @gemini-cli-robot in
+  [#28402](https://github.com/google-gemini/gemini-cli/pull/28402)

 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.49.0...v0.50.0
+https://github.com/google-gemini/gemini-cli/compare/v0.51.0...v0.52.0
@@ -1,6 +1,6 @@
-# Preview release: v0.51.0-preview.0
+# Preview release: v0.53.0-preview.0

-Released: July 8, 2026
+Released: July 22, 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).
@@ -13,53 +13,42 @@ npm install -g @google/gemini-cli@preview

 ## Highlights

- **Caretaker Cloud Run Services**: Implemented a Cloud Run webhook ingestion
-  service and egress service skeleton to support advanced caretaker features.
- **Enhanced Security & Sandbox Hardening**: Enforced a case-insensitive
-  sensitive path blocklist and VS Code human-in-the-loop (HITL) checks, resolved
-  a directory escape vulnerability in the memory import processor, and marked
-  `~/.gitconfig` as read-only within the macOS sandbox.
- **Improved Thought Leakage and Escape Handling**: Resolved potential thought
-  leakage by stripping thinking/thought processes from scrubbed history turns,
-  and ensured escape sequences in string literals are correctly preserved for
-  modern models.
- **Robust Path & API Updates**: Enhanced defensive path resolution for
-  at-reference files, and updated the Vertex AI base URL configuration to
-  support the latest API updates.
+- **Caretaker LLM Triage Orchestrator**: Implemented the LLM triage orchestrator
+  and container build configuration to support caretaker triage workflows.
+- **Enhanced Workspace Trust & Sandbox Hardening**: Aligned macOS permissive
+  Seatbelt profiles with the deny-default model and enforced workspace trust and
+  task isolation in the Agent-to-Agent (A2A) server to prevent remote code
+  execution (RCE).
+- **Core Robustness & API Protections**: Mitigated infinite ReAct and prompt
+  injection loops, and prevented 400 Bad Request errors by grouping cancelled
+  tool responses and coalescing consecutive roles.
+- **Robust Credentials & Fallbacks**: Restored the
+  `GOOGLE_APPLICATION_CREDENTIALS` environment variable fallback and
+  sequentially verified cached credentials.
+- **Evaluation Coverage Reporting**: Added a new command to generate
+  comprehensive eval coverage reports.

 ## What's Changed

- Changelog for v0.50.0-preview.1 by @gemini-cli-robot in
-  [#28150](https://github.com/google-gemini/gemini-cli/pull/28150)
- Fix no_proxy test by @jerrylin3321 in
-  [#28131](https://github.com/google-gemini/gemini-cli/pull/28131)
- chore(release): bump version to 0.51.0-nightly.20260625.g3fbf93e26 by
-  @gemini-cli-robot in
-  [#28151](https://github.com/google-gemini/gemini-cli/pull/28151)
- Vertex base url update by @DavidAPierce in
-  [#28145](https://github.com/google-gemini/gemini-cli/pull/28145)
- fix(security): enforce case-insensitive sensitive path blocklist and vscode
-  hitl by @luisfelipe-alt in
-  [#27966](https://github.com/google-gemini/gemini-cli/pull/27966)
- fix(core-tools): resolve defensive path resolution for at-reference files and
-  fix macOS tests by @luisfelipe-alt in
-  [#28053](https://github.com/google-gemini/gemini-cli/pull/28053)
- feat(caretaker): implement Cloud Run webhook ingestion service by @chadd28 in
-  [#28015](https://github.com/google-gemini/gemini-cli/pull/28015)
- fix(core): resolve symbolic link directory escape in memory import processor
-  by @luisfelipe-alt in
-  [#28233](https://github.com/google-gemini/gemini-cli/pull/28233)
- feat(caretaker): egress cloud run service skeleton by @chadd28 in
-  [#28167](https://github.com/google-gemini/gemini-cli/pull/28167)
- fix(sandbox): make ~/.gitconfig read-only in the macOS sandbox by
-  @ompatel-aiml in
-  [#28221](https://github.com/google-gemini/gemini-cli/pull/28221)
- fix(core): preserve escape sequences in string literals for modern models by
+- fix(core,a2a): group cancelled tool responses and coalesce consecutive roles
+  to prevent 400 Bad Request by @luisfelipe-alt in
+  [#28407](https://github.com/google-gemini/gemini-cli/pull/28407)
+- feat(caretaker-triage): implement LLM triage orchestrator and container build
+  by @chadd28 in
+  [#28345](https://github.com/google-gemini/gemini-cli/pull/28345)
+- refactor(cli): align macOS permissive Seatbelt profiles with deny-default
+  model by @ompatel-aiml in
+  [#28424](https://github.com/google-gemini/gemini-cli/pull/28424)
+- fix(core): mitigate infinite ReAct loops and prompt injection loops by
+  @amelidev in [#28429](https://github.com/google-gemini/gemini-cli/pull/28429)
+- fix(a2a-server): enforce workspace trust and task isolation to prevent RCE by
  @luisfelipe-alt in
-  [#28299](https://github.com/google-gemini/gemini-cli/pull/28299)
- fix(core): strip thoughts from scrubbed history turns and resolve thought
-  leakage by @amelidev in
-  [#27971](https://github.com/google-gemini/gemini-cli/pull/27971)
+  [#28470](https://github.com/google-gemini/gemini-cli/pull/28470)
+- fix(core): sequentially verify cached credentials and restore
+  GOOGLE_APPLICATION_CREDENTIALS fallback by @luisfelipe-alt in
+  [#28472](https://github.com/google-gemini/gemini-cli/pull/28472)
+- feat(evals): add eval coverage report command by @ved015 in
+  [#28169](https://github.com/google-gemini/gemini-cli/pull/28169)

 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.50.0-preview.1...v0.51.0-preview.0
+https://github.com/google-gemini/gemini-cli/compare/v0.52.0-preview.0...v0.53.0-preview.0
@@ -87,8 +87,9 @@ preferred container solution.

 Lightweight, built-in sandboxing using `sandbox-exec`.

-**Default profile**: `permissive-open` - restricts writes outside project
-directory but allows most other operations.
+**Default profile**: `permissive-open` - denies operations by default; confines
+writes to the project directory while allowing broad file reads and network
+access.

 Built-in profiles (set via `SEATBELT_PROFILE` env var):

@@ -2736,10 +2736,10 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
  - Run the CLI once with this set to generate the file.
 - **`SEATBELT_PROFILE`** (macOS specific):
  - Switches the Seatbelt (`sandbox-exec`) profile on macOS.
-  - `permissive-open`: (Default) Restricts writes to the project folder (and a
-    few other folders, see
-    `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other
-    operations.
+  - `permissive-open`: (Default) Denies operations by default, confining writes
+    to the project folder (and a few other folders, see
+    `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) while allowing
+    broad file reads and network access.
  - `restrictive-open`: Declines operations by default, allows network.
  - `strict-open`: Restricts both reads and writes to the working directory,
    allows network.
@@ -35,7 +35,7 @@ describe('Interactive file system', () => {
    const run = await rig.runInteractive();

    // Step 1: Read the file
-    const readPrompt = `Read the version from ${fileName}`;
+    const readPrompt = `Read the version from ${fileName} using the read_file tool`;
    await run.type(readPrompt);
    await run.type('\r');

@@ -1,12 +1,12 @@
 {
  "name": "@google/gemini-cli",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@google/gemini-cli",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "workspaces": [
        "packages/*"
      ],
@@ -17782,7 +17782,7 @@
    },
    "packages/a2a-server": {
      "name": "@google/gemini-cli-a2a-server",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "dependencies": {
        "@a2a-js/sdk": "0.3.11",
        "@google-cloud/storage": "7.19.0",
@@ -18242,7 +18242,7 @@
    },
    "packages/cli": {
      "name": "@google/gemini-cli",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "license": "Apache-2.0",
      "dependencies": {
        "@agentclientprotocol/sdk": "0.16.1",
@@ -18458,7 +18458,7 @@
    },
    "packages/core": {
      "name": "@google/gemini-cli-core",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "license": "Apache-2.0",
      "dependencies": {
        "@a2a-js/sdk": "0.3.11",
@@ -19131,7 +19131,7 @@
    },
    "packages/devtools": {
      "name": "@google/gemini-cli-devtools",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "license": "Apache-2.0",
      "dependencies": {
        "ws": "8.16.0"
@@ -19167,7 +19167,7 @@
    },
    "packages/sdk": {
      "name": "@google/gemini-cli-sdk",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "license": "Apache-2.0",
      "dependencies": {
        "@google/gemini-cli-core": "file:../core",
@@ -19506,7 +19506,7 @@
    },
    "packages/test-utils": {
      "name": "@google/gemini-cli-test-utils",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "license": "Apache-2.0",
      "dependencies": {
        "@google/gemini-cli-core": "file:../core",
@@ -19524,7 +19524,7 @@
    },
    "packages/vscode-ide-companion": {
      "name": "gemini-cli-vscode-ide-companion",
-      "version": "0.52.0",
+      "version": "0.54.1",
      "license": "LICENSE",
      "dependencies": {
        "@modelcontextprotocol/sdk": "1.23.0",
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli",
-  "version": "0.52.0",
+  "version": "0.54.2",
  "engines": {
    "node": ">=20.0.0"
  },
@@ -14,7 +14,7 @@
    "url": "git+https://github.com/google-gemini/gemini-cli.git"
  },
  "config": {
-    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.52.0"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.54.1"
  },
  "scripts": {
    "start": "cross-env NODE_ENV=development node scripts/start.js",
@@ -34,6 +34,7 @@
    "docs:keybindings": "tsx ./scripts/generate-keybindings-doc.ts",
    "eval:inventory": "tsx ./scripts/eval-inventory-cli.ts",
    "eval:inventory:json": "tsx ./scripts/eval-inventory-cli.ts --json",
+    "eval:coverage": "tsx ./scripts/eval-coverage-cli.ts",
    "build": "node scripts/build.js",
    "build-and-start": "npm run build && npm run start --",
    "build:vscode": "node scripts/build_vscode_companion.js",
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli-a2a-server",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "description": "Gemini CLI A2A Server",
  "repository": {
    "type": "git",
@@ -21,6 +21,17 @@ vi.mock('../utils/path_utils.js', () => ({
 }));

 // Mocks for constructor dependencies
+vi.mock('@google/gemini-cli-core', () => ({
+  GeminiEventType: {
+    PRIMARY_TURN_STARTED: 'PRIMARY_TURN_STARTED',
+    SECONDARY_TURN_STARTED: 'SECONDARY_TURN_STARTED',
+  },
+  SimpleExtensionLoader: vi.fn(),
+  checkPathTrust: vi.fn().mockReturnValue({ isTrusted: false }),
+  isHeadlessMode: vi.fn().mockReturnValue(true),
+  resolveToRealPath: vi.fn().mockImplementation((p) => p),
+}));
+
 vi.mock('../config/config.js', () => ({
  loadConfig: vi.fn().mockReturnValue({
    getSessionId: () => 'test-session',
@@ -30,6 +41,10 @@ vi.mock('../config/config.js', () => ({
  loadEnvironment: vi.fn(),
  setIsTrusted: vi.fn().mockReturnValue(false),
  setTargetDir: vi.fn().mockReturnValue('/tmp'),
+  envStorage: {
+    run: (env: Record<string, string>, cb: () => unknown) => cb(),
+  },
+  cwdSymbol: Symbol('cwd'),
 }));

 vi.mock('../config/settings.js', () => ({
@@ -752,4 +752,107 @@ describe('Task', () => {
      expect(changed3).toBe(true);
    });
  });
+
+  describe('getProposedContent (CRLF Line Ending Normalization)', () => {
+    it('should successfully replace LF-based strings in CRLF-based files', async () => {
+      const fs = await import('node:fs');
+      const path = await import('node:path');
+      const os = await import('node:os');
+
+      const mockConfig = createMockConfig({
+        getTargetDir: () => os.tmpdir(),
+        validatePathAccess: () => null,
+      });
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const tempFile = path.resolve(os.tmpdir(), 'crlf_test_file.txt');
+      const crlfContent = 'line1\r\nline2\r\nline3\r\n';
+      fs.writeFileSync(tempFile, crlfContent, 'utf8');
+
+      try {
+        const oldString = 'line2\n';
+        const newString = 'line2-optimized\n';
+
+        const result = await task['getProposedContent'](
+          tempFile,
+          oldString,
+          newString,
+        );
+
+        expect(result).toContain('line2-optimized');
+        expect(result).toContain('\r\n'); // It should preserve the original CRLF line endings
+      } finally {
+        if (fs.existsSync(tempFile)) {
+          fs.unlinkSync(tempFile);
+        }
+      }
+    });
+
+    it('should successfully replace CRLF-based strings in CRLF-based files by normalizing all to LF', async () => {
+      const fs = await import('node:fs');
+      const path = await import('node:path');
+      const os = await import('node:os');
+
+      const mockConfig = createMockConfig({
+        getTargetDir: () => os.tmpdir(),
+        validatePathAccess: () => null,
+      });
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const tempFile = path.resolve(
+        os.tmpdir(),
+        'crlf_test_file_crlf_inputs.txt',
+      );
+      const crlfContent = 'line1\r\nline2\r\nline3\r\n';
+      fs.writeFileSync(tempFile, crlfContent, 'utf8');
+
+      try {
+        const oldString = 'line2\r\n';
+        const newString = 'line2-optimized\r\n';
+
+        const result = await task['getProposedContent'](
+          tempFile,
+          oldString,
+          newString,
+        );
+
+        expect(result).toContain('line2-optimized');
+        expect(result).toContain('\r\n'); // It should preserve the original CRLF line endings
+      } finally {
+        if (fs.existsSync(tempFile)) {
+          fs.unlinkSync(tempFile);
+        }
+      }
+    });
+  });
 });
@@ -666,13 +666,18 @@ export class Task {
    }

    try {
-      const currentContent = await fs.readFile(resolvedPath, 'utf8');
-      return this._applyReplacement(
+      const rawContent = await fs.readFile(resolvedPath, 'utf8');
+      const hasCrlf = rawContent.includes('\r\n');
+      const currentContent = rawContent.replace(/\r\n/g, '\n');
+      const normalizedOldString = old_string.replace(/\r\n/g, '\n');
+      const normalizedNewString = new_string.replace(/\r\n/g, '\n');
+      const proposedContent = this._applyReplacement(
        currentContent,
-        old_string,
-        new_string,
-        old_string === '' && currentContent === '',
+        normalizedOldString,
+        normalizedNewString,
+        normalizedOldString === '' && currentContent === '',
      );
+      return hasCrlf ? proposedContent.replace(/\n/g, '\r\n') : proposedContent;
    } catch (err) {
      if (!isNodeError(err) || err.code !== 'ENOENT') throw err;
      return '';
@@ -1092,19 +1097,21 @@ export class Task {
    logger.info(
      `[Task] Adding ${completedTools.length} tool responses to history without generating a new response.`,
    );
-    const responsesToAdd = completedTools.flatMap(
-      (toolCall) => toolCall.response.responseParts,
-    );
-
-    for (const response of responsesToAdd) {
-      let parts: genAiPart[];
-      if (Array.isArray(response)) {
-        parts = response;
-      } else if (typeof response === 'string') {
-        parts = [{ text: response }];
-      } else {
-        parts = [response];
+    const parts: genAiPart[] = [];
+    for (const toolCall of completedTools) {
+      const response = toolCall.response?.responseParts;
+      if (!response) {
+        continue;
      }
+      if (Array.isArray(response)) {
+        parts.push(...response);
+      } else if (typeof response === 'string') {
+        parts.push({ text: response });
+      } else {
+        parts.push(response);
+      }
+    }
+    if (parts.length > 0) {
      // eslint-disable-next-line @typescript-eslint/no-floating-promises
      this.geminiClient.addHistory({
        role: 'user',
@@ -7,6 +7,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as dotenv from 'dotenv';
+import { AsyncLocalStorage } from 'node:async_hooks';

 import {
  AuthType,
@@ -17,6 +18,7 @@ import {
  startupProfiler,
  PREVIEW_GEMINI_MODEL,
  homedir,
+  tmpdir,
  GitService,
  fetchAdminControlsOnce,
  getCodeAssistServer,
@@ -28,28 +30,246 @@ import {
  type TelemetryTarget,
  type ConfigParameters,
  type ExtensionLoader,
+  resolveToRealPath,
 } from '@google/gemini-cli-core';

 import { logger } from '../utils/logger.js';
 import type { Settings } from './settings.js';
 import { type AgentSettings, CoderAgentEvent } from '../types.js';

-const INITIAL_FOLDER_TRUST = process.env['GEMINI_FOLDER_TRUST'];
+export const envStorage = new AsyncLocalStorage<TaskEnv>();
+
+const deletedKeysSymbol = Symbol('deletedKeys');
+export const cwdSymbol = Symbol('cwd');
+
+export interface TaskEnv extends Record<string, string | undefined> {
+  [deletedKeysSymbol]?: Set<string>;
+  [cwdSymbol]?: string;
+}
+
+// Set up a Proxy on process.env to intercept reads and writes, isolating environment variables per task
+const originalEnv = process.env;
+const envProxy = new Proxy(originalEnv, {
+  get(target, prop) {
+    if (typeof prop === 'string') {
+      const taskEnv = envStorage.getStore();
+      if (taskEnv) {
+        const deleted = taskEnv[deletedKeysSymbol];
+        if (deleted?.has(prop)) {
+          return undefined;
+        }
+        if (Object.prototype.hasOwnProperty.call(taskEnv, prop)) {
+          return taskEnv[prop];
+        }
+      }
+      return target[prop];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion
+    return target[prop as any];
+  },
+  has(target, prop) {
+    if (typeof prop === 'string') {
+      const taskEnv = envStorage.getStore();
+      if (taskEnv) {
+        const deleted = taskEnv[deletedKeysSymbol];
+        if (deleted?.has(prop)) {
+          return false;
+        }
+        if (Object.prototype.hasOwnProperty.call(taskEnv, prop)) {
+          return true;
+        }
+      }
+      return prop in target;
+    }
+    return prop in target;
+  },
+  set(target, prop, value) {
+    if (typeof prop === 'string') {
+      if (
+        prop === '__proto__' ||
+        prop === 'constructor' ||
+        prop === 'prototype'
+      ) {
+        return false;
+      }
+      const taskEnv = envStorage.getStore();
+      if (taskEnv) {
+        taskEnv[deletedKeysSymbol]?.delete(prop);
+        taskEnv[prop] = String(value);
+        return true;
+      }
+      target[prop] = String(value);
+      return true;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-assignment
+    target[prop as any] = value;
+    return true;
+  },
+  deleteProperty(target, prop) {
+    if (typeof prop === 'string') {
+      if (
+        prop === '__proto__' ||
+        prop === 'constructor' ||
+        prop === 'prototype'
+      ) {
+        return false;
+      }
+      const taskEnv = envStorage.getStore();
+      if (taskEnv) {
+        delete taskEnv[prop];
+        (taskEnv[deletedKeysSymbol] ??= new Set()).add(prop);
+        return true;
+      }
+      delete target[prop];
+      return true;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion
+    return delete target[prop as any];
+  },
+  ownKeys(target) {
+    const taskEnv = envStorage.getStore();
+    if (taskEnv) {
+      const keys = new Set<string | symbol>([
+        ...Object.getOwnPropertyNames(target),
+        ...Object.getOwnPropertySymbols(target),
+        ...Object.keys(taskEnv),
+      ]);
+      taskEnv[deletedKeysSymbol]?.forEach((key) => {
+        keys.delete(key);
+      });
+      return Array.from(keys);
+    }
+    return [
+      ...Object.getOwnPropertyNames(target),
+      ...Object.getOwnPropertySymbols(target),
+    ];
+  },
+  getOwnPropertyDescriptor(target, prop) {
+    const taskEnv = envStorage.getStore();
+    if (taskEnv && typeof prop === 'string') {
+      const deleted = taskEnv[deletedKeysSymbol];
+      if (deleted?.has(prop)) {
+        return undefined;
+      }
+      if (Object.prototype.hasOwnProperty.call(taskEnv, prop)) {
+        return {
+          value: taskEnv[prop],
+          writable: true,
+          enumerable: true,
+          configurable: true,
+        };
+      }
+    }
+    return Object.getOwnPropertyDescriptor(target, prop);
+  },
+  defineProperty(target, prop, descriptor) {
+    if (typeof prop === 'string') {
+      if (
+        prop === '__proto__' ||
+        prop === 'constructor' ||
+        prop === 'prototype'
+      ) {
+        return false;
+      }
+      const taskEnv = envStorage.getStore();
+      if (taskEnv) {
+        taskEnv[deletedKeysSymbol]?.delete(prop);
+        taskEnv[prop] =
+          descriptor.value !== undefined ? String(descriptor.value) : undefined;
+        return true;
+      }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion
+    Object.defineProperty(target, prop as any, descriptor);
+    return true;
+  },
+});
+
+Object.defineProperty(process, 'env', {
+  value: envProxy,
+  writable: false,
+  configurable: true,
+});
+
+// NOTE: Monkey-patching process.cwd and process.chdir via AsyncLocalStorage is a robust way
+// to simulate workspace isolation in a concurrent server. However, please be aware of a critical
+// limitation: Node.js native C++ APIs (such as fs.readFileSync, fs.writeFile, etc.) and child
+// process spawning APIs (like child_process.spawn) resolve relative paths using the OS-level
+// working directory of the process, NOT the JS-level process.cwd() function.
+// To prevent cross-task interference, all file paths in the core package must be resolved to
+// absolute paths using path.resolve/path.join relative to config.getTargetDir() or config.getCwd()
+// before being passed to native APIs.
+const originalCwd = process.cwd;
+process.cwd = function () {
+  const taskEnv = envStorage.getStore();
+  if (taskEnv && taskEnv[cwdSymbol]) {
+    return taskEnv[cwdSymbol];
+  }
+  return originalCwd.call(process);
+};
+
+const originalChdir = process.chdir;
+process.chdir = function (directory: string) {
+  const taskEnv = envStorage.getStore();
+  if (taskEnv) {
+    const resolved = path.resolve(process.cwd(), directory);
+    try {
+      const stats = fs.statSync(resolved);
+      if (!stats.isDirectory()) {
+        const err = new Error(
+          "ENOTDIR: not a directory, chdir '" + resolved + "'",
+        );
+        (err as NodeJS.ErrnoException).code = 'ENOTDIR';
+        throw err;
+      }
+    } catch (err: unknown) {
+      if (
+        err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        err.code === 'ENOENT'
+      ) {
+        const chdirErr = new Error(
+          "ENOENT: no such file or directory, chdir '" + resolved + "'",
+        );
+        (chdirErr as NodeJS.ErrnoException).code = 'ENOENT';
+        throw chdirErr;
+      }
+      throw err;
+    }
+    taskEnv[cwdSymbol] = resolved;
+    return;
+  }
+  return originalChdir.call(process, directory);
+};
+
+export function getEnv(key: string): string | undefined {
+  return process.env[key];
+}

 export async function loadConfig(
  settings: Settings,
  extensionLoader: ExtensionLoader,
  taskId: string,
  trusted: boolean = false,
+  workspaceDir: string = process.cwd(),
 ): Promise<Config> {
-  const workspaceDir = process.cwd();
+  const workspaceEnv = await loadEnvironment(trusted, workspaceDir);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const envVars: Record<string, string> = { ...process.env } as Record<
+    string,
+    string
+  >;
+  Object.assign(envVars, workspaceEnv);
+
+  const getEnvLocal = (key: string) => envVars[key];

  const folderTrust =
    settings.folderTrust === true ||
-    process.env['GEMINI_FOLDER_TRUST'] === 'true';
+    getEnvLocal('GEMINI_FOLDER_TRUST') === 'true';

-  let checkpointing = process.env['CHECKPOINTING']
-    ? process.env['CHECKPOINTING'] === 'true'
+  let checkpointing = getEnvLocal('CHECKPOINTING')
+    ? getEnvLocal('CHECKPOINTING') === 'true'
    : settings.checkpointing?.enabled;

  if (checkpointing) {
@@ -62,7 +282,7 @@ export async function loadConfig(
  }

  const approvalMode =
-    process.env['GEMINI_YOLO_MODE'] === 'true'
+    getEnvLocal('GEMINI_YOLO_MODE') === 'true'
      ? ApprovalMode.YOLO
      : ApprovalMode.DEFAULT;

@@ -91,8 +311,9 @@ export async function loadConfig(
    embeddingModel: DEFAULT_GEMINI_EMBEDDING_MODEL,
    sandbox: undefined, // Sandbox might not be relevant for a server-side agent
    targetDir: workspaceDir, // Or a specific directory the agent operates on
-    debugMode: process.env['DEBUG'] === 'true' || false,
+    debugMode: getEnvLocal('DEBUG') === 'true' || false,
    question: '', // Not used in server mode directly like CLI
+    env: envVars,

    coreTools: settings.tools?.core || undefined,
    excludeTools: settings.tools?.exclude || undefined,
@@ -107,7 +328,7 @@ export async function loadConfig(
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
      target: settings.telemetry?.target as TelemetryTarget,
      otlpEndpoint:
-        process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] ??
+        getEnvLocal('OTEL_EXPORTER_OTLP_ENDPOINT') ??
        settings.telemetry?.otlpEndpoint,
      logPrompts: settings.telemetry?.logPrompts,
    },
@@ -119,8 +340,8 @@ export async function loadConfig(
        settings.fileFiltering?.enableRecursiveFileSearch,
      customIgnoreFilePaths: [
        ...(settings.fileFiltering?.customIgnoreFilePaths || []),
-        ...(process.env['CUSTOM_IGNORE_FILE_PATHS']
-          ? process.env['CUSTOM_IGNORE_FILE_PATHS'].split(path.delimiter)
+        ...(getEnvLocal('CUSTOM_IGNORE_FILE_PATHS')
+          ? getEnvLocal('CUSTOM_IGNORE_FILE_PATHS').split(path.delimiter)
          : []),
      ],
    },
@@ -179,7 +400,7 @@ export async function loadConfig(
  await config.waitForMcpInit();
  startupProfiler.flush(config);

-  await refreshAuthentication(config, 'Config');
+  await refreshAuthentication(config, 'Config', envVars);

  return config;
 }
@@ -187,16 +408,19 @@ export async function loadConfig(
 export function setIsTrusted(
  agentSettings: AgentSettings | undefined,
 ): boolean {
-  if (INITIAL_FOLDER_TRUST !== undefined) {
-    return INITIAL_FOLDER_TRUST === 'true';
+  const folderTrustEnv = getEnv('GEMINI_FOLDER_TRUST');
+  if (folderTrustEnv !== undefined) {
+    return folderTrustEnv === 'true';
  }
  return !!agentSettings?.isTrusted;
 }

-export function setTargetDir(agentSettings: AgentSettings | undefined): string {
+export async function setTargetDir(
+  agentSettings: AgentSettings | undefined,
+): Promise<string> {
  const originalCWD = process.cwd();
  const targetDir =
-    process.env['CODER_AGENT_WORKSPACE_PATH'] ??
+    getEnv('CODER_AGENT_WORKSPACE_PATH') ??
    (agentSettings?.kind === CoderAgentEvent.StateAgentSettingsEvent
      ? agentSettings.workspacePath
      : undefined);
@@ -210,58 +434,170 @@ export function setTargetDir(agentSettings: AgentSettings | undefined): string {
  );

  try {
-    const resolvedPath = path.resolve(targetDir);
-    process.chdir(resolvedPath);
+    let resolvedPath: string;
+    try {
+      resolvedPath = resolveToRealPath(targetDir);
+    } catch (err: unknown) {
+      if (
+        err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        err.code === 'ENOENT'
+      ) {
+        const parentDir = path.dirname(path.resolve(targetDir));
+        resolvedPath = path.join(
+          resolveToRealPath(parentDir),
+          path.basename(targetDir),
+        );
+      } else {
+        throw err;
+      }
+    }
+
+    const isTestEnv =
+      process.env['VITEST'] === 'true' ||
+      process.env['NODE_ENV'] === 'test' ||
+      process.argv.some((arg) => arg.includes('vitest')) ||
+      resolvedPath.startsWith(resolveToRealPath(tmpdir()));
+
+    const allowedRoot = resolveToRealPath(
+      getEnv('CODER_AGENT_ALLOWED_ROOT') ||
+        (isTestEnv ? path.parse(resolvedPath).root : homedir()),
+    );
+    const relative = path.relative(allowedRoot, resolvedPath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error(
+        `Workspace path ${resolvedPath} is outside the allowed root directory`,
+      );
+    }
+
+    let stats: fs.Stats;
+    try {
+      stats = await fs.promises.stat(resolvedPath);
+    } catch (err: unknown) {
+      if (
+        err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        err.code === 'ENOENT'
+      ) {
+        if (isTestEnv) {
+          await fs.promises.mkdir(resolvedPath, { recursive: true });
+          stats = await fs.promises.stat(resolvedPath);
+        } else {
+          throw new Error(`Workspace path ${resolvedPath} does not exist`);
+        }
+      } else {
+        throw err;
+      }
+    }
+
+    if (!stats.isDirectory()) {
+      throw new Error(`Workspace path ${resolvedPath} is not a directory`);
+    }
+
    return resolvedPath;
  } catch (e) {
-    logger.error(
-      `[CoderAgentExecutor] Error resolving workspace path: ${e}, returning original os.cwd()`,
-    );
-    return originalCWD;
+    logger.error(`[CoderAgentExecutor] Error resolving workspace path: ${e}`);
+    throw e;
  }
 }

-export function loadEnvironment(): void {
-  const envFilePath = findEnvFile(process.cwd());
+export async function loadEnvironment(
+  isTrusted: boolean = false,
+  workspacePath: string = process.cwd(),
+): Promise<Record<string, string>> {
+  // For untrusted workspaces, we completely bypass workspace-level .env loading
+  // and only load environment variables from the user's trusted home directory.
+  let envFilePath: string | null = null;
+  if (isTrusted) {
+    envFilePath = await findEnvFile(workspacePath);
+  } else {
+    const homeGeminiEnvPath = path.join(homedir(), GEMINI_DIR, '.env');
+    try {
+      await fs.promises.access(homeGeminiEnvPath);
+      envFilePath = homeGeminiEnvPath;
+    } catch {
+      const homeEnvPath = path.join(homedir(), '.env');
+      try {
+        await fs.promises.access(homeEnvPath);
+        envFilePath = homeEnvPath;
+      } catch {
+        // Ignore
+      }
+    }
+  }
+  const envVars: Record<string, string> = {};
  if (envFilePath) {
-    dotenv.config({ path: envFilePath, override: true });
+    try {
+      const content = await fs.promises.readFile(envFilePath, 'utf-8');
+      const parsed = dotenv.parse(content);
+      for (const key in parsed) {
+        if (
+          Object.prototype.hasOwnProperty.call(parsed, key) &&
+          key !== '__proto__' &&
+          key !== 'constructor' &&
+          key !== 'prototype'
+        ) {
+          envVars[key] = parsed[key];
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
  }
+  return envVars;
 }

-function findEnvFile(startDir: string): string | null {
+async function findEnvFile(startDir: string): Promise<string | null> {
  let currentDir = path.resolve(startDir);
  while (true) {
    // prefer gemini-specific .env under GEMINI_DIR
    const geminiEnvPath = path.join(currentDir, GEMINI_DIR, '.env');
-    if (fs.existsSync(geminiEnvPath)) {
+    try {
+      await fs.promises.access(geminiEnvPath);
      return geminiEnvPath;
+    } catch {
+      // Ignore
    }
    const envPath = path.join(currentDir, '.env');
-    if (fs.existsSync(envPath)) {
+    try {
+      await fs.promises.access(envPath);
      return envPath;
+    } catch {
+      // Ignore
    }
    const parentDir = path.dirname(currentDir);
    if (parentDir === currentDir || !parentDir) {
-      // check .env under home as fallback, again preferring gemini-specific .env
-      const homeGeminiEnvPath = path.join(process.cwd(), GEMINI_DIR, '.env');
-      if (fs.existsSync(homeGeminiEnvPath)) {
-        return homeGeminiEnvPath;
-      }
-      const homeEnvPath = path.join(homedir(), '.env');
-      if (fs.existsSync(homeEnvPath)) {
-        return homeEnvPath;
-      }
-      return null;
+      break;
    }
    currentDir = parentDir;
  }
+  // check .env under home as fallback, again preferring gemini-specific .env
+  const homeGeminiEnvPath = path.join(homedir(), GEMINI_DIR, '.env');
+  try {
+    await fs.promises.access(homeGeminiEnvPath);
+    return homeGeminiEnvPath;
+  } catch {
+    // Ignore
+  }
+  const homeEnvPath = path.join(homedir(), '.env');
+  try {
+    await fs.promises.access(homeEnvPath);
+    return homeEnvPath;
+  } catch {
+    return null;
+  }
 }

 async function refreshAuthentication(
  config: Config,
  logPrefix: string,
+  envVars: Record<string, string>,
 ): Promise<void> {
-  if (process.env['USE_CCPA']) {
+  const getEnvLocal = (key: string) => envVars[key];
+
+  if (getEnvLocal('USE_CCPA')) {
    logger.info(`[${logPrefix}] Using CCPA Auth:`);

    logger.info(`[${logPrefix}] Attempting COMPUTE_ADC first.`);
@@ -276,7 +612,7 @@ async function refreshAuthentication(
      );

      const useComputeAdc =
-        process.env['GEMINI_CLI_USE_COMPUTE_ADC'] === 'true';
+        getEnvLocal('GEMINI_CLI_USE_COMPUTE_ADC') === 'true';
      const isHeadless = isHeadlessMode();

      if (isHeadless || useComputeAdc) {
@@ -305,11 +641,14 @@ async function refreshAuthentication(
    }

    logger.info(
-      `[${logPrefix}] GOOGLE_CLOUD_PROJECT: ${process.env['GOOGLE_CLOUD_PROJECT']}`,
+      `[${logPrefix}] GOOGLE_CLOUD_PROJECT: ${getEnvLocal('GOOGLE_CLOUD_PROJECT')}`,
    );
-  } else if (process.env['GEMINI_API_KEY']) {
+  } else if (getEnvLocal('GEMINI_API_KEY')) {
    logger.info(`[${logPrefix}] Using Gemini API Key`);
-    await config.refreshAuth(AuthType.USE_GEMINI);
+    await config.refreshAuth(
+      AuthType.USE_GEMINI,
+      getEnvLocal('GEMINI_API_KEY'),
+    );
  } else {
    const errorMessage = `[${logPrefix}] Unable to set GeneratorConfig. Please provide a GEMINI_API_KEY or set USE_CCPA.`;
    logger.error(errorMessage);
@@ -36,9 +36,12 @@ interface ExtensionConfig {
  excludeTools?: string[];
 }

-export function loadExtensions(workspaceDir: string): GeminiCLIExtension[] {
+export function loadExtensions(
+  workspaceDir: string,
+  isTrusted: boolean = false,
+): GeminiCLIExtension[] {
  const allExtensions = [
-    ...loadExtensionsFromDir(workspaceDir),
+    ...(isTrusted ? loadExtensionsFromDir(workspaceDir) : []),
    ...loadExtensionsFromDir(homedir()),
  ];

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+let mockHomeDir = '';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...original,
+    homedir: () => mockHomeDir,
+  };
+});
+
+import { loadEnvironment } from './config.js';
+
+describe('Vulnerability Mitigation: b-519269096', () => {
+  let tempWorkspaceDir: string;
+
+  beforeEach(() => {
+    // Create a temporary home directory securely using mkdtempSync to ensure hermeticity
+    mockHomeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gemini-mock-home-'));
+
+    // Create a temporary workspace directory representing an untrusted repo
+    tempWorkspaceDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'gemini-exploit-workspace-'),
+    );
+    const geminiDir = path.join(tempWorkspaceDir, '.gemini');
+    fs.mkdirSync(geminiDir, { recursive: true });
+
+    // Mock process.cwd to return the untrusted workspace
+    vi.spyOn(process, 'cwd').mockReturnValue(tempWorkspaceDir);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+    fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
+    fs.rmSync(mockHomeDir, { recursive: true, force: true });
+  });
+
+  it('should ignore GEMINI_CLI_TRUST_WORKSPACE and GEMINI_YOLO_MODE in untrusted workspaces', async () => {
+    const geminiDir = path.join(tempWorkspaceDir, '.gemini');
+    fs.writeFileSync(
+      path.join(geminiDir, '.env'),
+      'GEMINI_CLI_TRUST_WORKSPACE=true\nGEMINI_YOLO_MODE=true\n',
+    );
+
+    // Ensure initially not set
+    vi.stubEnv('GEMINI_CLI_TRUST_WORKSPACE', '');
+    vi.stubEnv('GEMINI_YOLO_MODE', '');
+
+    // Act: load environment with isTrusted = false
+    const envVars = await loadEnvironment(false);
+
+    // Assert: In a SECURE system, these variables should NOT be loaded
+    expect(envVars['GEMINI_CLI_TRUST_WORKSPACE']).toBeUndefined();
+    expect(envVars['GEMINI_YOLO_MODE']).toBeUndefined();
+    expect(process.env['GEMINI_CLI_TRUST_WORKSPACE']).toBeFalsy();
+    expect(process.env['GEMINI_YOLO_MODE']).toBeFalsy();
+  });
+
+  it('should not load any variables from untrusted workspaces', async () => {
+    fs.writeFileSync(
+      path.join(tempWorkspaceDir, '.env'),
+      'GEMINI_API_KEY=safe-key-123;rm -rf /\nGOOGLE_CLOUD_PROJECT=my-project\n',
+    );
+
+    // Ensure initially not set
+    vi.stubEnv('GEMINI_API_KEY', '');
+    vi.stubEnv('GOOGLE_CLOUD_PROJECT', '');
+
+    // Act: load environment with isTrusted = false
+    const envVars = await loadEnvironment(false);
+
+    // Assert: No variables should be loaded from the untrusted workspace
+    expect(envVars['GEMINI_API_KEY']).toBeUndefined();
+    expect(envVars['GOOGLE_CLOUD_PROJECT']).toBeUndefined();
+    expect(process.env['GEMINI_API_KEY']).toBeFalsy();
+    expect(process.env['GOOGLE_CLOUD_PROJECT']).toBeFalsy();
+  });
+
+  it('should load all variables in trusted workspaces with isolation', async () => {
+    const geminiDir = path.join(tempWorkspaceDir, '.gemini');
+    fs.writeFileSync(
+      path.join(geminiDir, '.env'),
+      'GEMINI_CLI_TRUST_WORKSPACE=true\nGEMINI_YOLO_MODE=true\n',
+    );
+
+    // Ensure initially not set
+    vi.stubEnv('GEMINI_CLI_TRUST_WORKSPACE', '');
+    vi.stubEnv('GEMINI_YOLO_MODE', '');
+
+    // Load environment variables
+    const envVars = await loadEnvironment(true);
+
+    // Assert: In a trusted workspace, variables should be loaded
+    expect(envVars['GEMINI_CLI_TRUST_WORKSPACE']).toBe('true');
+    expect(envVars['GEMINI_YOLO_MODE']).toBe('true');
+
+    // Assert: Global process.env should NOT be polluted
+    expect(process.env['GEMINI_CLI_TRUST_WORKSPACE']).toBeFalsy();
+    expect(process.env['GEMINI_YOLO_MODE']).toBeFalsy();
+  });
+});
@@ -197,8 +197,7 @@ async function handleExecuteCommand(
 export async function createApp() {
  try {
    // Load the server configuration once on startup.
-    const workspaceRoot = setTargetDir(undefined);
-    loadEnvironment();
+    const workspaceRoot = await setTargetDir(undefined);

    // Use a temporary settings load to check if folder trust is enabled.
    // This is similar to how the CLI handles the initial trust check.
@@ -209,13 +208,35 @@ export async function createApp() {
      isHeadless: isHeadlessMode(),
    });

+    // Change the global working directory to the workspace root during startup
+    process.chdir(workspaceRoot);
+
+    // Load environment globally for the server startup
+    const globalEnv = await loadEnvironment(isTrusted ?? false, workspaceRoot);
+    // Only assign safe server-config variables to process.env to prevent credential leakage
+    const allowedServerKeys = [
+      'CODER_AGENT_PORT',
+      'CODER_AGENT_WORKSPACE_PATH',
+      'GCS_BUCKET_NAME',
+      'LOG_LEVEL',
+      'GOOGLE_APPLICATION_CREDENTIALS',
+      'GOOGLE_CLOUD_PROJECT',
+      'GEMINI_CLI_USE_COMPUTE_ADC',
+    ];
+    for (const key of allowedServerKeys) {
+      if (globalEnv[key] !== undefined) {
+        process.env[key] = globalEnv[key];
+      }
+    }
+
    const settings = loadSettings(workspaceRoot, isTrusted ?? false);
-    const extensions = loadExtensions(workspaceRoot);
+    const extensions = loadExtensions(workspaceRoot, isTrusted ?? false);
    const config = await loadConfig(
      settings,
      new SimpleExtensionLoader(extensions),
      'a2a-server',
      isTrusted ?? false,
+      workspaceRoot,
    );

    let git: GitService | undefined;
@@ -258,7 +258,7 @@ export class GCSTaskStore implements TaskStore {
      }
      const agentSettings = persistedState._agentSettings;

-      const workDir = setTargetDir(agentSettings);
+      const workDir = await setTargetDir(agentSettings);
      await fse.ensureDir(workDir);
      const workspaceFile = this.storage
        .bucket(this.bucketName)
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "description": "Gemini CLI",
  "license": "Apache-2.0",
  "repository": {
@@ -27,7 +27,7 @@
    "dist"
  ],
  "config": {
-    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.52.0"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.54.1"
  },
  "dependencies": {
    "@agentclientprotocol/sdk": "0.16.1",
@@ -319,6 +319,41 @@ describe('Session', () => {
    expect(result).toMatchObject({ stopReason: 'end_turn' });
  });

+  it.each([
+    { type: 'MAX_TOKENS_EXCEEDED', reason: 'MAX_TOKENS' },
+    { type: 'SAFETY_BLOCKED', reason: 'SAFETY' },
+    { type: 'RECITATION_BLOCKED', reason: 'RECITATION' },
+    { type: 'OTHER_BLOCKED', reason: 'OTHER' },
+    { type: 'THINKING_ONLY_RESPONSE', reason: 'STOP' },
+  ])(
+    'should gracefully handle InvalidStreamError with type $type in ACP session',
+    async ({ type, reason }) => {
+      const error = new InvalidStreamError(
+        `Stream failed with ${reason}`,
+        type as InvalidStreamError['type'],
+      );
+      mockSendMessageStream.mockImplementation(() => {
+        async function* errorGen(): AsyncGenerator<
+          ServerGeminiStreamEvent,
+          void,
+          unknown
+        > {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          yield* [] as any;
+          throw error;
+        }
+        return errorGen();
+      });
+
+      const result = await session.prompt({
+        sessionId: 'session-1',
+        prompt: [{ type: 'text', text: 'Hi' }],
+      });
+
+      expect(result).toMatchObject({ stopReason: 'end_turn' });
+    },
+  );
+
  it('should handle /memory command', async () => {
    const handleCommandSpy = vi
      .spyOn(
@@ -510,7 +510,12 @@ export class Session {
            (error.type === 'NO_RESPONSE_TEXT' ||
              error.type === 'NO_FINISH_REASON' ||
              error.type === 'MALFORMED_FUNCTION_CALL' ||
-              error.type === 'UNEXPECTED_TOOL_CALL'))
+              error.type === 'UNEXPECTED_TOOL_CALL' ||
+              error.type === 'MAX_TOKENS_EXCEEDED' ||
+              error.type === 'SAFETY_BLOCKED' ||
+              error.type === 'RECITATION_BLOCKED' ||
+              error.type === 'OTHER_BLOCKED' ||
+              error.type === 'THINKING_ONLY_RESPONSE'))
        ) {
          // The stream ended with an empty response or malformed tool call.
          // Treat this as a graceful end to the model's turn rather than a crash.
@@ -22,6 +22,7 @@ import {
  CoreEvent,
  CoreToolCallStatus,
  JsonStreamEventType,
+  TRUE_EMPTY_RESPONSE_MESSAGE,
 } from '@google/gemini-cli-core';
 import type { Part } from '@google/genai';
 import { runNonInteractive } from './nonInteractiveCli.js';
@@ -78,6 +79,7 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
    ChatRecordingService: MockChatRecordingService,
    uiTelemetryService: {
      getMetrics: vi.fn(),
+      recordSemanticValidationError: vi.fn(),
    },
    coreEvents: mockCoreEvents,
    createWorkingStdio: vi.fn(() => ({
@@ -110,6 +112,7 @@ describe('runNonInteractive', () => {
    sendMessageStream: Mock;
    resumeChat: Mock;
    getChatRecordingService: Mock;
+    getCurrentSequenceModel: Mock;
  };
  const MOCK_SESSION_METRICS: SessionMetrics = {
    models: {},
@@ -165,6 +168,7 @@ describe('runNonInteractive', () => {
        recordMessageTokens: vi.fn(),
        recordToolCalls: vi.fn(),
      })),
+      getCurrentSequenceModel: vi.fn().mockReturnValue('gemini-2.5-flash'),
    };

    mockConfig = {
@@ -193,6 +197,7 @@ describe('runNonInteractive', () => {
      getRawOutput: vi.fn().mockReturnValue(false),
      getAcceptRawOutputRisk: vi.fn().mockReturnValue(false),
      getAgentSessionNoninteractiveEnabled: vi.fn().mockReturnValue(false),
+      getUsageStatisticsEnabled: vi.fn().mockReturnValue(false),
    } as unknown as Config;

    mockSettings = {
@@ -1820,7 +1825,6 @@ describe('runNonInteractive', () => {
    };
    // @ts-expect-error - Mocking internal structure
    mockGeminiClient.getChat = vi.fn().mockReturnValue(mockChat);
-    // @ts-expect-error - Mocking internal structure
    mockGeminiClient.getCurrentSequenceModel = vi
      .fn()
      .mockReturnValue('model-1');
@@ -2298,7 +2302,13 @@ describe('runNonInteractive', () => {

    it('should handle InvalidStream event gracefully in TEXT mode', async () => {
      const events: ServerGeminiStreamEvent[] = [
-        { type: GeminiEventType.InvalidStream },
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_RESPONSE_TEXT',
+            message: 'Empty response',
+          },
+        },
      ];
      mockGeminiClient.sendMessageStream.mockReturnValue(
        createStreamFromEvents(events),
@@ -2312,7 +2322,7 @@ describe('runNonInteractive', () => {
      });

      expect(processStderrSpy).toHaveBeenCalledWith(
-        '[ERROR] Invalid stream: The model returned an empty response or malformed tool call.\n',
+        `[ERROR] ${TRUE_EMPTY_RESPONSE_MESSAGE}\n`,
      );
      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
    });
@@ -2325,7 +2335,13 @@ describe('runNonInteractive', () => {
        OutputFormat.STREAM_JSON,
      );
      const events: ServerGeminiStreamEvent[] = [
-        { type: GeminiEventType.InvalidStream },
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_RESPONSE_TEXT',
+            message: 'Empty response',
+          },
+        },
      ];
      mockGeminiClient.sendMessageStream.mockReturnValue(
        createStreamFromEvents(events),
@@ -2341,9 +2357,7 @@ describe('runNonInteractive', () => {
      const output = getWrittenOutput();
      expect(output).toContain('"type":"error"');
      expect(output).toContain('"severity":"error"');
-      expect(output).toContain(
-        'Invalid stream: The model returned an empty response or malformed tool call.',
-      );
+      expect(output).toContain(TRUE_EMPTY_RESPONSE_MESSAGE);
      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
    });

@@ -2355,7 +2369,13 @@ describe('runNonInteractive', () => {
        OutputFormat.JSON,
      );
      const events: ServerGeminiStreamEvent[] = [
-        { type: GeminiEventType.InvalidStream },
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_RESPONSE_TEXT',
+            message: 'Empty response',
+          },
+        },
      ];
      mockGeminiClient.sendMessageStream.mockReturnValue(
        createStreamFromEvents(events),
@@ -2371,8 +2391,33 @@ describe('runNonInteractive', () => {
      const output = getWrittenOutput();
      expect(output).toContain('"error": {');
      expect(output).toContain('"type": "INVALID_STREAM"');
-      expect(output).toContain(
-        'Invalid stream: The model returned an empty response or malformed tool call.',
+      expect(output).toContain(TRUE_EMPTY_RESPONSE_MESSAGE);
+      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle non-NO_RESPONSE_TEXT InvalidStream event gracefully and use message from eventValue', async () => {
+      const events: ServerGeminiStreamEvent[] = [
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'MALFORMED_FUNCTION_CALL',
+            message: 'Custom malformed function call message',
+          },
+        },
+      ];
+      mockGeminiClient.sendMessageStream.mockReturnValue(
+        createStreamFromEvents(events),
+      );
+
+      await runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'test invalid stream malformed',
+        prompt_id: 'prompt-id-invalid-malformed',
+      });
+
+      expect(processStderrSpy).toHaveBeenCalledWith(
+        '[ERROR] Custom malformed function call message\n',
      );
      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
    });
@@ -30,6 +30,12 @@ import {
  ToolErrorType,
  Scheduler,
  ROOT_SCHEDULER_ID,
+  THINKING_ONLY_COMPRESS_SUGGESTION,
+  MAX_TOKENS_EXCEEDED_SUGGESTION,
+  SAFETY_BLOCKED_MESSAGE,
+  RECITATION_BLOCKED_MESSAGE,
+  OTHER_BLOCKED_MESSAGE,
+  TRUE_EMPTY_RESPONSE_MESSAGE,
 } from '@google/gemini-cli-core';

 import type { Content, Part } from '@google/genai';
@@ -433,8 +439,31 @@ export async function runNonInteractive(
            }
            warnings.push(blockMessage);
          } else if (event.type === GeminiEventType.InvalidStream) {
-            invalidStreamError =
-              'Invalid stream: The model returned an empty response or malformed tool call.';
+            const eventValue = event.value;
+            if (eventValue?.type === 'NO_RESPONSE_TEXT') {
+              invalidStreamError = TRUE_EMPTY_RESPONSE_MESSAGE;
+            } else if (eventValue?.type === 'THINKING_ONLY_RESPONSE') {
+              invalidStreamError = THINKING_ONLY_COMPRESS_SUGGESTION;
+            } else if (eventValue?.type === 'MAX_TOKENS_EXCEEDED') {
+              invalidStreamError = MAX_TOKENS_EXCEEDED_SUGGESTION;
+            } else if (eventValue?.type === 'SAFETY_BLOCKED') {
+              invalidStreamError = SAFETY_BLOCKED_MESSAGE;
+            } else if (eventValue?.type === 'RECITATION_BLOCKED') {
+              invalidStreamError = RECITATION_BLOCKED_MESSAGE;
+            } else if (eventValue?.type === 'OTHER_BLOCKED') {
+              invalidStreamError = OTHER_BLOCKED_MESSAGE;
+            } else {
+              invalidStreamError =
+                eventValue?.message?.trim() ||
+                'Invalid stream: The model returned an empty response or malformed tool call.';
+            }
+
+            // Log semantic error telemetry without double-counting requests
+            uiTelemetryService.recordSemanticValidationError(
+              geminiClient.getCurrentSequenceModel() ?? config.getModel(),
+              eventValue?.type || 'INVALID_STREAM',
+            );
+
            if (streamFormatter) {
              streamFormatter.emitEvent({
                type: JsonStreamEventType.ERROR,
@@ -22,6 +22,7 @@ import {
  CoreEvent,
  CoreToolCallStatus,
  JsonStreamEventType,
+  TRUE_EMPTY_RESPONSE_MESSAGE,
 } from '@google/gemini-cli-core';
 import type { Part } from '@google/genai';
 import { runNonInteractive } from './nonInteractiveCliAgentSession.js';
@@ -78,6 +79,7 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
    ChatRecordingService: MockChatRecordingService,
    uiTelemetryService: {
      getMetrics: vi.fn(),
+      recordSemanticValidationError: vi.fn(),
    },
    LegacyAgentSession: original.LegacyAgentSession,
    geminiPartsToContentParts: original.geminiPartsToContentParts,
@@ -199,6 +201,7 @@ describe('runNonInteractive', () => {
      getRawOutput: vi.fn().mockReturnValue(false),
      getAcceptRawOutputRisk: vi.fn().mockReturnValue(false),
      getAgentSessionNoninteractiveEnabled: vi.fn().mockReturnValue(false),
+      getUsageStatisticsEnabled: vi.fn().mockReturnValue(false),
    } as unknown as Config;

    mockSettings = {
@@ -2457,6 +2460,126 @@ describe('runNonInteractive', () => {
      const output = JSON.parse(getWrittenOutput());
      expect(output.warnings).toBeUndefined();
    });
+
+    it('should handle InvalidStream event gracefully in TEXT mode', async () => {
+      const events: ServerGeminiStreamEvent[] = [
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_RESPONSE_TEXT',
+            message: 'Empty response',
+          },
+        },
+      ];
+      mockGeminiClient.sendMessageStream.mockReturnValue(
+        createStreamFromEvents(events),
+      );
+
+      await runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'test invalid stream',
+        prompt_id: 'prompt-id-invalid',
+      });
+
+      expect(processStderrSpy).toHaveBeenCalledWith(
+        `[ERROR] ${TRUE_EMPTY_RESPONSE_MESSAGE}\n`,
+      );
+      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle InvalidStream event gracefully in STREAM_JSON mode', async () => {
+      vi.spyOn(uiTelemetryService, 'getMetrics').mockReturnValue(
+        MOCK_SESSION_METRICS,
+      );
+      vi.spyOn(mockConfig, 'getOutputFormat').mockReturnValue(
+        OutputFormat.STREAM_JSON,
+      );
+      const events: ServerGeminiStreamEvent[] = [
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_RESPONSE_TEXT',
+            message: 'Empty response',
+          },
+        },
+      ];
+      mockGeminiClient.sendMessageStream.mockReturnValue(
+        createStreamFromEvents(events),
+      );
+
+      await runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'test invalid stream',
+        prompt_id: 'prompt-id-invalid',
+      });
+
+      const output = getWrittenOutput();
+      expect(output).toContain('"type":"error"');
+      expect(output).toContain('"severity":"error"');
+      expect(output).toContain(TRUE_EMPTY_RESPONSE_MESSAGE);
+      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle InvalidStream event gracefully in JSON mode', async () => {
+      vi.spyOn(uiTelemetryService, 'getMetrics').mockReturnValue(
+        MOCK_SESSION_METRICS,
+      );
+      vi.spyOn(mockConfig, 'getOutputFormat').mockReturnValue(
+        OutputFormat.JSON,
+      );
+      const events: ServerGeminiStreamEvent[] = [
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_RESPONSE_TEXT',
+            message: 'Empty response',
+          },
+        },
+      ];
+      mockGeminiClient.sendMessageStream.mockReturnValue(
+        createStreamFromEvents(events),
+      );
+
+      await runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'test invalid stream',
+        prompt_id: 'prompt-id-invalid',
+      });
+
+      const output = getWrittenOutput();
+      expect(output).toContain('"error": {');
+      expect(output).toContain('"type": "INVALID_STREAM"');
+      expect(output).toContain(TRUE_EMPTY_RESPONSE_MESSAGE);
+      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle non-NO_RESPONSE_TEXT InvalidStream event gracefully and use message from eventValue', async () => {
+      const events: ServerGeminiStreamEvent[] = [
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'MALFORMED_FUNCTION_CALL',
+            message: 'Malformed call',
+          },
+        },
+      ];
+      mockGeminiClient.sendMessageStream.mockReturnValue(
+        createStreamFromEvents(events),
+      );
+
+      await runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'test invalid stream',
+        prompt_id: 'prompt-id-invalid',
+      });
+
+      expect(processStderrSpy).toHaveBeenCalledWith('[ERROR] Malformed call\n');
+      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
+    });
  });

  describe('Output Sanitization', () => {
@@ -39,6 +39,12 @@ import {
  geminiPartsToContentParts,
  displayContentToString,
  debugLogger,
+  THINKING_ONLY_COMPRESS_SUGGESTION,
+  MAX_TOKENS_EXCEEDED_SUGGESTION,
+  SAFETY_BLOCKED_MESSAGE,
+  RECITATION_BLOCKED_MESSAGE,
+  OTHER_BLOCKED_MESSAGE,
+  TRUE_EMPTY_RESPONSE_MESSAGE,
 } from '@google/gemini-cli-core';

 import type { Part } from '@google/genai';
@@ -332,14 +338,17 @@ export async function runNonInteractive({
        return text ? text : undefined;
      };

-      const emitFinalSuccessResult = (): void => {
+      const emitFinalResult = (errorPayload?: {
+        type: string;
+        message: string;
+      }): void => {
        if (streamFormatter) {
          const metrics = uiTelemetryService.getMetrics();
          const durationMs = Date.now() - startTime;
          streamFormatter.emitEvent({
            type: JsonStreamEventType.RESULT,
            timestamp: new Date().toISOString(),
-            status: 'success',
+            status: errorPayload ? 'error' : 'success',
            stats: streamFormatter.convertToStreamStats(metrics, durationMs),
          });
        } else if (config.getOutputFormat() === OutputFormat.JSON) {
@@ -350,7 +359,7 @@ export async function runNonInteractive({
              config.getSessionId(),
              responseText,
              stats,
-              undefined,
+              errorPayload,
              warnings,
            ),
          );
@@ -545,6 +554,52 @@ export async function runNonInteractive({
            break;
          }
          case 'error': {
+            if (event._meta?.['code'] === 'INVALID_STREAM') {
+              const errorTypeVal = event._meta?.['errorType'];
+              const errorType =
+                typeof errorTypeVal === 'string' ? errorTypeVal : undefined;
+
+              let errorMessage = event.message;
+              if (errorType === 'NO_RESPONSE_TEXT') {
+                errorMessage = TRUE_EMPTY_RESPONSE_MESSAGE;
+              } else if (errorType === 'THINKING_ONLY_RESPONSE') {
+                errorMessage = THINKING_ONLY_COMPRESS_SUGGESTION;
+              } else if (errorType === 'MAX_TOKENS_EXCEEDED') {
+                errorMessage = MAX_TOKENS_EXCEEDED_SUGGESTION;
+              } else if (errorType === 'SAFETY_BLOCKED') {
+                errorMessage = SAFETY_BLOCKED_MESSAGE;
+              } else if (errorType === 'RECITATION_BLOCKED') {
+                errorMessage = RECITATION_BLOCKED_MESSAGE;
+              } else if (errorType === 'OTHER_BLOCKED') {
+                errorMessage = OTHER_BLOCKED_MESSAGE;
+              }
+
+              if (streamFormatter) {
+                streamFormatter.emitEvent({
+                  type: JsonStreamEventType.ERROR,
+                  timestamp: new Date().toISOString(),
+                  severity: 'error',
+                  message: errorMessage,
+                });
+              } else if (config.getOutputFormat() === OutputFormat.TEXT) {
+                process.stderr.write(`[ERROR] ${errorMessage}\n`);
+              }
+
+              // Log semantic error telemetry without double-counting requests
+              uiTelemetryService.recordSemanticValidationError(
+                geminiClient.getCurrentSequenceModel() ?? config.getModel(),
+                errorType || 'INVALID_STREAM',
+              );
+
+              // If it's a fatal stream error, we should terminate and output final results
+              emitFinalResult({
+                type: 'INVALID_STREAM',
+                message: errorMessage,
+              });
+              streamEnded = true;
+              break;
+            }
+
            if (event.fatal) {
              throw reconstructFatalError(event);
            }
@@ -613,7 +668,7 @@ export async function runNonInteractive({
              process.stderr.write(`Agent execution stopped: ${stopMessage}\n`);
            }

-            emitFinalSuccessResult();
+            emitFinalResult();
            streamEnded = true;
            break;
          }
@@ -36,6 +36,18 @@ function areModelMetricsEqual(a: ModelMetrics, b: ModelMetrics): boolean {
  ) {
    return false;
  }
+  const errorsA = a.api.errorsByType || {};
+  const errorsB = b.api.errorsByType || {};
+  const keysA = Object.keys(errorsA);
+  const keysB = Object.keys(errorsB);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  for (const key of keysA) {
+    if (errorsA[key] !== errorsB[key]) {
+      return false;
+    }
+  }
  if (
    a.tokens.input !== b.tokens.input ||
    a.tokens.prompt !== b.tokens.prompt ||
@@ -54,6 +54,7 @@ import {
  GeminiCliOperation,
  getPlanModeExitMessage,
  UPDATE_TOPIC_TOOL_NAME,
+  TRUE_EMPTY_RESPONSE_MESSAGE,
 } from '@google/gemini-cli-core';
 import type { Part, PartListUnion } from '@google/genai';
 import type { UseHistoryManagerReturn } from './useHistoryManager.js';
@@ -1045,6 +1046,107 @@ describe('useGeminiStream', () => {
    });
  });

+  it('should record tool responses in history when the model was switched due to a quota error', async () => {
+    // Regression test: returning early on a quota-triggered model switch
+    // without recording the responses leaves the already-recorded
+    // functionCall unpaired, which corrupts all subsequent requests.
+    const responseParts: Part[] = [
+      {
+        functionResponse: {
+          name: 'testTool',
+          id: 'call1',
+          response: { output: 'tool result' },
+        },
+      },
+    ];
+    const completedToolCalls: TrackedToolCall[] = [
+      {
+        request: {
+          callId: 'call1',
+          name: 'testTool',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-quota',
+        },
+        status: CoreToolCallStatus.Success,
+        responseSubmittedToGemini: false,
+        response: {
+          callId: 'call1',
+          responseParts,
+          errorType: undefined,
+        },
+        tool: { displayName: 'MockTool' },
+        invocation: {
+          getDescription: () => `Mock description`,
+        } as unknown as AnyToolInvocation,
+      } as TrackedCompletedToolCall,
+    ];
+
+    const client = new MockedGeminiClientClass(mockConfig);
+    const mockConsumeUserHint = vi.fn(() => 'switch to the nprd database');
+
+    let capturedOnComplete:
+      | ((completedTools: TrackedToolCall[]) => Promise<void>)
+      | null = null;
+
+    mockUseToolScheduler.mockImplementation((onComplete) => {
+      capturedOnComplete = onComplete;
+      return [
+        [],
+        mockScheduleToolCalls,
+        mockMarkToolsAsSubmitted,
+        vi.fn(),
+        mockCancelAllToolCalls,
+        0,
+      ];
+    });
+
+    await renderHookWithProviders(() =>
+      useGeminiStream(
+        client,
+        [],
+        mockAddItem,
+        mockConfig,
+        mockLoadedSettings,
+        mockOnDebugMessage,
+        mockHandleSlashCommand,
+        false,
+        () => 'vscode' as EditorType,
+        () => {},
+        () => Promise.resolve(),
+        true, // modelSwitchedFromQuotaError
+        () => {},
+        () => {},
+        () => {},
+        80,
+        24,
+        false,
+        mockConsumeUserHint,
+      ),
+    );
+
+    await act(async () => {
+      if (capturedOnComplete) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        await capturedOnComplete(completedToolCalls);
+      }
+    });
+
+    await waitFor(() => {
+      expect(mockMarkToolsAsSubmitted).toHaveBeenCalledWith(['call1']);
+      // The tool response must be paired with its functionCall in history,
+      // with no steering-hint text ahead of it...
+      expect(client.addHistory).toHaveBeenCalledWith({
+        role: 'user',
+        parts: responseParts,
+      });
+      // ...the turn must NOT auto-continue on the fallback model...
+      expect(mockSendMessageStream).not.toHaveBeenCalled();
+      // ...and the pending hint is left for the next real submit.
+      expect(mockConsumeUserHint).not.toHaveBeenCalled();
+    });
+  });
+
  it('should NOT stop responding when only update_topic is called', async () => {
    const topicToolCalls: TrackedToolCall[] = [
      {
@@ -1772,6 +1874,120 @@ describe('useGeminiStream', () => {
      expect(mockCancelAllToolCalls).toHaveBeenCalled();
    });

+    it('should transition to Idle state when cancelled while a tool call is in progress and completes', async () => {
+      const toolCalls: TrackedToolCall[] = [
+        {
+          request: { callId: 'call1', name: 'tool1', args: {} },
+          status: CoreToolCallStatus.Executing,
+          responseSubmittedToGemini: false,
+          tool: {
+            name: 'tool1',
+            description: 'desc1',
+            build: vi.fn().mockImplementation((_) => ({
+              getDescription: () => `Mock description`,
+            })),
+          } as any,
+          invocation: {
+            getDescription: () => `Mock description`,
+          },
+          startTime: Date.now(),
+          liveOutput: '...',
+        } as TrackedExecutingToolCall,
+      ];
+
+      const { result } = await renderTestHook(toolCalls);
+
+      // State is `Responding` because a tool is running
+      expect(result.current.streamingState).toBe(StreamingState.Responding);
+
+      // Try to cancel
+      simulateEscapeKeyPress();
+
+      // Trigger the onComplete callback with the cancelled tool call
+      await act(async () => {
+        if (capturedOnComplete) {
+          await capturedOnComplete([
+            {
+              ...toolCalls[0],
+              status: CoreToolCallStatus.Cancelled,
+              response: {
+                callId: 'call1',
+                responseParts: [],
+              },
+            } as any,
+          ]);
+        }
+      });
+
+      // The final state should be idle because the cancelled tool call was marked as submitted
+      expect(result.current.streamingState).toBe(StreamingState.Idle);
+    });
+
+    it('should append cancelled tool responses to history when cancelled while a tool call is in progress and completes with response parts', async () => {
+      const toolCalls: TrackedToolCall[] = [
+        {
+          request: { callId: 'call1', name: 'tool1', args: {} },
+          status: CoreToolCallStatus.Executing,
+          responseSubmittedToGemini: false,
+          tool: {
+            name: 'tool1',
+            description: 'desc1',
+            build: vi.fn().mockImplementation((_) => ({
+              getDescription: () => `Mock description`,
+            })),
+          } as any,
+          invocation: {
+            getDescription: () => `Mock description`,
+          },
+          startTime: Date.now(),
+          liveOutput: '...',
+        } as TrackedExecutingToolCall,
+      ];
+
+      const { result, client } = await renderTestHook(toolCalls);
+
+      // State is `Responding` because a tool is running
+      expect(result.current.streamingState).toBe(StreamingState.Responding);
+
+      // Try to cancel
+      simulateEscapeKeyPress();
+
+      const expectedResponseParts = [
+        {
+          functionResponse: {
+            name: 'tool1',
+            id: 'call1',
+            response: { error: 'cancelled' },
+          },
+        },
+      ];
+
+      // Trigger the onComplete callback with the cancelled tool call having non-empty response parts
+      await act(async () => {
+        if (capturedOnComplete) {
+          await capturedOnComplete([
+            {
+              ...toolCalls[0],
+              status: CoreToolCallStatus.Cancelled,
+              response: {
+                callId: 'call1',
+                responseParts: expectedResponseParts,
+              },
+            } as any,
+          ]);
+        }
+      });
+
+      // Assert that addHistory was called with the combined response parts
+      expect(client.addHistory).toHaveBeenCalledWith({
+        role: 'user',
+        parts: expectedResponseParts,
+      });
+
+      // The final state should be idle because the cancelled tool call was marked as submitted
+      expect(result.current.streamingState).toBe(StreamingState.Idle);
+    });
+
    it('should cancel a request when a tool is awaiting confirmation', async () => {
      const mockOnConfirm = vi.fn().mockResolvedValue(undefined);
      const toolCalls: TrackedToolCall[] = [
@@ -2306,6 +2522,68 @@ describe('useGeminiStream', () => {
        );
      });
    });
+
+    it('should use TRUE_EMPTY_RESPONSE_MESSAGE when receiving an invalid stream event of type NO_RESPONSE_TEXT', async () => {
+      mockSendMessageStream.mockClear();
+      mockSendMessageStream.mockReturnValue(
+        (async function* () {
+          yield {
+            type: ServerGeminiEventType.InvalidStream,
+            value: {
+              type: 'NO_RESPONSE_TEXT',
+              message: 'empty response text',
+            },
+          };
+        })(),
+      );
+
+      const { result } = await renderTestHook();
+
+      await act(async () => {
+        await result.current.submitQuery('test query');
+      });
+
+      await waitFor(() => {
+        expect(mockAddItem).toHaveBeenCalledWith(
+          expect.objectContaining({
+            type: MessageType.ERROR,
+            text: TRUE_EMPTY_RESPONSE_MESSAGE,
+          }),
+          expect.any(Number),
+        );
+      });
+    });
+
+    it('should use the event message when receiving a non-NO_RESPONSE_TEXT invalid stream event', async () => {
+      mockSendMessageStream.mockClear();
+      mockSendMessageStream.mockReturnValue(
+        (async function* () {
+          yield {
+            type: ServerGeminiEventType.InvalidStream,
+            value: {
+              type: 'MALFORMED_FUNCTION_CALL',
+              message: 'Custom malformed function call message',
+            },
+          };
+        })(),
+      );
+
+      const { result } = await renderTestHook();
+
+      await act(async () => {
+        await result.current.submitQuery('test query');
+      });
+
+      await waitFor(() => {
+        expect(mockAddItem).toHaveBeenCalledWith(
+          expect.objectContaining({
+            type: MessageType.ERROR,
+            text: 'Custom malformed function call message',
+          }),
+          expect.any(Number),
+        );
+      });
+    });
  });

  describe('handleApprovalModeChange', () => {
@@ -14,6 +14,7 @@ import {
  GitService,
  UnauthorizedError,
  UserPromptEvent,
+  uiTelemetryService,
  DEFAULT_GEMINI_FLASH_MODEL,
  logConversationFinishedEvent,
  ConversationFinishedEvent,
@@ -45,6 +46,12 @@ import {
  buildToolVisibilityContext,
  UPDATE_TOPIC_TOOL_NAME,
  UPDATE_TOPIC_DISPLAY_NAME,
+  THINKING_ONLY_COMPRESS_SUGGESTION,
+  MAX_TOKENS_EXCEEDED_SUGGESTION,
+  SAFETY_BLOCKED_MESSAGE,
+  RECITATION_BLOCKED_MESSAGE,
+  OTHER_BLOCKED_MESSAGE,
+  TRUE_EMPTY_RESPONSE_MESSAGE,
 } from '@google/gemini-cli-core';
 import type {
  Config,
@@ -54,6 +61,7 @@ import type {
  ServerGeminiContentEvent as ContentEvent,
  ServerGeminiFinishedEvent,
  ServerGeminiStreamEvent as GeminiEvent,
+  ServerGeminiInvalidStreamEvent,
  ThoughtSummary,
  ToolCallRequestInfo,
  ToolCallResponseInfo,
@@ -1229,6 +1237,61 @@ export const useGeminiStream = (
    ],
  );

+  const handleInvalidStreamEvent = useCallback(
+    (
+      eventValue: ServerGeminiInvalidStreamEvent['value'],
+      userMessageTimestamp: number,
+    ) => {
+      if (pendingHistoryItemRef.current) {
+        addItem(pendingHistoryItemRef.current, userMessageTimestamp);
+        setPendingHistoryItem(null);
+      }
+      maybeAddSuppressedToolErrorNote(userMessageTimestamp);
+
+      let text =
+        eventValue?.message?.trim() || 'Invalid stream received from model';
+      if (eventValue?.type === 'NO_RESPONSE_TEXT') {
+        text = TRUE_EMPTY_RESPONSE_MESSAGE;
+      } else if (eventValue?.type === 'THINKING_ONLY_RESPONSE') {
+        text = THINKING_ONLY_COMPRESS_SUGGESTION;
+      } else if (eventValue?.type === 'MAX_TOKENS_EXCEEDED') {
+        text = MAX_TOKENS_EXCEEDED_SUGGESTION;
+      } else if (eventValue?.type === 'SAFETY_BLOCKED') {
+        text = SAFETY_BLOCKED_MESSAGE;
+      } else if (eventValue?.type === 'RECITATION_BLOCKED') {
+        text = RECITATION_BLOCKED_MESSAGE;
+      } else if (eventValue?.type === 'OTHER_BLOCKED') {
+        text = OTHER_BLOCKED_MESSAGE;
+      }
+
+      // Log semantic error telemetry without double-counting requests
+      uiTelemetryService.recordSemanticValidationError(
+        geminiClient.getCurrentSequenceModel() ?? config.getModel(),
+        eventValue?.type || 'INVALID_STREAM',
+      );
+
+      addItem(
+        {
+          type: MessageType.ERROR,
+          text,
+        },
+        userMessageTimestamp,
+      );
+      maybeAddLowVerbosityFailureNote(userMessageTimestamp);
+      setThought(null); // Reset thought when there's an error
+    },
+    [
+      addItem,
+      pendingHistoryItemRef,
+      setPendingHistoryItem,
+      setThought,
+      maybeAddSuppressedToolErrorNote,
+      maybeAddLowVerbosityFailureNote,
+      config,
+      geminiClient,
+    ],
+  );
+
  const handleCitationEvent = useCallback(
    (text: string, userMessageTimestamp: number) => {
      if (!showCitations(settings)) {
@@ -1541,8 +1604,10 @@ export const useGeminiStream = (
            loopDetectedRef.current = true;
            break;
          case ServerGeminiEventType.Retry:
+            // Handled transparently by the backend stream retries.
+            break;
          case ServerGeminiEventType.InvalidStream:
-            // Will add the missing logic later
+            handleInvalidStreamEvent(event.value, userMessageTimestamp);
            break;
          default: {
            // enforces exhaustive switch-case
@@ -1575,6 +1640,7 @@ export const useGeminiStream = (
      handleChatModelEvent,
      handleAgentExecutionStoppedEvent,
      handleAgentExecutionBlockedEvent,
+      handleInvalidStreamEvent,
      addItem,
      pendingHistoryItemRef,
      setPendingHistoryItem,
@@ -1886,6 +1952,30 @@ export const useGeminiStream = (
          },
        );

+      if (turnCancelledRef.current) {
+        setIsResponding(false);
+        const geminiTools = completedAndReadyToSubmitTools.filter(
+          (t) => !t.request.isClientInitiated,
+        );
+        if (geminiClient && geminiTools.length > 0) {
+          const combinedParts = geminiTools.flatMap(
+            (toolCall) => toolCall.response.responseParts,
+          );
+          if (combinedParts.length > 0) {
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            geminiClient.addHistory({
+              role: 'user',
+              parts: combinedParts,
+            });
+          }
+        }
+        const callIdsToMarkAsSubmitted = toolCalls.map(
+          (toolCall) => toolCall.request.callId,
+        );
+        markToolsAsSubmitted(callIdsToMarkAsSubmitted);
+        return;
+      }
+
      // Finalize any client-initiated tools as soon as they are done.
      const clientTools = completedAndReadyToSubmitTools.filter(
        (t) => t.request.isClientInitiated,
@@ -2020,6 +2110,27 @@ export const useGeminiStream = (
        (toolCall) => toolCall.response.responseParts,
      );

+      const callIdsToMarkAsSubmitted = geminiTools.map(
+        (toolCall) => toolCall.request.callId,
+      );
+
+      markToolsAsSubmitted(callIdsToMarkAsSubmitted);
+
+      // Don't continue if model was switched due to quota error, but still
+      // record the responses: the matching functionCall is already in history,
+      // and leaving it unpaired corrupts every subsequent request. Any pending
+      // steering hint is deliberately left unconsumed so it rides along with
+      // the next query the user actually submits.
+      if (modelSwitchedFromQuotaError) {
+        if (geminiClient && responsesToSend.length > 0) {
+          await geminiClient.addHistory({
+            role: 'user',
+            parts: responsesToSend,
+          });
+        }
+        return;
+      }
+
      if (consumeUserHint) {
        const userHint = consumeUserHint();
        if (userHint && userHint.trim().length > 0) {
@@ -2030,21 +2141,10 @@ export const useGeminiStream = (
        }
      }

-      const callIdsToMarkAsSubmitted = geminiTools.map(
-        (toolCall) => toolCall.request.callId,
-      );
-
      const prompt_ids = geminiTools.map(
        (toolCall) => toolCall.request.prompt_id,
      );

-      markToolsAsSubmitted(callIdsToMarkAsSubmitted);
-
-      // Don't continue if model was switched due to quota error
-      if (modelSwitchedFromQuotaError) {
-        return;
-      }
-
      // eslint-disable-next-line @typescript-eslint/no-floating-promises
      submitQuery(
        responsesToSend,
@@ -2066,6 +2166,7 @@ export const useGeminiStream = (
      maybeAddSuppressedToolErrorNote,
      maybeAddLowVerbosityFailureNote,
      setIsResponding,
+      toolCalls,
    ],
  );

@@ -1,10 +1,74 @@
 (version 1)

-;; allow everything by default
-(allow default)
+;; permissive-open: uses (deny default) and explicitly allows the operations the
+;; CLI needs, matching the restrictive-* / strict-* profiles. Keep the allow-list
+;; minimal and reviewed; do not switch to (allow default).
+;;
+;; Keep the non-network rules in sync with sandbox-macos-permissive-proxied.sb:
+;; the two profiles are intentionally identical except for their network rules
+;; ("open" allows broad outbound; "proxied" routes outbound through the proxy).
+(deny default)

-;; deny all writes EXCEPT under specific paths
-(deny file-write*)
+;; allow reading files from anywhere on host
+(allow file-read*)
+
+;; allow exec/fork (children inherit this policy, so they stay sandboxed)
+(allow process-exec)
+(allow process-fork)
+
+;; allow signals to self, e.g. SIGPIPE on write to closed pipe
+(allow signal (target self))
+
+;; allow read access to specific information about system
+;; from https://source.chromium.org/chromium/chromium/src/+/main:sandbox/policy/mac/common.sb;l=273-319;drc=7b3962fe2e5fc9e2ee58000dc8fbf3429d84d3bd
+(allow sysctl-read
+    (sysctl-name "hw.activecpu")
+    (sysctl-name "hw.busfrequency_compat")
+    (sysctl-name "hw.byteorder")
+    (sysctl-name "hw.cacheconfig")
+    (sysctl-name "hw.cachelinesize_compat")
+    (sysctl-name "hw.cpufamily")
+    (sysctl-name "hw.cpufrequency_compat")
+    (sysctl-name "hw.cputype")
+    (sysctl-name "hw.l1dcachesize_compat")
+    (sysctl-name "hw.l1icachesize_compat")
+    (sysctl-name "hw.l2cachesize_compat")
+    (sysctl-name "hw.l3cachesize_compat")
+    (sysctl-name "hw.logicalcpu_max")
+    (sysctl-name "hw.machine")
+    (sysctl-name "hw.ncpu")
+    (sysctl-name "hw.nperflevels")
+    (sysctl-name "hw.optional.arm.FEAT_BF16")
+    (sysctl-name "hw.optional.arm.FEAT_DotProd")
+    (sysctl-name "hw.optional.arm.FEAT_FCMA")
+    (sysctl-name "hw.optional.arm.FEAT_FHM")
+    (sysctl-name "hw.optional.arm.FEAT_FP16")
+    (sysctl-name "hw.optional.arm.FEAT_I8MM")
+    (sysctl-name "hw.optional.arm.FEAT_JSCVT")
+    (sysctl-name "hw.optional.arm.FEAT_LSE")
+    (sysctl-name "hw.optional.arm.FEAT_RDM")
+    (sysctl-name "hw.optional.arm.FEAT_SHA512")
+    (sysctl-name "hw.optional.armv8_2_sha512")
+    (sysctl-name "hw.packages")
+    (sysctl-name "hw.pagesize_compat")
+    (sysctl-name "hw.physicalcpu_max")
+    (sysctl-name "hw.tbfrequency_compat")
+    (sysctl-name "hw.vectorunit")
+    (sysctl-name "kern.hostname")
+    (sysctl-name "kern.maxfilesperproc")
+    (sysctl-name "kern.osproductversion")
+    (sysctl-name "kern.osrelease")
+    (sysctl-name "kern.ostype")
+    (sysctl-name "kern.osvariant_status")
+    (sysctl-name "kern.osversion")
+    (sysctl-name "kern.secure_kernel")
+    (sysctl-name "kern.usrstack64")
+    (sysctl-name "kern.version")
+    (sysctl-name "sysctl.proc_cputype")
+    (sysctl-name-prefix "hw.perflevel")
+)
+
+;; allow writes only to specific paths (deny default already blocks the rest)
 (allow file-write*
    (subpath (param "TARGET_DIR"))
    (subpath (param "TMP_DIR"))
@@ -24,3 +88,48 @@
    (literal "/dev/ptmx")
    (regex #"^/dev/ttys[0-9]*$")
 )
+
+;; allow the mach services normal workflows need under deny-default: sysmond for
+;; process listing (pgrep), plus DNS resolution (mDNSResponder), directory
+;; services (opendirectoryd), and certificate validation (trustd/ocspd).
+;; This set mirrors the deny-default profile in
+;; packages/core/src/sandbox/macos/baseProfile.ts (its NETWORK_SEATBELT_PROFILE),
+;; which restrictive-open reaches only implicitly via (allow network-outbound).
+;; Keep this allow-list minimal and reviewed.
+(allow mach-lookup
+    (global-name "com.apple.sysmond")
+    (global-name "com.apple.system.opendirectoryd.libinfo")
+    (global-name "com.apple.system.opendirectoryd.membership")
+    (global-name "com.apple.bsd.dirhelper")
+    (global-name "com.apple.SecurityServer")
+    (global-name "com.apple.networkd")
+    (global-name "com.apple.ocspd")
+    (global-name "com.apple.trustd")
+    (global-name "com.apple.trustd.agent")
+    (global-name "com.apple.mDNSResponder")
+    (global-name "com.apple.mDNSResponderHelper")
+    (global-name "com.apple.SystemConfiguration.DNSConfiguration")
+    (global-name "com.apple.SystemConfiguration.configd")
+)
+
+;; AF_SYSTEM socket used by the network stack (from baseProfile.ts)
+(allow system-socket
+    (require-all
+        (socket-domain AF_SYSTEM)
+        (socket-protocol 2)
+    )
+)
+
+;; enable terminal access required by ink
+;; fixes setRawMode EPERM failure (at node:tty:81:24)
+(allow file-ioctl (regex #"^/dev/tty.*"))
+
+;; allow inbound network traffic (local dev/test servers, the debugger on :9229,
+;; OAuth localhost callbacks)
+(allow network-inbound (local ip "*:*"))
+
+;; allow binding local ports (dev/test servers, OAuth localhost listeners)
+(allow network-bind (local ip "*:*"))
+
+;; allow all outbound network traffic
+(allow network-outbound)
@@ -1,10 +1,76 @@
 (version 1)

-;; allow everything by default
-(allow default)
+;; permissive-proxied: uses (deny default) and explicitly allows the operations
+;; the CLI needs, matching the restrictive-* / strict-* profiles. Keep the
+;; allow-list minimal and reviewed; do not switch to (allow default).
+;;
+;; Keep the non-network rules in sync with sandbox-macos-permissive-open.sb:
+;; the two profiles are intentionally identical except for their network rules
+;; ("open" allows broad outbound; "proxied" routes outbound through the proxy).
+(deny default)

-;; deny all writes EXCEPT under specific paths
-(deny file-write*)
+;; allow reading files from anywhere on host
+(allow file-read*)
+
+;; allow exec/fork (children inherit this policy, so they stay sandboxed)
+(allow process-exec)
+(allow process-fork)
+
+;; allow signals to self, e.g. SIGPIPE on write to closed pipe
+(allow signal (target self))
+
+;; allow read access to specific information about system
+;; from https://source.chromium.org/chromium/chromium/src/+/main:sandbox/policy/mac/common.sb;l=273-319;drc=7b3962fe2e5fc9e2ee58000dc8fbf3429d84d3bd
+(allow sysctl-read
+    (sysctl-name "hw.activecpu")
+    (sysctl-name "hw.busfrequency_compat")
+    (sysctl-name "hw.byteorder")
+    (sysctl-name "hw.cacheconfig")
+    (sysctl-name "hw.cachelinesize_compat")
+    (sysctl-name "hw.cpufamily")
+    (sysctl-name "hw.cpufrequency_compat")
+    (sysctl-name "hw.cputype")
+    (sysctl-name "hw.l1dcachesize_compat")
+    (sysctl-name "hw.l1icachesize_compat")
+    (sysctl-name "hw.l2cachesize_compat")
+    (sysctl-name "hw.l3cachesize_compat")
+    (sysctl-name "hw.logicalcpu_max")
+    (sysctl-name "hw.machine")
+    (sysctl-name "hw.ncpu")
+    (sysctl-name "hw.nperflevels")
+    (sysctl-name "hw.optional.arm.FEAT_BF16")
+    (sysctl-name "hw.optional.arm.FEAT_DotProd")
+    (sysctl-name "hw.optional.arm.FEAT_FCMA")
+    (sysctl-name "hw.optional.arm.FEAT_FHM")
+    (sysctl-name "hw.optional.arm.FEAT_FP16")
+    (sysctl-name "hw.optional.arm.FEAT_I8MM")
+    (sysctl-name "hw.optional.arm.FEAT_JSCVT")
+    (sysctl-name "hw.optional.arm.FEAT_LSE")
+    (sysctl-name "hw.optional.arm.FEAT_RDM")
+    (sysctl-name "hw.optional.arm.FEAT_SHA512")
+    (sysctl-name "hw.optional.armv8_2_sha512")
+    (sysctl-name "hw.packages")
+    (sysctl-name "hw.pagesize_compat")
+    (sysctl-name "hw.physicalcpu_max")
+    (sysctl-name "hw.tbfrequency_compat")
+    (sysctl-name "hw.vectorunit")
+    (sysctl-name "kern.hostname")
+    (sysctl-name "kern.maxfilesperproc")
+    (sysctl-name "kern.osproductversion")
+    (sysctl-name "kern.osrelease")
+    (sysctl-name "kern.ostype")
+    (sysctl-name "kern.osvariant_status")
+    (sysctl-name "kern.osversion")
+    (sysctl-name "kern.secure_kernel")
+    (sysctl-name "kern.usrstack64")
+    (sysctl-name "kern.version")
+    (sysctl-name "sysctl.proc_cputype")
+    (sysctl-name-prefix "hw.perflevel")
+)
+
+;; allow writes only to specific paths (deny default already blocks the rest).
+;; Mirrors permissive-open, including /dev/ptmx and the /dev/ttys regex needed
+;; for PTY support under deny default.
 (allow file-write*
    (subpath (param "TARGET_DIR"))
    (subpath (param "TMP_DIR"))
@@ -21,16 +87,52 @@
    (literal "/dev/stdout")
    (literal "/dev/stderr")
    (literal "/dev/null")
+    (literal "/dev/ptmx")
+    (regex #"^/dev/ttys[0-9]*$")
 )

-;; deny all inbound network traffic EXCEPT on debugger port
-(deny network-inbound)
+;; allow the mach services normal workflows need under deny-default: sysmond for
+;; process listing (pgrep), plus DNS resolution (mDNSResponder), directory
+;; services (opendirectoryd), and certificate validation (trustd/ocspd).
+;; This set mirrors the deny-default profile in
+;; packages/core/src/sandbox/macos/baseProfile.ts (its NETWORK_SEATBELT_PROFILE),
+;; which restrictive-proxied reaches only implicitly via (allow network-outbound).
+;; Keep this allow-list minimal and reviewed.
+(allow mach-lookup
+    (global-name "com.apple.sysmond")
+    (global-name "com.apple.system.opendirectoryd.libinfo")
+    (global-name "com.apple.system.opendirectoryd.membership")
+    (global-name "com.apple.bsd.dirhelper")
+    (global-name "com.apple.SecurityServer")
+    (global-name "com.apple.networkd")
+    (global-name "com.apple.ocspd")
+    (global-name "com.apple.trustd")
+    (global-name "com.apple.trustd.agent")
+    (global-name "com.apple.mDNSResponder")
+    (global-name "com.apple.mDNSResponderHelper")
+    (global-name "com.apple.SystemConfiguration.DNSConfiguration")
+    (global-name "com.apple.SystemConfiguration.configd")
+)
+
+;; AF_SYSTEM socket used by the network stack (from baseProfile.ts)
+(allow system-socket
+    (require-all
+        (socket-domain AF_SYSTEM)
+        (socket-protocol 2)
+    )
+)
+
+;; enable terminal access required by ink
+;; fixes setRawMode EPERM failure (at node:tty:81:24)
+(allow file-ioctl (regex #"^/dev/tty.*"))
+
+;; allow inbound network traffic on debugger port
 (allow network-inbound (local ip "localhost:9229"))

+;; allow binding local ports (dev/test servers, OAuth localhost listeners)
+(allow network-bind (local ip "*:*"))
+
 ;; deny all outbound network traffic EXCEPT through proxy on localhost:8877
 ;; set `GEMINI_SANDBOX_PROXY_COMMAND=<command>` to run proxy alongside sandbox
 ;; proxy must listen on :::8877 (see docs/examples/proxy-script.md)
-(deny network-outbound)
 (allow network-outbound (remote tcp "localhost:8877"))
-
-(allow network-bind (local ip "*:*"))
@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const utilsDir = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Strip SBPL comments (`; ...` to end of line) so assertions run against the
+ * actual sandbox rules rather than any keywords that happen to appear in the
+ * explanatory comments.
+ */
+function readRules(profile: string): string {
+  return readFileSync(path.join(utilsDir, profile), 'utf8')
+    .split('\n')
+    .map((line) => {
+      const commentStart = line.indexOf(';');
+      return commentStart === -1 ? line : line.slice(0, commentStart);
+    })
+    .join('\n');
+}
+
+const PERMISSIVE_PROFILES = [
+  'sandbox-macos-permissive-open.sb',
+  'sandbox-macos-permissive-proxied.sb',
+];
+
+// These two profiles are the default macOS Seatbelt profiles, so the invariants
+// below must never silently regress. Keep them deny-default and confirm the
+// reviewed allow-list stays in place.
+describe('macOS permissive Seatbelt profiles', () => {
+  describe.each(PERMISSIVE_PROFILES)('%s', (profile) => {
+    const rules = readRules(profile);
+
+    it('uses a deny-default foundation', () => {
+      expect(rules).toContain('(deny default)');
+    });
+
+    it('does not use an allow-default foundation', () => {
+      expect(rules).not.toContain('(allow default)');
+    });
+
+    it('does not permit filesystem (un)mounts', () => {
+      expect(rules).not.toMatch(/file-mount/);
+      expect(rules).not.toMatch(/file-unmount/);
+    });
+
+    it('does not grant broad service lookups', () => {
+      expect(rules).not.toMatch(/launchd/);
+      expect(rules).not.toMatch(/launchservices/i);
+    });
+
+    it('allows binding local ports for dev/test servers', () => {
+      expect(rules).toContain('(allow network-bind (local ip "*:*"))');
+    });
+  });
+
+  it('permissive-open keeps broad inbound and outbound network', () => {
+    const rules = readRules('sandbox-macos-permissive-open.sb');
+    expect(rules).toContain('(allow network-inbound (local ip "*:*"))');
+    expect(rules).toMatch(/\(allow network-outbound\)/);
+  });
+
+  it('permissive-proxied confines outbound to the proxy', () => {
+    const rules = readRules('sandbox-macos-permissive-proxied.sb');
+    expect(rules).toContain(
+      '(allow network-outbound (remote tcp "localhost:8877"))',
+    );
+    // Proxied mode must never grant unrestricted outbound network.
+    expect(rules).not.toMatch(/\(allow network-outbound\)/);
+  });
+});
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli-core",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "description": "Gemini CLI Core",
  "license": "Apache-2.0",
  "repository": {
@@ -516,10 +516,34 @@ describe('translateEvent', () => {
  });

  describe('InvalidStream events', () => {
-    it('emits fatal error', () => {
+    it('emits fatal error with specific message from event', () => {
      state.streamStartEmitted = true;
      const event: ServerGeminiStreamEvent = {
        type: GeminiEventType.InvalidStream,
+        value: {
+          type: 'NO_RESPONSE_TEXT',
+          message: 'Empty response',
+        },
+      };
+      const result = translateEvent(event, state);
+      expect(result).toHaveLength(1);
+      const err = result[0] as AgentEvent<'error'>;
+      expect(err.status).toBe('INTERNAL');
+      expect(err.message).toBe('Empty response');
+      expect(err.fatal).toBe(true);
+      expect(err._meta?.['code']).toBe('INVALID_STREAM');
+      expect(err._meta?.['errorType']).toBe('NO_RESPONSE_TEXT');
+      expect(err._meta?.['rawMessage']).toBe('Empty response');
+    });
+
+    it('falls back to default message when message is missing', () => {
+      state.streamStartEmitted = true;
+      const event: ServerGeminiStreamEvent = {
+        type: GeminiEventType.InvalidStream,
+        value: {
+          type: 'NO_RESPONSE_TEXT',
+          message: '',
+        },
      };
      const result = translateEvent(event, state);
      expect(result).toHaveLength(1);
@@ -222,8 +222,15 @@ export function translateEvent(
      out.push(
        makeEvent('error', state, {
          status: 'INTERNAL',
-          message: 'Invalid stream received from model',
+          message:
+            event.value?.message?.trim() ||
+            'Invalid stream received from model',
          fatal: true,
+          _meta: {
+            code: 'INVALID_STREAM',
+            errorType: event.value?.type,
+            rawMessage: event.value?.message,
+          },
        }),
      );
      break;
@@ -10,7 +10,7 @@
 */

 import { GeminiEventType } from '../core/turn.js';
-import type { Part } from '@google/genai';
+import type { Part, FinishReason } from '@google/genai';
 import type { GeminiClient } from '../core/client.js';
 import type { Config } from '../config/config.js';
 import type { ToolCallRequestInfo } from '../scheduler/types.js';
@@ -192,6 +192,7 @@ export class LegacyAgentProtocol implements AgentProtocol {
      }

      const toolCallRequests: ToolCallRequestInfo[] = [];
+      let finishedReason: FinishReason | undefined = undefined;
      const responseStream = this._client.sendMessageStream(
        currentParts,
        this._abortController.signal,
@@ -220,10 +221,7 @@ export class LegacyAgentProtocol implements AgentProtocol {
            this._finishStream('failed');
            return;
          case GeminiEventType.Finished:
-            if (toolCallRequests.length === 0) {
-              this._finishStream(mapFinishReason(event.value.reason));
-              return;
-            }
+            finishedReason = event.value.reason;
            break;
          case GeminiEventType.AgentExecutionStopped:
          case GeminiEventType.UserCancelled:
@@ -241,7 +239,11 @@ export class LegacyAgentProtocol implements AgentProtocol {
      }

      if (toolCallRequests.length === 0) {
-        this._finishStream('completed');
+        if (finishedReason !== undefined) {
+          this._finishStream(mapFinishReason(finishedReason));
+        } else {
+          this._finishStream('completed');
+        }
        return;
      }

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { GoogleCredentialsAuthProvider } from './google-credentials-provider.js';
+import type { GoogleCredentialsAuthConfig } from './types.js';
+import { GoogleAuth } from 'google-auth-library';
+
+vi.mock('google-auth-library', () => ({
+  GoogleAuth: vi.fn(),
+}));
+
+describe('Credential Leak Prevention (RCA / PoC Verification)', () => {
+  const mockConfig: GoogleCredentialsAuthConfig = {
+    type: 'google-credentials',
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (GoogleAuth as unknown as Mock).mockImplementation(() => ({
+      getClient: vi.fn().mockResolvedValue({
+        getAccessToken: vi.fn().mockResolvedValue({ token: 'leaked-token' }),
+        credentials: { expiry_date: Date.now() + 3600 * 1000 },
+      }),
+      getIdTokenClient: vi.fn().mockResolvedValue({
+        idTokenProvider: {
+          fetchIdToken: vi.fn().mockResolvedValue('leaked-id-token'),
+        },
+      }),
+    }));
+  });
+
+  it('should FAIL (throw error) when trying to initialize with an untrusted arbitrary remote agent URL (reproducing vulnerability prevention)', () => {
+    // This test simulates the reproduction scenario: registering a remote agent with an arbitrary external URL
+    // e.g., http://127.0.0.1:1337 or https://malicious-agent.evil.com
+    const untrustedUrls = [
+      {
+        url: 'http://127.0.0.1:1337/.well-known/agent.json',
+        error: /requires HTTPS/,
+      },
+      {
+        url: 'https://malicious-agent.evil.com/card',
+        error: /is not an allowed host/,
+      },
+      {
+        url: 'https://untrusted-third-party.com/agent',
+        error: /is not an allowed host/,
+      },
+    ];
+
+    for (const item of untrustedUrls) {
+      expect(() => {
+        new GoogleCredentialsAuthProvider(mockConfig, item.url);
+      }).toThrow(item.error);
+    }
+  });
+
+  it('should SUCCEED only for allowed Google Services (proving the allowlist constraint)', () => {
+    const trustedUrls = [
+      'https://language.googleapis.com/v1/models',
+      'https://vertex-ai-agent.googleapis.com/agent',
+      'https://my-secure-service-abc.run.app/card',
+    ];
+
+    for (const url of trustedUrls) {
+      expect(() => {
+        new GoogleCredentialsAuthProvider(mockConfig, url);
+      }).not.toThrow();
+    }
+  });
+});
@@ -82,6 +82,24 @@ describe('GoogleCredentialsAuthProvider', () => {
          ),
      ).not.toThrow();
    });
+
+    it('throws if the protocol is not HTTPS', () => {
+      expect(
+        () =>
+          new GoogleCredentialsAuthProvider(
+            mockConfig,
+            'http://language.googleapis.com/v1/models',
+          ),
+      ).toThrow(/requires HTTPS/);
+
+      expect(
+        () =>
+          new GoogleCredentialsAuthProvider(
+            mockConfig,
+            'http://my-cloud-run-service.run.app',
+          ),
+      ).toThrow(/requires HTTPS/);
+    });
  });

  describe('Token Fetching', () => {
@@ -40,7 +40,14 @@ export class GoogleCredentialsAuthProvider extends BaseA2AAuthProvider {
      );
    }

-    const hostname = new URL(targetUrl).hostname;
+    const urlObj = new URL(targetUrl);
+    if (urlObj.protocol !== 'https:') {
+      throw new Error(
+        `Protocol "${urlObj.protocol}" is not secure. Google Credential provider requires HTTPS.`,
+      );
+    }
+
+    const hostname = urlObj.hostname;
    const isRunAppHost = CLOUD_RUN_HOST_REGEX.test(hostname);

    if (isRunAppHost) {
@@ -414,4 +414,86 @@ describe('Auto Routing Fallback Integration', () => {
      'Pro success',
    );
  });
+
+  it('should rotate session ID on fallback and retry successfully with the Flash model', async () => {
+    const originalSessionId = 'test-session-rotate-id';
+    config = new Config({
+      sessionId: originalSessionId,
+      targetDir: '/test',
+      debugMode: false,
+      cwd: '/test',
+      model: PREVIEW_GEMINI_MODEL_AUTO,
+    });
+
+    vi.spyOn(config, 'isInteractive').mockReturnValue(true);
+
+    client = new BaseLlmClient(
+      fakeGenerator,
+      config,
+      AuthType.LOGIN_WITH_GOOGLE,
+    );
+
+    let attemptsPro = 0;
+    let attemptsFlash = 0;
+
+    const mockGoogleApiError = {
+      code: 429,
+      message:
+        'Automatically switching from gemini-2.5-pro to gemini-2.5-flash for faster responses for the remainder of this session. Possible reasons for this are...',
+      details: [],
+    };
+
+    vi.spyOn(fakeGenerator, 'generateContent').mockImplementation(
+      async (params) => {
+        if (params.model === PREVIEW_GEMINI_MODEL) {
+          attemptsPro++;
+          throw new RetryableQuotaError(
+            'Quota exceeded for Pro',
+            mockGoogleApiError,
+            0,
+          );
+        } else if (params.model === PREVIEW_GEMINI_FLASH_MODEL) {
+          attemptsFlash++;
+          return {
+            candidates: [
+              {
+                content: {
+                  role: 'model',
+                  parts: [{ text: 'Flash success after rotation' }],
+                },
+              },
+            ],
+          } as unknown as GenerateContentResponse;
+        }
+        throw new Error(`Unexpected model: ${params.model}`);
+      },
+    );
+
+    config.setFallbackModelHandler(
+      async (_failed, _fallback, _error): Promise<FallbackIntent | null> =>
+        'retry_always', // Approve switch to Flash
+    );
+
+    const promise = client.generateContent({
+      modelConfigKey: { model: PREVIEW_GEMINI_MODEL, isChatModel: true },
+      contents: [{ role: 'user', parts: [{ text: 'test query' }] }],
+      abortSignal: new AbortController().signal,
+      promptId: 'test-prompt',
+      role: LlmRole.UTILITY_TOOL,
+    });
+
+    await vi.runAllTimersAsync();
+    const result = await promise;
+
+    // Verify it resolved to Flash success instead of failing with Please submit a new query
+    expect(result.candidates?.[0]?.content?.parts?.[0]?.text).toBe(
+      'Flash success after rotation',
+    );
+    expect(attemptsPro).toBe(3);
+    expect(attemptsFlash).toBe(1);
+
+    // Verify session ID has been rotated
+    expect(config.getSessionId()).not.toBe(originalSessionId);
+    expect(config.getSessionId()).toBeDefined();
+  });
 });
@@ -680,6 +680,64 @@ describe('oauth2', () => {
        expect(mockFromJSON).toHaveBeenCalledWith(byoidCredentials);
        expect(client).toBe(mockExternalAccountClient);
      });
+
+      it('should fall back to GOOGLE_APPLICATION_CREDENTIALS if default cached credentials are invalid or expired', async () => {
+        // Setup default cached credentials that are expired/invalid
+        const defaultCreds = { refresh_token: 'expired-token' };
+        const defaultCredsPath = path.join(
+          tempHomeDir,
+          GEMINI_DIR,
+          'oauth_creds.json',
+        );
+        await fs.promises.mkdir(path.dirname(defaultCredsPath), {
+          recursive: true,
+        });
+        await fs.promises.writeFile(
+          defaultCredsPath,
+          JSON.stringify(defaultCreds),
+        );
+
+        // Setup valid fallback credentials via environment variable
+        const envCreds = { refresh_token: 'valid-env-token' };
+        const envCredsPath = path.join(tempHomeDir, 'env_creds.json');
+        await fs.promises.writeFile(envCredsPath, JSON.stringify(envCreds));
+        vi.stubEnv('GOOGLE_APPLICATION_CREDENTIALS', envCredsPath);
+
+        let currentCredentials: Credentials | null = null;
+        const mockClient = {
+          setCredentials: vi.fn((creds) => {
+            currentCredentials = creds as Credentials;
+          }),
+          getAccessToken: vi.fn(async () => {
+            if (
+              currentCredentials &&
+              currentCredentials.refresh_token === 'expired-token'
+            ) {
+              throw new Error('Token is expired or revoked');
+            }
+            return { token: 'valid-token' };
+          }),
+          getTokenInfo: vi.fn(async (_token) => {
+            if (
+              currentCredentials &&
+              currentCredentials.refresh_token === 'expired-token'
+            ) {
+              throw new Error('Token is expired or revoked');
+            }
+            return {};
+          }),
+          on: vi.fn(),
+        };
+
+        vi.mocked(OAuth2Client).mockImplementation(
+          () => mockClient as unknown as OAuth2Client,
+        );
+
+        await getOauthClient(AuthType.LOGIN_WITH_GOOGLE, mockConfig);
+
+        // Assert that fallback envCreds were eventually loaded and used
+        expect(mockClient.setCredentials).toHaveBeenCalledWith(envCreds);
+      });
    });

    describe('with GCP environment variables', () => {
@@ -113,46 +113,52 @@ function getUseEncryptedStorageFlag() {
  return process.env[FORCE_ENCRYPTED_FILE_ENV_VAR] === 'true';
 }

+/**
+ * Determines whether the given credentials object represents ADC credentials.
+ */
+function isAdcCredentials(
+  credentials: unknown,
+): credentials is JWTInput & { type: string } {
+  if (credentials && typeof credentials === 'object' && 'type' in credentials) {
+    const type = credentials.type;
+    return typeof type === 'string' && type !== 'authorized_user';
+  }
+  return false;
+}
+
 async function initOauthClient(
  authType: AuthType,
  config: Config,
 ): Promise<AuthClient> {
-  const credentials = await fetchCachedCredentials();
+  function createBaseOAuth2Client(): OAuth2Client {
+    const client = new OAuth2Client({
+      clientId: OAUTH_CLIENT_ID,
+      clientSecret: OAUTH_CLIENT_SECRET,
+      transporterOptions: {
+        proxy: config.getProxy(),
+      },
+    });
+    const useEncryptedStorage = getUseEncryptedStorageFlag();

-  if (
-    credentials &&
-    typeof credentials === 'object' &&
-    'type' in credentials &&
-    (credentials.type === 'external_account_authorized_user' ||
-      credentials.type === 'service_account')
-  ) {
-    const auth = new GoogleAuth({
-      scopes: OAUTH_SCOPE,
+    client.on('tokens', async (tokens: Credentials) => {
+      if (useEncryptedStorage) {
+        await OAuthCredentialStorage.saveCredentials(tokens);
+      } else {
+        await cacheCredentials(tokens);
+      }
+
+      await triggerPostAuthCallbacks(tokens);
    });
-    const byoidClient = auth.fromJSON({
-      ...credentials,
-      refresh_token: credentials.refresh_token ?? undefined,
-    });
-    const token = await byoidClient.getAccessToken();
-    if (token) {
-      debugLogger.debug(`Created ${credentials.type} auth client.`);
-      return byoidClient;
-    }
+
+    return client;
  }

-  const client = new OAuth2Client({
-    clientId: OAUTH_CLIENT_ID,
-    clientSecret: OAUTH_CLIENT_SECRET,
-    transporterOptions: {
-      proxy: config.getProxy(),
-    },
-  });
-  const useEncryptedStorage = getUseEncryptedStorageFlag();
-
+  // 1. Try GOOGLE_CLOUD_ACCESS_TOKEN override first if configured
  if (
    process.env['GOOGLE_GENAI_USE_GCA'] &&
    process.env['GOOGLE_CLOUD_ACCESS_TOKEN']
  ) {
+    const client = createBaseOAuth2Client();
    client.setCredentials({
      access_token: process.env['GOOGLE_CLOUD_ACCESS_TOKEN'],
    });
@@ -160,49 +166,70 @@ async function initOauthClient(
    return client;
  }

-  client.on('tokens', async (tokens: Credentials) => {
-    if (useEncryptedStorage) {
-      await OAuthCredentialStorage.saveCredentials(tokens);
-    } else {
-      await cacheCredentials(tokens);
-    }
+  const credentialsList = await fetchCachedCredentialsList();

-    await triggerPostAuthCallbacks(tokens);
-  });
-
-  if (credentials) {
-    client.setCredentials(credentials as Credentials);
-    try {
-      // This will verify locally that the credentials look good.
-      const { token } = await client.getAccessToken();
-      if (token) {
-        // This will check with the server to see if it hasn't been revoked.
-        await client.getTokenInfo(token);
-
-        if (!userAccountManager.getCachedGoogleAccount()) {
-          try {
-            await fetchAndCacheUserInfo(client);
-          } catch (error) {
-            // Non-fatal, continue with existing auth.
-            debugLogger.warn(
-              'Failed to fetch user info:',
-              getErrorMessage(error),
-            );
-          }
+  // 2. Iterate sequentially over the credentials list in their natural priority order
+  for (const credentials of credentialsList) {
+    if (isAdcCredentials(credentials)) {
+      try {
+        const auth = new GoogleAuth({
+          scopes: OAUTH_SCOPE,
+        });
+        const adcClient = auth.fromJSON({
+          ...credentials,
+          refresh_token: credentials.refresh_token ?? undefined,
+        });
+        const response = await adcClient.getAccessToken();
+        const token = response.token ?? null;
+        if (token) {
+          debugLogger.debug('Created ' + credentials.type + ' auth client.');
+          return adcClient;
        }
-        debugLogger.log('Loaded cached credentials.');
-        await triggerPostAuthCallbacks(credentials as Credentials);
-
-        return client;
+      } catch (error) {
+        debugLogger.debug(
+          'ADC credentials verification failed:',
+          getErrorMessage(error),
+        );
+      }
+    } else if (credentials) {
+      const client = createBaseOAuth2Client();
+      client.setCredentials(credentials as Credentials);
+      try {
+        // This will verify locally that the credentials look good.
+        const { token } = await client.getAccessToken();
+        if (token) {
+          // This will check with the server to see if it hasn't been revoked.
+          await client.getTokenInfo(token);
+
+          if (!userAccountManager.getCachedGoogleAccount()) {
+            try {
+              await fetchAndCacheUserInfo(client);
+            } catch (error) {
+              // Non-fatal, continue with existing auth.
+              debugLogger.warn(
+                'Failed to fetch user info:',
+                getErrorMessage(error),
+              );
+            }
+          }
+          debugLogger.log('Loaded cached credentials.');
+          await triggerPostAuthCallbacks(
+            client.credentials || (credentials as Credentials),
+          );
+
+          return client;
+        }
+      } catch (error) {
+        debugLogger.debug(
+          'Cached credentials are not valid:',
+          getErrorMessage(error),
+        );
      }
-    } catch (error) {
-      debugLogger.debug(
-        `Cached credentials are not valid:`,
-        getErrorMessage(error),
-      );
    }
  }

+  const client = createBaseOAuth2Client();
+
  // In Google Compute Engine based environments (including Cloud Shell), we can
  // use Application Default Credentials (ADC) provided via its metadata server
  // to authenticate non-interactively using the identity of the logged-in user.
@@ -663,16 +690,27 @@ export function getAvailablePort(): Promise<number> {
  });
 }

-async function fetchCachedCredentials(): Promise<
-  Credentials | JWTInput | null
+async function fetchCachedCredentialsList(): Promise<
+  Array<Credentials | JWTInput>
 > {
+  const credentialsList: Array<Credentials | JWTInput> = [];
  const useEncryptedStorage = getUseEncryptedStorageFlag();
  if (useEncryptedStorage) {
-    return OAuthCredentialStorage.loadCredentials();
+    try {
+      const creds = await OAuthCredentialStorage.loadCredentials();
+      if (creds) {
+        credentialsList.push(creds);
+      }
+    } catch (error) {
+      debugLogger.debug(
+        'Failed to load credentials from encrypted storage:',
+        error,
+      );
+    }
  }

  const pathsToTry = [
-    Storage.getOAuthCredsPath(),
+    ...(!useEncryptedStorage ? [Storage.getOAuthCredsPath()] : []),
    process.env['GOOGLE_APPLICATION_CREDENTIALS'],
  ].filter((p): p is string => !!p);

@@ -683,9 +721,10 @@ async function fetchCachedCredentials(): Promise<
      const isOAuthCreds = (val: unknown): val is Credentials | JWTInput =>
        typeof val === 'object' && val !== null;
      if (isOAuthCreds(parsed)) {
-        return parsed;
+        credentialsList.push(parsed);
+      } else {
+        throw new Error('Invalid credentials format');
      }
-      throw new Error('Invalid credentials format');
    } catch (error) {
      // Log specific error for debugging, but continue trying other paths
      debugLogger.debug(
@@ -695,7 +734,7 @@ async function fetchCachedCredentials(): Promise<
    }
  }

-  return null;
+  return credentialsList;
 }

 export function clearOauthClientCache() {
@@ -86,6 +86,10 @@ export class CodeAssistServer implements ContentGenerator {
    readonly config?: Config,
  ) {}

+  getEffectiveSessionId(): string | undefined {
+    return this.config?.getSessionId() ?? this.sessionId;
+  }
+
  async generateContentStream(
    req: GenerateContentParameters,
    userPromptId: string,
@@ -117,7 +121,7 @@ export class CodeAssistServer implements ContentGenerator {
          req,
          userPromptId,
          this.projectId,
-          this.sessionId,
+          this.getEffectiveSessionId(),
          enabledCreditTypes,
        ),
        req.config?.abortSignal,
@@ -153,7 +157,7 @@ export class CodeAssistServer implements ContentGenerator {
          translatedResponse,
          streamingLatency,
          req.config?.abortSignal,
-          server.sessionId, // Use sessionId as trajectoryId
+          server.getEffectiveSessionId(), // Use sessionId as trajectoryId
        );

        if (response.consumedCredits) {
@@ -204,7 +208,7 @@ export class CodeAssistServer implements ContentGenerator {
        req,
        userPromptId,
        this.projectId,
-        this.sessionId,
+        this.getEffectiveSessionId(),
        undefined,
      ),
      req.config?.abortSignal,
@@ -224,7 +228,7 @@ export class CodeAssistServer implements ContentGenerator {
      translatedResponse,
      streamingLatency,
      req.config?.abortSignal,
-      this.sessionId, // Use sessionId as trajectoryId
+      this.getEffectiveSessionId(), // Use sessionId as trajectoryId
    );

    if (response.remainingCredits) {
@@ -678,6 +678,7 @@ export interface ConfigParameters {
  truncateToolOutputThreshold?: number;
  eventEmitter?: EventEmitter;
  useWriteTodos?: boolean;
+  env?: Record<string, string>;
  workspacePoliciesDir?: string;
  policyEngineConfig?: PolicyEngineConfig;
  directWebFetch?: boolean;
@@ -896,6 +897,7 @@ export class Config implements McpContext, AgentLoopContext {
  private readonly useTerminalBuffer: boolean;
  private readonly useRenderProcess: boolean;
  private shellExecutionConfig: ShellExecutionConfig;
+  readonly env?: Record<string, string>;
  private readonly extensionManagement: boolean = true;
  private readonly extensionRegistryURI: string | undefined;
  private readonly truncateToolOutputThreshold: number;
@@ -1119,6 +1121,7 @@ export class Config implements McpContext, AgentLoopContext {
    this.checkpointing = params.checkpointing ?? false;
    this.proxy = params.proxy;
    this.cwd = params.cwd ?? process.cwd();
+    this.env = params.env;
    this.fileDiscoveryService = params.fileDiscoveryService ?? null;
    this.bugCommand = params.bugCommand;
    this.model = params.model;
@@ -1858,6 +1861,10 @@ export class Config implements McpContext, AgentLoopContext {
    }
  }

+  rotateSessionId(sessionId: string): void {
+    this._sessionId = sessionId;
+  }
+
  resetNewSessionState(sessionId: string): void {
    this.setSessionId(sessionId);
  }
@@ -165,6 +165,16 @@ ONLY use the built-in \`exit_plan_mode\` tool to present the plan for formal app
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -361,6 +371,16 @@ An approved plan is available for this task at \`../plans/feature-x.md\`.
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -671,6 +691,16 @@ ONLY use the built-in \`exit_plan_mode\` tool to present the plan for formal app
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -845,6 +875,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -1005,6 +1045,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -1148,6 +1198,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -1837,6 +1897,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -2011,6 +2081,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -2189,6 +2269,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -2367,6 +2457,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -2541,6 +2641,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -2709,6 +2819,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -2851,6 +2971,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -3025,6 +3155,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -3345,6 +3485,16 @@ You are operating with a persistent file-based task tracking system located at \
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -3774,6 +3924,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -3948,6 +4108,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -4241,6 +4411,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -4415,6 +4595,16 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. \`replace\`, \`write_file\`), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the \`replace\` tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the \`run_shell_command\` tool for running shell commands, remembering the safety rule to explain modifying commands first.
@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { AgentChatHistory, type HistoryTurn } from './agentChatHistory.js';
+
+describe('AgentChatHistory', () => {
+  const dummyTurns: HistoryTurn[] = [
+    {
+      id: 'turn-1',
+      content: { role: 'user', parts: [{ text: 'Hello' }] },
+    },
+    {
+      id: 'turn-2',
+      content: { role: 'model', parts: [{ text: 'Hi there' }] },
+    },
+    {
+      id: 'turn-3',
+      content: { role: 'user', parts: [{ text: 'How are you?' }] },
+    },
+  ];
+
+  it('should initialize with empty history by default', () => {
+    const history = new AgentChatHistory();
+    expect(history.length).toBe(0);
+    expect(history.get()).toEqual([]);
+  });
+
+  it('should initialize with provided turns', () => {
+    const history = new AgentChatHistory(dummyTurns);
+    expect(history.length).toBe(3);
+    expect(history.get()).toEqual(dummyTurns);
+  });
+
+  it('should push new turns', () => {
+    const history = new AgentChatHistory();
+    history.push(dummyTurns[0]);
+    expect(history.length).toBe(1);
+    expect(history.get()[0]).toEqual(dummyTurns[0]);
+  });
+
+  it('should set and overwrite history turns', () => {
+    const history = new AgentChatHistory(dummyTurns.slice(0, 1));
+    expect(history.length).toBe(1);
+    history.set(dummyTurns);
+    expect(history.length).toBe(3);
+    expect(history.get()).toEqual(dummyTurns);
+  });
+
+  it('should clear history', () => {
+    const history = new AgentChatHistory(dummyTurns);
+    expect(history.length).toBe(3);
+    history.clear();
+    expect(history.length).toBe(0);
+    expect(history.get()).toEqual([]);
+  });
+
+  describe('rollback', () => {
+    it('should roll back history to a specified length', () => {
+      const history = new AgentChatHistory(dummyTurns);
+      history.rollback(1);
+      expect(history.length).toBe(1);
+      expect(history.get()).toEqual([dummyTurns[0]]);
+    });
+
+    it('should roll back to 0', () => {
+      const history = new AgentChatHistory(dummyTurns);
+      history.rollback(0);
+      expect(history.length).toBe(0);
+      expect(history.get()).toEqual([]);
+    });
+
+    it('should do nothing if rollback length is out of bounds (negative)', () => {
+      const history = new AgentChatHistory(dummyTurns);
+      history.rollback(-1);
+      expect(history.length).toBe(3);
+      expect(history.get()).toEqual(dummyTurns);
+    });
+
+    it('should do nothing if rollback length is out of bounds (greater than current history length)', () => {
+      const history = new AgentChatHistory(dummyTurns);
+      history.rollback(5);
+      expect(history.length).toBe(3);
+      expect(history.get()).toEqual(dummyTurns);
+    });
+  });
+
+  it('should return raw Content array via getContents()', () => {
+    const history = new AgentChatHistory(dummyTurns);
+    expect(history.getContents()).toEqual(
+      dummyTurns.map((turn) => turn.content),
+    );
+  });
+
+  it('should support mapping and flatMapping operations', () => {
+    const history = new AgentChatHistory(dummyTurns);
+    const mappedIds = history.map((turn) => turn.id);
+    expect(mappedIds).toEqual(['turn-1', 'turn-2', 'turn-3']);
+
+    const flatMappedParts = history.flatMap((turn) => turn.content.parts || []);
+    expect(flatMappedParts).toEqual([
+      { text: 'Hello' },
+      { text: 'Hi there' },
+      { text: 'How are you?' },
+    ]);
+  });
+});
@@ -46,6 +46,16 @@ export class AgentChatHistory {
    this.history = [];
  }

+  /**
+   * Rolls back the history to a specified length.
+   * Useful when a stream fails and we need to remove the un-responded turn(s).
+   */
+  rollback(length: number) {
+    if (length >= 0 && length <= this.history.length) {
+      this.history = this.history.slice(0, length);
+    }
+  }
+
  get(): readonly HistoryTurn[] {
    return this.history;
  }
@@ -212,7 +212,7 @@ describe('Gemini Client (client.ts)', () => {
        .fn()
        .mockReturnValue(contentGeneratorConfig),
      getToolRegistry: vi.fn().mockReturnValue(mockToolRegistry),
-      getModel: vi.fn().mockReturnValue('test-model'),
+      getModel: vi.fn().mockReturnValue('gemini-1.5-pro'),
      getUserTier: vi.fn().mockReturnValue(undefined),
      getEmbeddingModel: vi.fn().mockReturnValue('test-embedding-model'),
      getApiKey: vi.fn().mockReturnValue('test-key'),
@@ -154,6 +154,13 @@ export async function createContentGeneratorConfig(
    vertexAiRouting,
  };

+  const getEnv = (key: string) => {
+    if (config?.env && config.env[key] !== undefined) {
+      return config.env[key];
+    }
+    return process.env[key];
+  };
+
  // If we are using Google auth or we are in Cloud Shell, there is nothing else to validate for now.
  // Return before touching the API-key keychain: on Linux without a Secret Service
  // (WSL/SSH/Docker/CI) keytar can block indefinitely on its functional probe.
@@ -165,16 +172,13 @@ export async function createContentGeneratorConfig(
  }

  const geminiApiKey =
-    apiKey ||
-    process.env['GEMINI_API_KEY'] ||
-    (await loadApiKey()) ||
-    undefined;
-  const googleApiKey = process.env['GOOGLE_API_KEY'] || undefined;
+    apiKey || getEnv('GEMINI_API_KEY') || (await loadApiKey()) || undefined;
+  const googleApiKey = getEnv('GOOGLE_API_KEY') || undefined;
  const googleCloudProject =
-    process.env['GOOGLE_CLOUD_PROJECT'] ||
-    process.env['GOOGLE_CLOUD_PROJECT_ID'] ||
+    getEnv('GOOGLE_CLOUD_PROJECT') ||
+    getEnv('GOOGLE_CLOUD_PROJECT_ID') ||
    undefined;
-  const googleCloudLocation = process.env['GOOGLE_CLOUD_LOCATION'] || undefined;
+  const googleCloudLocation = getEnv('GOOGLE_CLOUD_LOCATION') || undefined;

  if (authType === AuthType.USE_GEMINI && geminiApiKey) {
    contentGeneratorConfig.apiKey = geminiApiKey;
@@ -194,8 +198,7 @@ export async function createContentGeneratorConfig(
  }

  if (authType === AuthType.GATEWAY) {
-    contentGeneratorConfig.apiKey =
-      apiKey || process.env['GEMINI_API_KEY'] || '';
+    contentGeneratorConfig.apiKey = apiKey || getEnv('GEMINI_API_KEY') || '';
    contentGeneratorConfig.vertexai = false;

    return contentGeneratorConfig;
@@ -30,7 +30,11 @@ import {
  getRetryErrorType,
 } from '../utils/retry.js';
 import type { ValidationRequiredError } from '../utils/googleQuotaErrors.js';
-import { resolveModel, supportsModernFeatures } from '../config/models.js';
+import {
+  resolveModel,
+  supportsModernFeatures,
+  isGemini2Model,
+} from '../config/models.js';
 import { hasCycleInSchema } from '../tools/tools.js';
 import type { StructuredError } from './turn.js';
 import type { CompletedToolCall } from '../scheduler/types.js';
@@ -104,6 +108,13 @@ const MID_STREAM_RETRY_OPTIONS: MidStreamRetryOptions = {

 export const SYNTHETIC_THOUGHT_SIGNATURE = 'skip_thought_signature_validator';

+/**
+ * Stands in for a model turn that never arrived because the stream failed
+ * after a tool response was already committed to history.
+ */
+export const INTERRUPTED_RESPONSE_PLACEHOLDER =
+  '[The previous response was interrupted before it completed.]';
+
 /**
 * Internal interface for parts that carry the magic 'callIndex' property
 * used during model response consolidation.
@@ -221,7 +232,12 @@ export class InvalidStreamError extends Error {
    | 'NO_FINISH_REASON'
    | 'NO_RESPONSE_TEXT'
    | 'MALFORMED_FUNCTION_CALL'
-    | 'UNEXPECTED_TOOL_CALL';
+    | 'UNEXPECTED_TOOL_CALL'
+    | 'MAX_TOKENS_EXCEEDED'
+    | 'SAFETY_BLOCKED'
+    | 'RECITATION_BLOCKED'
+    | 'OTHER_BLOCKED'
+    | 'THINKING_ONLY_RESPONSE';

  constructor(
    message: string,
@@ -229,7 +245,12 @@ export class InvalidStreamError extends Error {
      | 'NO_FINISH_REASON'
      | 'NO_RESPONSE_TEXT'
      | 'MALFORMED_FUNCTION_CALL'
-      | 'UNEXPECTED_TOOL_CALL',
+      | 'UNEXPECTED_TOOL_CALL'
+      | 'MAX_TOKENS_EXCEEDED'
+      | 'SAFETY_BLOCKED'
+      | 'RECITATION_BLOCKED'
+      | 'OTHER_BLOCKED'
+      | 'THINKING_ONLY_RESPONSE',
  ) {
    super(message);
    this.name = 'InvalidStreamError';
@@ -383,6 +404,9 @@ export class GeminiChat {
  ): Promise<AsyncGenerator<StreamEvent>> {
    await this.sendPromise;

+    const historyLengthBefore = this.agentHistory.length;
+    const baselinePromptTokenCount = this.lastPromptTokenCount;
+
    let streamDoneResolver: () => void;
    const streamDonePromise = new Promise<void>((resolve) => {
      streamDoneResolver = resolve;
@@ -390,6 +414,17 @@ export class GeminiChat {
    this.sendPromise = streamDonePromise;

    let userContent = createUserContent(message);
+    const isOriginalFunctionResponse = isFunctionResponse(userContent);
+
+    // A turn can end leaving history on an unanswered tool response: a stream
+    // error after the response was committed, or a cancelled tool call. Close
+    // it before recording a genuinely new user message, otherwise the two user
+    // turns are coalesced into one and the model continues the trailing text
+    // instead of answering it.
+    if (!isOriginalFunctionResponse) {
+      this.closeUnansweredToolResponseTurn();
+    }
+
    const { model } =
      this.context.config.modelConfigService.getResolvedConfig(modelConfigKey);

@@ -398,7 +433,7 @@ export class GeminiChat {

    // Record user input - capture complete message with all parts (text, files, images, etc.)
    // but skip recording function responses (tool call results) as they should be stored in tool call records
-    if (!isFunctionResponse(userContent)) {
+    if (!isOriginalFunctionResponse) {
      const userMessageParts = userContent.parts || [];
      const userMessageContent = partListUnionToString(userMessageParts);

@@ -515,6 +550,7 @@ export class GeminiChat {
    ): AsyncGenerator<StreamEvent, void, void> {
      try {
        const maxAttempts = this.context.config.getMaxAttempts();
+        let lastStreamError: unknown = undefined;

        for (let attempt = 0; attempt < maxAttempts; attempt++) {
          let isConnectionPhase = true;
@@ -526,7 +562,7 @@ export class GeminiChat {
            // If this is a retry, update the key with the new context.
            const currentConfigKey =
              attempt > 0
-                ? { ...modelConfigKey, isRetry: true }
+                ? { ...modelConfigKey, isRetry: true, lastStreamError }
                : modelConfigKey;

            isConnectionPhase = true;
@@ -545,6 +581,10 @@ export class GeminiChat {

            return;
          } catch (error) {
+            if (error instanceof InvalidStreamError) {
+              lastStreamError = error;
+            }
+
            if (error instanceof AgentExecutionStoppedError) {
              yield {
                type: StreamEventType.AGENT_EXECUTION_STOPPED,
@@ -581,8 +621,7 @@ export class GeminiChat {
            );

            const isContentError = error instanceof InvalidStreamError;
-            const isRetryableContentError =
-              isContentError && error.type !== 'NO_RESPONSE_TEXT';
+            const isRetryableContentError = isContentError;
            const errorType = isContentError
              ? error.type
              : getRetryErrorType(error);
@@ -644,6 +683,15 @@ export class GeminiChat {
            throw error;
          }
        }
+      } catch (error) {
+        if (!isOriginalFunctionResponse) {
+          this.agentHistory.rollback(historyLengthBefore);
+          this.chatRecordingService.updateMessagesFromHistory(
+            this.agentHistory.get(),
+          );
+          this.lastPromptTokenCount = baselinePromptTokenCount;
+        }
+        throw error;
      } finally {
        streamDoneResolver!();
      }
@@ -652,6 +700,28 @@ export class GeminiChat {
    return streamWithRetries.call(this);
  }

+  /**
+   * Appends a closing model turn when history ends with an unanswered tool
+   * response, so the next user message stays a turn of its own.
+   */
+  private closeUnansweredToolResponseTurn(): void {
+    const turns = this.agentHistory.get();
+    const last = turns[turns.length - 1];
+    if (
+      last?.content.role !== 'user' ||
+      !last.content.parts?.some((part) => !!part.functionResponse)
+    ) {
+      return;
+    }
+    this.agentHistory.push({
+      id: randomUUID(),
+      content: {
+        role: 'model',
+        parts: [{ text: INTERRUPTED_RESPONSE_PLACEHOLDER }],
+      },
+    });
+  }
+
  private extractBinaryInjections(
    parts: Part[] | undefined,
  ): Part[] | undefined {
@@ -683,10 +753,13 @@ export class GeminiChat {
  ): Promise<AsyncGenerator<GenerateContentResponse>> {
    // Last mile scrubbing to remove internal tracking properties (e.g. callIndex)
    // before sending to the Gemini API. This whitelists only standard Gemini fields.
-    const scrubbedHistory = this.context.config.isContextManagementEnabled()
+    let scrubbedHistory = this.context.config.isContextManagementEnabled()
      ? scrubHistory([...requestHistory])
      : [...requestHistory];

+    // Always coalesce consecutive roles to prevent 400 Bad Request errors
+    scrubbedHistory = coalesceConsecutiveRoles(scrubbedHistory);
+
    const scrubbedContents = scrubbedHistory.map((h) => h.content);

    const requestContents = apiHistoryOverride
@@ -763,9 +836,34 @@ export class GeminiChat {
        abortSignal,
      };

-      let contentsToUse: Content[] = supportsModernFeatures(modelToUse)
-        ? [...contentsForPreviewModel]
-        : [...requestContents];
+      // Apply Context-Aware Retries (On-Retry Nudging) to guide the model out of silent loops
+      if (
+        modelConfigKey.isRetry &&
+        modelConfigKey.lastStreamError instanceof InvalidStreamError
+      ) {
+        const lastError = modelConfigKey.lastStreamError;
+        let nudgeMessage = '';
+        if (lastError.type === 'THINKING_ONLY_RESPONSE') {
+          nudgeMessage =
+            '\n[System: You previously generated thoughts but failed to provide a final user-facing response. Please ensure you provide your final answer or call a tool now.]';
+        } else if (lastError.type === 'NO_RESPONSE_TEXT') {
+          nudgeMessage =
+            '\n[System: You previously returned an empty response with no text or thoughts. Please ensure you provide your final answer or call a tool now.]';
+        }
+
+        if (nudgeMessage) {
+          if (typeof config.systemInstruction === 'string') {
+            config.systemInstruction += nudgeMessage;
+          } else if (config.systemInstruction === undefined) {
+            config.systemInstruction = nudgeMessage;
+          }
+        }
+      }
+
+      let contentsToUse: Content[] =
+        supportsModernFeatures(modelToUse) || isGemini2Model(modelToUse)
+          ? [...contentsForPreviewModel]
+          : [...requestContents];

      const hookSystem = this.context.config.getHookSystem();
      if (hookSystem) {
@@ -807,9 +905,10 @@ export class GeminiChat {
          );
          lastModelToUse = modelToUse;
          // Re-evaluate contentsToUse based on the new model's feature support
-          contentsToUse = supportsModernFeatures(modelToUse)
-            ? [...contentsForPreviewModel]
-            : [...requestContents];
+          contentsToUse =
+            supportsModernFeatures(modelToUse) || isGemini2Model(modelToUse)
+              ? [...contentsForPreviewModel]
+              : [...requestContents];
        }
        if (beforeModelResult.modifiedConfig) {
          Object.assign(config, beforeModelResult.modifiedConfig);
@@ -953,9 +1052,16 @@ export class GeminiChat {
      ? extractCuratedHistory(this.agentHistory.get())
      : [...this.agentHistory.get()];

-    return this.context.config.isContextManagementEnabled()
-      ? scrubHistory(history)
-      : history;
+    if (this.context.config.isContextManagementEnabled()) {
+      return scrubHistory(history);
+    }
+
+    const model = this.context.config.getModel();
+    if (isGemini2Model(model) || supportsModernFeatures(model)) {
+      return coalesceConsecutiveRoles(stripThoughts(history));
+    }
+
+    return history;
  }

  /**
@@ -1028,11 +1134,19 @@ export class GeminiChat {
    requestContents: readonly Content[],
  ): readonly Content[] {
    // First, find the start of the active loop by finding the last user turn
-    // with a text message, i.e. that is not a function response.
+    // with a text message, i.e. that is not a function response. Testing for
+    // text alone is not enough: `coalesceConsecutiveRoles` can merge a function
+    // response turn with the prompt that follows it, and starting the loop at
+    // such a turn starts it later than the API starts the turn, leaving earlier
+    // function calls unsigned but still validated.
    let activeLoopStartIndex = -1;
    for (let i = requestContents.length - 1; i >= 0; i--) {
      const content = requestContents[i];
-      if (content.role === 'user' && content.parts?.some((part) => part.text)) {
+      if (
+        content.role === 'user' &&
+        content.parts?.some((part) => part.text) &&
+        !content.parts?.some((part) => part.functionResponse)
+      ) {
        activeLoopStartIndex = i;
        break;
      }
@@ -1119,6 +1233,13 @@ export class GeminiChat {
    let hasThoughts = false;
    let finishReason: FinishReason | undefined;

+    // Buffers to prevent failed stream attempts from polluting telemetry and logs
+    const bufferedThoughts: Array<{ subject: string; description: string }> =
+      [];
+    let bufferedUsageMetadata:
+      | GenerateContentResponse['usageMetadata']
+      | undefined = undefined;
+
    // The SDK provides fully assembled FunctionCall objects in chunk.functionCalls
    // We use a Map to ensure we only keep the latest version of each call (by ID)
    const finalFunctionCallsMap = new Map<string, FunctionCall>();
@@ -1174,7 +1295,10 @@ export class GeminiChat {
          if (content.parts.some((part) => part.thought)) {
            // Record thoughts
            hasThoughts = true;
-            this.recordThoughtFromContent(content);
+            const thought = this.extractThoughtFromContent(content);
+            if (thought) {
+              bufferedThoughts.push(thought);
+            }
          }
          if (content.parts.some((part) => part.functionCall)) {
            hasToolCall = true;
@@ -1202,12 +1326,9 @@ export class GeminiChat {
        }
      }

-      // Record token usage if this chunk has usageMetadata
+      // Buffer token usage if this chunk has usageMetadata
      if (chunk.usageMetadata) {
-        this.chatRecordingService.recordMessageTokens(chunk.usageMetadata);
-        if (chunk.usageMetadata.promptTokenCount !== undefined) {
-          this.lastPromptTokenCount = chunk.usageMetadata.promptTokenCount;
-        }
+        bufferedUsageMetadata = chunk.usageMetadata;
      }

      const hookSystem = this.context.config.getHookSystem();
@@ -1294,29 +1415,22 @@ export class GeminiChat {
      }
    }

-    const responseText = consolidatedParts
+    const rawResponseText = consolidatedParts
      .filter((part) => part.text)
      .map((part) => part.text)
-      .join('')
-      .trim();
+      .join('');

-    let id: string;
-    // Record model response text from the collected parts.
-    // Also flush when there are thoughts or a tool call (even with no text)
-    // so that BeforeTool hooks always see the latest transcript state.
-    if (responseText || hasThoughts || hasToolCall) {
-      id = this.chatRecordingService.recordMessage({
-        model,
-        type: 'gemini',
-        content: responseText,
-      });
-    } else {
-      // Still need a durable ID even if response is empty (e.g. only tool calls)
-      id = this.chatRecordingService.recordSyntheticMessage(
-        'gemini',
-        consolidatedParts,
-      );
-    }
+    // Clean zero-width/invisible characters and HTML comments to determine actual printable/visible content
+    let responseText = rawResponseText.replace(
+      /[\u200B-\u200D\uFEFF\u200E\u200F]/g,
+      '',
+    );
+    let previous: string;
+    do {
+      previous = responseText;
+      responseText = responseText.replace(/<!--[\s\S]*?-->/g, '');
+    } while (responseText !== previous);
+    responseText = responseText.trim();

    // Stream validation logic: A stream is considered successful if:
    // 1. There's a tool call OR
@@ -1346,6 +1460,36 @@ export class GeminiChat {
        );
      }
      if (!responseText) {
+        if (finishReason === FinishReason.MAX_TOKENS) {
+          throw new InvalidStreamError(
+            'Model stream ended due to token limit exhaustion (MAX_TOKENS) with empty response text.',
+            'MAX_TOKENS_EXCEEDED',
+          );
+        }
+        if (finishReason === FinishReason.SAFETY) {
+          throw new InvalidStreamError(
+            'Model stream ended due to safety settings (SAFETY) with empty response text.',
+            'SAFETY_BLOCKED',
+          );
+        }
+        if (finishReason === FinishReason.RECITATION) {
+          throw new InvalidStreamError(
+            'Model stream ended due to recitation settings (RECITATION) with empty response text.',
+            'RECITATION_BLOCKED',
+          );
+        }
+        if (finishReason === FinishReason.OTHER) {
+          throw new InvalidStreamError(
+            'Model stream ended due to other settings (OTHER) with empty response text.',
+            'OTHER_BLOCKED',
+          );
+        }
+        if (hasThoughts) {
+          throw new InvalidStreamError(
+            'Model stream ended with empty response text but contained reasoning thoughts.',
+            'THINKING_ONLY_RESPONSE',
+          );
+        }
        throw new InvalidStreamError(
          'Model stream ended with empty response text.',
          'NO_RESPONSE_TEXT',
@@ -1353,6 +1497,37 @@ export class GeminiChat {
      }
    }

+    // Flush buffered thoughts from the successful attempt
+    for (const thought of bufferedThoughts) {
+      this.chatRecordingService.recordThought(thought);
+    }
+
+    // Flush buffered usage metadata and token counts from the successful attempt
+    if (bufferedUsageMetadata) {
+      this.chatRecordingService.recordMessageTokens(bufferedUsageMetadata);
+      if (bufferedUsageMetadata.promptTokenCount !== undefined) {
+        this.lastPromptTokenCount = bufferedUsageMetadata.promptTokenCount;
+      }
+    }
+
+    let id: string;
+    // Record model response text from the collected parts.
+    // Also flush when there are thoughts or a tool call (even with no text)
+    // so that BeforeTool hooks always see the latest transcript state.
+    if (responseText || hasThoughts || hasToolCall) {
+      id = this.chatRecordingService.recordMessage({
+        model,
+        type: 'gemini',
+        content: responseText,
+      });
+    } else {
+      // Still need a durable ID even if response is empty (e.g. only tool calls)
+      id = this.chatRecordingService.recordSyntheticMessage(
+        'gemini',
+        consolidatedParts,
+      );
+    }
+
    this.agentHistory.push({
      id,
      content: { role: 'model', parts: consolidatedParts },
@@ -1407,11 +1582,13 @@ export class GeminiChat {
  }

  /**
-   * Extracts and records thought from thought content.
+   * Extracts thought from thought content.
   */
-  private recordThoughtFromContent(content: Content): void {
+  private extractThoughtFromContent(
+    content: Content,
+  ): { subject: string; description: string } | undefined {
    if (!content.parts || content.parts.length === 0) {
-      return;
+      return undefined;
    }

    const thoughtPart = content.parts[0];
@@ -1424,11 +1601,12 @@ export class GeminiChat {
        : '';
      const description = rawText.replace(/\*\*(.*?)\*\*/s, '').trim();

-      this.chatRecordingService.recordThought({
+      return {
        subject,
        description,
-      });
+      };
    }
+    return undefined;
  }
 }

@@ -1472,3 +1650,73 @@ export function stripToolCallIdPrefixes(contents: Content[]): Content[] {
    }),
  }));
 }
+
+export function coalesceConsecutiveRoles(
+  history: HistoryTurn[],
+): HistoryTurn[] {
+  const result: HistoryTurn[] = [];
+  for (const turn of history) {
+    const lastIdx = result.length - 1;
+    const last = result[lastIdx];
+    if (last && last.content.role && last.content.role === turn.content.role) {
+      const hasParts = last.content.parts || turn.content.parts;
+      result[lastIdx] = {
+        id: last.id,
+        content: {
+          ...last.content,
+          parts: hasParts
+            ? [...(last.content.parts || []), ...(turn.content.parts || [])]
+            : undefined,
+        },
+      };
+    } else {
+      result.push({
+        id: turn.id,
+        content: { ...turn.content },
+      });
+    }
+  }
+  return result;
+}
+
+export function stripThoughts(history: HistoryTurn[]): HistoryTurn[] {
+  return history
+    .map((turn) => {
+      if (!turn.content.parts) return turn;
+      const hasThought = turn.content.parts.some((p) => p && p.thought);
+      if (!hasThought) return turn;
+
+      const nonThoughtParts = turn.content.parts.filter((p) => p && !p.thought);
+
+      // The thoughtSignature the API requires on the first functionCall of a
+      // model turn is sometimes only carried by the thought part we just
+      // removed, not by the functionCall part itself. Without it, replaying
+      // this turn in a later request gets rejected with a 400 "missing
+      // thought_signature" error, so inject a synthetic one if needed.
+      let patchedFirstCall = false;
+      const finalParts =
+        turn.content.role === 'model'
+          ? nonThoughtParts.map((p) => {
+              if (!patchedFirstCall && p.functionCall) {
+                patchedFirstCall = true;
+                if (!p.thoughtSignature) {
+                  return {
+                    ...p,
+                    thoughtSignature: SYNTHETIC_THOUGHT_SIGNATURE,
+                  };
+                }
+              }
+              return p;
+            })
+          : nonThoughtParts;
+
+      return {
+        ...turn,
+        content: {
+          ...turn.content,
+          parts: finalParts,
+        },
+      };
+    })
+    .filter((turn) => !turn.content.parts || turn.content.parts.length > 0);
+}
@@ -254,7 +254,15 @@ describe('Turn', () => {
        events.push(event);
      }

-      expect(events).toEqual([{ type: GeminiEventType.InvalidStream }]);
+      expect(events).toEqual([
+        {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: 'NO_FINISH_REASON',
+            message: 'Test invalid stream',
+          },
+        },
+      ]);
      expect(turn.getDebugResponses().length).toBe(0);
      expect(reportError).not.toHaveBeenCalled(); // Should not report as error
    });
@@ -105,6 +105,19 @@ export type ServerGeminiContextWindowWillOverflowEvent = {

 export type ServerGeminiInvalidStreamEvent = {
  type: GeminiEventType.InvalidStream;
+  value: {
+    type:
+      | 'NO_FINISH_REASON'
+      | 'NO_RESPONSE_TEXT'
+      | 'MALFORMED_FUNCTION_CALL'
+      | 'UNEXPECTED_TOOL_CALL'
+      | 'MAX_TOKENS_EXCEEDED'
+      | 'SAFETY_BLOCKED'
+      | 'RECITATION_BLOCKED'
+      | 'OTHER_BLOCKED'
+      | 'THINKING_ONLY_RESPONSE';
+    message: string;
+  };
 };

 export type ServerGeminiModelInfoEvent = {
@@ -408,7 +421,13 @@ export class Turn {
      }

      if (e instanceof InvalidStreamError) {
-        yield { type: GeminiEventType.InvalidStream };
+        yield {
+          type: GeminiEventType.InvalidStream,
+          value: {
+            type: e.type,
+            message: e.message,
+          },
+        };
        return;
      }

@@ -67,6 +67,7 @@ const createMockConfig = (overrides: Partial<Config> = {}): Config =>
    setActiveModel: vi.fn(),
    setModel: vi.fn(),
    activateFallbackMode: vi.fn(),
+    rotateSessionId: vi.fn(),
    getModelAvailabilityService: vi.fn(() =>
      createAvailabilityServiceMock({
        selectedModel: FALLBACK_MODEL,
@@ -5,6 +5,7 @@
 */

 import type { Config } from '../config/config.js';
+import { createSessionId } from '../utils/session.js';
 import {
  openBrowserSecurely,
  shouldLaunchBrowser,
@@ -161,8 +162,9 @@ async function processIntent(
 ): Promise<boolean> {
  switch (intent) {
    case 'retry_always':
-      // TODO(telemetry): Implement generic fallback event logging. Existing
-      // logFlashFallback is specific to a single Model.
+      // Rotate the session ID to ensure the backend treats the retried request
+      // as a brand-new session, preventing stateful model-switching errors.
+      config.rotateSessionId(createSessionId());
      config.activateFallbackMode(fallbackModel, failedModel);
      return true;

@@ -413,6 +413,16 @@ export function renderOperationalGuidelines(
 - **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.

 ## Tool Usage
+- **Tool Execution Response Rules:**
+  1. After receiving a \`functionResponse\`, you MUST ALWAYS execute one of the following two actions:
+     a) Call another tool to proceed with the task.
+     b) Provide a user-facing text response explaining the tool output, your analysis, and next steps.
+  2. You MUST NEVER return an empty response with no text and no tool calls.
+- **Post-Edit Response Rules:**
+  1. After an edit tool execution (e.g. ${formatToolName(EDIT_TOOL_NAME)}, ${formatToolName(WRITE_FILE_TOOL_NAME)}), you MUST ALWAYS generate a user-facing text response summarizing:
+     - What changes were made to the file.
+     - Your verification plan or next steps (e.g. running tests).
+  2. You MUST NEVER return an empty response with 0 text tokens after completing an edit.
 - **Parallelism & Sequencing:** Tools execute in parallel by default. Execute multiple independent tool calls in parallel when feasible (e.g., searching, reading files, independent shell commands, or editing *different* files). If a tool depends on the output or side-effects of a previous tool in the same turn (e.g., running a shell command that depends on the success of a previous command), you MUST set the \`wait_for_previous\` parameter to \`true\` on the dependent tool to ensure sequential execution.
 - **File Editing Collisions:** Do NOT make multiple calls to the ${formatToolName(EDIT_TOOL_NAME)} tool for the SAME file in a single turn. To make multiple edits to the same file, you MUST perform them sequentially across multiple conversational turns to prevent race conditions and ensure the file state is accurate before each edit.
 - **Command Execution:** Use the ${formatToolName(SHELL_TOOL_NAME)} tool for running shell commands, remembering the safety rule to explain modifying commands first.${toolUsageInteractive(
@@ -34,6 +34,10 @@ describe('CheckerRunner', () => {

  beforeEach(() => {
    mockContextBuilder = new ContextBuilder({} as Config);
+    vi.spyOn(mockContextBuilder, 'config', 'get').mockReturnValue({
+      env: {},
+      getWorkingDir: vi.fn().mockReturnValue('/mock/cwd'),
+    } as unknown as Config);
    mockRegistry = new CheckerRegistry('/mock/dist');
    CheckerRegistry.prototype.resolveInProcess = vi.fn();

@@ -168,6 +168,8 @@ export class CheckerRunner {
    return new Promise((resolve) => {
      const child = spawn(checkerPath, [], {
        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: this.contextBuilder.config.getWorkingDir(),
+        env: { ...process.env, ...this.contextBuilder.config.env },
      });

      let stdout = '';
@@ -15,6 +15,10 @@ import type { AgentLoopContext } from '../config/agent-loop-context.js';
 export class ContextBuilder {
  constructor(private readonly context: AgentLoopContext) {}

+  get config() {
+    return this.context.config;
+  }
+
  /**
   * Builds the full context object with all available data.
   */
@@ -630,8 +630,8 @@ describe('Scheduler (Orchestrator)', () => {
        CoreToolCallStatus.Cancelled,
        'Operation cancelled by user',
      );
-      // finalizeCall is handled by the processing loop, not synchronously by cancelAll
-      // expect(mockStateManager.finalizeCall).toHaveBeenCalledWith('call-1');
+      // finalizeCall is called synchronously by cancelAll to ensure completedBatch is populated and isActive is updated immediately
+      expect(mockStateManager.finalizeCall).toHaveBeenCalledWith('call-1');
      expect(mockStateManager.cancelAllQueued).toHaveBeenCalledWith(
        'Operation cancelled by user',
      );
@@ -278,6 +278,7 @@ export class Scheduler {
          CoreToolCallStatus.Cancelled,
          'Operation cancelled by user',
        );
+        this.state.finalizeCall(activeCall.request.callId);
      }
    }

@@ -438,6 +439,14 @@ export class Scheduler {
   */
  private async _processNextItem(signal: AbortSignal): Promise<boolean> {
    if (signal.aborted || this.isCancelling) {
+      // Finalize active calls that are terminal
+      const activeCalls = this.state.allActiveCalls;
+      for (const call of activeCalls) {
+        if (this.isTerminal(call.status)) {
+          this.state.finalizeCall(call.request.callId);
+        }
+      }
+
      this.state.cancelAllQueued('Operation cancelled');
      return false;
    }
@@ -308,6 +308,125 @@ describe('ChatRecordingService', () => {
      )) as ConversationRecord;
      expect(conversation.sessionId).toBe('old-session-id');
    });
+
+    it('should fall back to the in-memory conversation when the file cannot be reloaded', async () => {
+      // Regression test for the `/compress` "Failed to load resumed session
+      // data from file" bug: when resuming with a filePath that cannot be
+      // loaded from disk, initialize must NOT throw. It should adopt the
+      // in-memory conversation it was handed and rewrite a clean file.
+      const chatsDir = path.join(testTempDir, 'chats');
+      fs.mkdirSync(chatsDir, { recursive: true });
+      const missingFile = path.join(chatsDir, 'missing-session.jsonl');
+      expect(fs.existsSync(missingFile)).toBe(false);
+
+      const inMemoryConversation = {
+        sessionId: 'resumed-session-id',
+        projectHash: 'resumed-project-hash',
+        startTime: new Date().toISOString(),
+        lastUpdated: new Date().toISOString(),
+        messages: [
+          {
+            id: 'msg-1',
+            type: 'user',
+            timestamp: new Date().toISOString(),
+            content: 'hello from memory',
+          },
+        ],
+      } as unknown as ConversationRecord;
+
+      await expect(
+        chatRecordingService.initialize({
+          filePath: missingFile,
+          conversation: inMemoryConversation,
+        }),
+      ).resolves.not.toThrow();
+
+      // The in-memory conversation is adopted.
+      expect(chatRecordingService.getConversation()?.sessionId).toBe(
+        'resumed-session-id',
+      );
+
+      // A clean, loadable file is rewritten from the in-memory copy so future
+      // loads and appends succeed.
+      const reloaded = (await loadConversationRecord(
+        missingFile,
+      )) as ConversationRecord;
+      expect(reloaded).not.toBeNull();
+      expect(reloaded.sessionId).toBe('resumed-session-id');
+      expect(reloaded.projectHash).toBe('resumed-project-hash');
+      expect(reloaded.messages).toHaveLength(1);
+    });
+
+    it('should preserve an unreadable session file instead of destroying it', async () => {
+      // The reload may have failed only transiently, so the original bytes
+      // must survive the recovery rewrite.
+      const chatsDir = path.join(testTempDir, 'chats');
+      fs.mkdirSync(chatsDir, { recursive: true });
+      const sessionFile = path.join(chatsDir, 'unreadable.jsonl');
+
+      // No usable metadata line => loadConversationRecord() returns null.
+      const originalBytes = '{"not":"a valid metadata line"}\n';
+      fs.writeFileSync(sessionFile, originalBytes);
+
+      await chatRecordingService.initialize({
+        filePath: sessionFile,
+        conversation: {
+          sessionId: 'recovered-session-id',
+          projectHash: 'recovered-project-hash',
+          startTime: new Date().toISOString(),
+          lastUpdated: new Date().toISOString(),
+          messages: [],
+        } as unknown as ConversationRecord,
+      });
+
+      // The rewritten file is loadable again...
+      const reloaded = (await loadConversationRecord(
+        sessionFile,
+      )) as ConversationRecord;
+      expect(reloaded.sessionId).toBe('recovered-session-id');
+
+      // ...and the original bytes were kept alongside it.
+      const preserved = fs
+        .readdirSync(chatsDir)
+        .filter((f) => f.startsWith('unreadable.jsonl.unreadable-'));
+      expect(preserved).toHaveLength(1);
+      expect(fs.readFileSync(path.join(chatsDir, preserved[0]), 'utf-8')).toBe(
+        originalBytes,
+      );
+    });
+
+    it('should not leave a temp file behind when the rewrite fails', async () => {
+      const chatsDir = path.join(testTempDir, 'chats');
+      fs.mkdirSync(chatsDir, { recursive: true });
+      const sessionFile = path.join(chatsDir, 'rewrite-fails.jsonl');
+
+      // Fail the rename that publishes the temp file, leaving it orphaned.
+      const realRename = fs.renameSync;
+      vi.spyOn(fs, 'renameSync').mockImplementation((from, to) => {
+        if (String(from).includes('.tmp-')) {
+          throw new Error('simulated rename failure');
+        }
+        return realRename(from, to);
+      });
+
+      await expect(
+        chatRecordingService.initialize({
+          filePath: sessionFile,
+          conversation: {
+            sessionId: 'temp-cleanup-session',
+            projectHash: 'temp-cleanup-hash',
+            startTime: new Date().toISOString(),
+            lastUpdated: new Date().toISOString(),
+            messages: [],
+          } as unknown as ConversationRecord,
+        }),
+      ).rejects.toThrow('simulated rename failure');
+
+      const leftovers = fs
+        .readdirSync(chatsDir)
+        .filter((f) => f.includes('.tmp-'));
+      expect(leftovers).toEqual([]);
+    });
  });

  describe('recordMessage', () => {
@@ -462,7 +462,16 @@ export class ChatRecordingService {
          // Update the session ID in the existing file
          this.updateMetadata({ sessionId: this.sessionId });
        } else {
-          throw new Error('Failed to load resumed session data from file');
+          // The file could not be reloaded (missing, corrupt metadata, or an
+          // I/O error). Fall back to the in-memory conversation we were handed
+          // rather than failing the caller, and rewrite a clean file from it.
+          debugLogger.warn(
+            'Failed to reload resumed session data from file; falling back ' +
+              'to the in-memory conversation.',
+          );
+          this.cachedConversation = resumedSessionData.conversation;
+          this.projectHash = this.cachedConversation.projectHash;
+          this.rewriteConversationFile(this.cachedConversation);
        }
      } else {
        // Create new session
@@ -563,6 +572,73 @@ export class ChatRecordingService {
    }
  }

+  /**
+   * Rewrites the session file from an in-memory record. Any existing
+   * (unreadable) file is preserved alongside rather than destroyed, and the
+   * new file is written atomically (temp file + rename).
+   */
+  private rewriteConversationFile(conversation: ConversationRecord): void {
+    if (!this.conversationFile) return;
+
+    // Normalize legacy `.json` paths to the `.jsonl` format we write.
+    if (this.conversationFile.endsWith('.json')) {
+      this.conversationFile = this.conversationFile + 'l';
+    }
+
+    const { messages, memoryScratchpad, ...metadata } = conversation;
+    const lines: string[] = [JSON.stringify(metadata)];
+    for (const msg of messages) {
+      lines.push(JSON.stringify(msg));
+    }
+    if (memoryScratchpad) {
+      lines.push(JSON.stringify({ $set: { memoryScratchpad } }));
+    }
+    const content = lines.join('\n') + '\n';
+
+    try {
+      fs.mkdirSync(path.dirname(this.conversationFile), { recursive: true });
+
+      // The existing file was unreadable, but it may have been only
+      // transiently so (a lock or I/O blip) rather than truly corrupt. Keep
+      // its bytes rather than destroying them.
+      if (fs.existsSync(this.conversationFile)) {
+        const backup = `${this.conversationFile}.unreadable-${Date.now()}`;
+        try {
+          fs.renameSync(this.conversationFile, backup);
+          debugLogger.warn(
+            `Preserved the unreadable session file at ${backup}.`,
+          );
+        } catch (backupError) {
+          debugLogger.error(
+            'Failed to preserve the unreadable session file.',
+            backupError,
+          );
+        }
+      }
+
+      const tempFile = `${this.conversationFile}.tmp-${process.pid}`;
+      try {
+        fs.writeFileSync(tempFile, content);
+        fs.renameSync(tempFile, this.conversationFile);
+      } catch (error) {
+        // The rename did not complete, so the temp file would be left behind.
+        try {
+          fs.unlinkSync(tempFile);
+        } catch {
+          // Ignore cleanup errors so the original failure still surfaces.
+        }
+        throw error;
+      }
+    } catch (error) {
+      if (isNodeError(error) && error.code === 'ENOSPC') {
+        this.conversationFile = null;
+        debugLogger.warn(ENOSPC_WARNING_MESSAGE);
+      } else {
+        throw error;
+      }
+    }
+  }
+
  private updateMetadata(updates: Partial<ConversationRecord>): void {
    if (!this.cachedConversation) return;
    Object.assign(this.cachedConversation, updates);
@@ -27,8 +27,15 @@ export class FileKeychain implements Keychain {
  }

  private encrypt(text: string): string {
-    const iv = crypto.randomBytes(16);
-    const cipher = crypto.createCipheriv('aes-256-gcm', this.encryptionKey, iv);
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv(
+      'aes-256-gcm',
+      this.encryptionKey,
+      iv,
+      {
+        authTagLength: 16,
+      },
+    );

    let encrypted = cipher.update(text, 'utf8', 'hex');
    encrypted += cipher.final('hex');
@@ -48,10 +55,19 @@ export class FileKeychain implements Keychain {
    const authTag = Buffer.from(parts[1], 'hex');
    const encrypted = parts[2];

+    if (iv.length !== 12 && iv.length !== 16) {
+      throw new Error('Invalid IV length: Must be 12 or 16 bytes');
+    }
+
+    if (authTag.length !== 16) {
+      throw new Error('Invalid authentication tag length: Must be 16 bytes');
+    }
+
    const decipher = crypto.createDecipheriv(
      'aes-256-gcm',
      this.encryptionKey,
      iv,
+      { authTagLength: 16 },
    );
    decipher.setAuthTag(authTag);

@@ -67,30 +83,28 @@ export class FileKeychain implements Keychain {
  }

  private async loadData(): Promise<Record<string, Record<string, string>>> {
+    let data: string;
    try {
-      const data = await fs.readFile(this.tokenFilePath, 'utf-8');
-      const decrypted = this.decrypt(data);
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      return JSON.parse(decrypted) as Record<string, Record<string, string>>;
+      data = await fs.readFile(this.tokenFilePath, 'utf-8');
    } catch (error: unknown) {
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      const err = error as NodeJS.ErrnoException & { message?: string };
+      const err = error as NodeJS.ErrnoException;
      if (err.code === 'ENOENT') {
        return {};
      }
-      if (
-        err.message?.includes('Invalid encrypted data format') ||
-        err.message?.includes(
-          'Unsupported state or unable to authenticate data',
-        )
-      ) {
-        throw new Error(
-          `Corrupted credentials file detected at: ${this.tokenFilePath}\n` +
-            `Please delete or rename this file to resolve the issue.`,
-        );
-      }
      throw error;
    }
+
+    try {
+      const decrypted = this.decrypt(data);
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return JSON.parse(decrypted) as Record<string, Record<string, string>>;
+    } catch {
+      throw new Error(
+        `Corrupted credentials file detected at: ${this.tokenFilePath}\n` +
+          `Please delete or rename this file to resolve the issue.`,
+      );
+    }
  }

  private async saveData(
@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import { FileKeychain } from './fileKeychain.js';
+
+describe('AES-GCM Tag Length Verification', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    // Create a unique temporary directory for test isolation
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gemini-test-keychain-'));
+    vi.stubEnv('GEMINI_CLI_HOME', tempDir);
+  });
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    // Clean up the temporary directory
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('should use a secure 128-bit (16-byte) AES-GCM authentication tag and standard 12-byte IV', async () => {
+    const keychain = new FileKeychain();
+    const service = 'test-service';
+    const account = 'test-account';
+    const password = 'secure-password-123';
+
+    // 1. Save credentials to trigger encryption and file write
+    await keychain.setPassword(service, account, password);
+
+    // 2. Read the raw encrypted file from disk
+    const credentialsFilePath = path.join(
+      tempDir,
+      '.gemini',
+      'gemini-credentials.json',
+    );
+    const rawEncryptedData = await fs.readFile(credentialsFilePath, 'utf-8');
+
+    // 3. Parse the encrypted data format (iv:authTag:encrypted)
+    const parts = rawEncryptedData.split(':');
+    expect(parts).toHaveLength(3);
+
+    const ivHex = parts[0];
+    const authTagHex = parts[1];
+
+    // 4. Verify the lengths of the components
+    const ivBuffer = Buffer.from(ivHex, 'hex');
+    const authTagBuffer = Buffer.from(authTagHex, 'hex');
+
+    // IV should be exactly 12 bytes (96 bits) by default
+    expect(ivBuffer.length).toBe(12);
+    expect(ivHex.length).toBe(24);
+
+    // Authentication Tag should be exactly 16 bytes (128 bits)
+    expect(authTagBuffer.length).toBe(16);
+    expect(authTagHex.length).toBe(32); // 32 hex characters
+
+    // Assert that the tag is NOT truncated to 4 bytes (32 bits)
+    expect(authTagBuffer.length).not.toBe(4);
+    expect(authTagHex.length).not.toBe(8); // 8 hex characters
+
+    // 5. Verify that decryption works correctly with the 16-byte tag
+    const decryptedPassword = await keychain.getPassword(service, account);
+    expect(decryptedPassword).toBe(password);
+  });
+
+  it('should support both 12-byte and 16-byte IVs for backward compatibility', async () => {
+    const keychain = new FileKeychain();
+    const service = 'test-service';
+    const account = 'test-account';
+    const password = 'secure-password-123';
+
+    // 1. Save credentials to trigger encryption and file write (generates 12-byte IV)
+    await keychain.setPassword(service, account, password);
+
+    // 2. Verify 12-byte IV decryption works
+    let decryptedPassword = await keychain.getPassword(service, account);
+    expect(decryptedPassword).toBe(password);
+
+    // 3. Manually simulate a legacy 16-byte IV credentials file
+    const credentialsFilePath = path.join(
+      tempDir,
+      '.gemini',
+      'gemini-credentials.json',
+    );
+    const legacyIv = crypto.randomBytes(16);
+    const encryptionKey = (keychain as unknown as { encryptionKey: Buffer })
+      .encryptionKey;
+    const cipher = crypto.createCipheriv(
+      'aes-256-gcm',
+      encryptionKey,
+      legacyIv,
+      {
+        authTagLength: 16,
+      },
+    );
+
+    let encrypted = cipher.update(
+      JSON.stringify({ [service]: { [account]: password } }),
+      'utf8',
+      'hex',
+    );
+    encrypted += cipher.final('hex');
+    const authTag = cipher.getAuthTag();
+
+    const legacyPayload =
+      legacyIv.toString('hex') +
+      ':' +
+      authTag.toString('hex') +
+      ':' +
+      encrypted;
+    await fs.writeFile(credentialsFilePath, legacyPayload, 'utf-8');
+
+    // 4. Verify 16-byte IV decryption works successfully (backward compatibility)
+    decryptedPassword = await keychain.getPassword(service, account);
+    expect(decryptedPassword).toBe(password);
+  });
+
+  it('should reject decryption of a credentials file with a truncated tag', async () => {
+    const keychain = new FileKeychain();
+    const service = 'test-service';
+    const account = 'test-account';
+    const password = 'secure-password-123';
+
+    // 1. Save credentials to trigger encryption and file write
+    await keychain.setPassword(service, account, password);
+
+    // 2. Read the raw encrypted file from disk
+    const credentialsFilePath = path.join(
+      tempDir,
+      '.gemini',
+      'gemini-credentials.json',
+    );
+    const rawEncryptedData = await fs.readFile(credentialsFilePath, 'utf-8');
+
+    // 3. Parse the encrypted data format (iv:authTag:encrypted)
+    const parts = rawEncryptedData.split(':');
+    expect(parts).toHaveLength(3);
+
+    const ivHex = parts[0];
+    const authTagHex = parts[1];
+    const encryptedHex = parts[2];
+
+    // 4. Create a truncated 4-byte tag (8 hex characters)
+    const truncatedTagHex = authTagHex.substring(0, 8);
+    const truncatedEncryptedData = `${ivHex}:${truncatedTagHex}:${encryptedHex}`;
+
+    // 5. Overwrite the credentials file with the truncated-tag payload
+    await fs.writeFile(credentialsFilePath, truncatedEncryptedData, 'utf-8');
+
+    // 6. Attempt to retrieve the password and verify it throws a clear, handled validation error
+    await expect(keychain.getPassword(service, account)).rejects.toThrow(
+      'Corrupted credentials file detected',
+    );
+  });
+
+  it('should reject decryption of a credentials file with a truncated IV', async () => {
+    const keychain = new FileKeychain();
+    const service = 'test-service';
+    const account = 'test-account';
+    const password = 'secure-password-123';
+
+    // 1. Save credentials to trigger encryption and file write
+    await keychain.setPassword(service, account, password);
+
+    // 2. Read the raw encrypted file from disk
+    const credentialsFilePath = path.join(
+      tempDir,
+      '.gemini',
+      'gemini-credentials.json',
+    );
+    const rawEncryptedData = await fs.readFile(credentialsFilePath, 'utf-8');
+
+    // 3. Parse the encrypted data format (iv:authTag:encrypted)
+    const parts = rawEncryptedData.split(':');
+    expect(parts).toHaveLength(3);
+
+    const ivHex = parts[0];
+    const authTagHex = parts[1];
+    const encryptedHex = parts[2];
+
+    // 4. Create a truncated 4-byte IV (8 hex characters)
+    const truncatedIvHex = ivHex.substring(0, 8);
+    const truncatedEncryptedData = `${truncatedIvHex}:${authTagHex}:${encryptedHex}`;
+
+    // 5. Overwrite the credentials file with the truncated-IV payload
+    await fs.writeFile(credentialsFilePath, truncatedEncryptedData, 'utf-8');
+
+    // 6. Attempt to retrieve the password and verify it throws a clear, handled validation error
+    await expect(keychain.getPassword(service, account)).rejects.toThrow(
+      'Corrupted credentials file detected',
+    );
+  });
+});
@@ -175,6 +175,93 @@ describe('LoopDetectionService', () => {
      }
      expect(loggers.logLoopDetected).not.toHaveBeenCalled();
    });
+
+    it('should detect an alternating tool call loop (cycle of length 2)', () => {
+      const eventA = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_a.txt',
+      });
+      const eventB = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_b.txt',
+      });
+
+      let loopCount = 0;
+      for (let i = 0; i < 15; i++) {
+        const currentEvent = i % 2 === 0 ? eventA : eventB;
+        const result = service.addAndCheck(currentEvent);
+        if (result.count > 0) {
+          loopCount = result.count;
+        }
+      }
+
+      expect(loopCount).toBeGreaterThan(0);
+    });
+
+    it('should detect a cyclic tool call loop of length 3', () => {
+      const eventA = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_a.txt',
+      });
+      const eventB = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_b.txt',
+      });
+      const eventC = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_c.txt',
+      });
+
+      let loopCount = 0;
+      const sequence = [eventA, eventB, eventC];
+      for (let i = 0; i < 20; i++) {
+        const result = service.addAndCheck(sequence[i % 3]);
+        if (result.count > 0) {
+          loopCount = result.count;
+        }
+      }
+
+      expect(loopCount).toBeGreaterThan(0);
+    });
+
+    it('should detect a cyclic tool call loop of length 5', () => {
+      const e1 = createToolCallRequestEvent('t', { id: 1 });
+      const e2 = createToolCallRequestEvent('t', { id: 2 });
+      const e3 = createToolCallRequestEvent('t', { id: 3 });
+      const e4 = createToolCallRequestEvent('t', { id: 4 });
+      const e5 = createToolCallRequestEvent('t', { id: 5 });
+
+      let loopCount = 0;
+      const sequence = [e1, e2, e3, e4, e5];
+      for (let i = 0; i < 30; i++) {
+        const result = service.addAndCheck(sequence[i % 5]);
+        if (result.count > 0) {
+          loopCount = result.count;
+        }
+      }
+
+      expect(loopCount).toBeGreaterThan(0);
+    });
+
+    it('should not detect loops for non-looping alternating sequences that vary', () => {
+      const eventA = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_a.txt',
+      });
+      const eventB = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_b.txt',
+      });
+      const eventC = createToolCallRequestEvent('read_file', {
+        file_path: 'loop_c.txt',
+      });
+
+      // Run some alternating calls, then break the pattern with eventC
+      for (let i = 0; i < 4; i++) {
+        expect(service.addAndCheck(i % 2 === 0 ? eventA : eventB).count).toBe(
+          0,
+        );
+      }
+      expect(service.addAndCheck(eventC).count).toBe(0);
+      for (let i = 0; i < 4; i++) {
+        expect(service.addAndCheck(i % 2 === 0 ? eventA : eventB).count).toBe(
+          0,
+        );
+      }
+    });
  });

  describe('Content Loop Detection', () => {
@@ -136,8 +136,7 @@ export class LoopDetectionService {
  private userPrompt = '';

  // Tool call tracking
-  private lastToolCallKey: string | null = null;
-  private toolCallRepetitionCount: number = 0;
+  private toolCallHistory: string[] = [];

  // Content streaming tracking
  private streamContentHistory = '';
@@ -313,15 +312,39 @@ export class LoopDetectionService {

  private checkToolCallLoop(toolCall: { name: string; args: object }): boolean {
    const key = this.getToolCallKey(toolCall);
-    if (this.lastToolCallKey === key) {
-      this.toolCallRepetitionCount++;
-    } else {
-      this.lastToolCallKey = key;
-      this.toolCallRepetitionCount = 1;
+    this.toolCallHistory.push(key);
+
+    const maxRequiredLength = 5 * TOOL_CALL_LOOP_THRESHOLD;
+    if (this.toolCallHistory.length > maxRequiredLength) {
+      this.toolCallHistory = this.toolCallHistory.slice(-maxRequiredLength);
    }
-    if (this.toolCallRepetitionCount >= TOOL_CALL_LOOP_THRESHOLD) {
-      return true;
+
+    const n = this.toolCallHistory.length;
+    const R = TOOL_CALL_LOOP_THRESHOLD; // 5
+
+    // Check for repeating patterns of cycle length k from 1 to 5
+    for (let k = 1; k <= 5; k++) {
+      const requiredLength = k * R;
+      if (n >= requiredLength) {
+        const cycle = this.toolCallHistory.slice(-k);
+        let isPatternMatch = true;
+
+        for (let i = 0; i < requiredLength; i++) {
+          const indexFromEnd = requiredLength - i;
+          const actualKey = this.toolCallHistory[n - indexFromEnd];
+          const expectedKey = cycle[i % k];
+          if (actualKey !== expectedKey) {
+            isPatternMatch = false;
+            break;
+          }
+        }
+
+        if (isPatternMatch) {
+          return true;
+        }
+      }
    }
+
    return false;
  }

@@ -739,8 +762,7 @@ export class LoopDetectionService {
  }

  private resetToolCallCount(): void {
-    this.lastToolCallKey = null;
-    this.toolCallRepetitionCount = 0;
+    this.toolCallHistory = [];
  }

  private resetContentTracking(resetHistory = true): void {
@@ -37,6 +37,9 @@ export interface ModelConfigKey {
  // Indicates whether this request originates from the primary interactive chat model.
  // Enables the default fallback configuration to `chat-base` when unknown.
  isChatModel?: boolean;
+
+  // The last stream error that triggered this retry attempt, if any.
+  lastStreamError?: unknown;
 }

 export interface ModelConfig {
@@ -139,6 +139,7 @@ export interface ShellExecutionConfig {
  backgroundCompletionBehavior?: 'inject' | 'notify' | 'silent';
  originalCommand?: string;
  sessionId?: string;
+  env?: Record<string, string>;
 }

 /**
@@ -461,9 +462,10 @@ export class ShellExecutionService {
    const spawnArgs = [...argsPrefix, finalCommand];

    // 2. Prepare Environment
+    const sourceEnv = shellExecutionConfig.env ?? process.env;
    const gitConfigKeys: string[] = [];
    if (!isInteractive) {
-      for (const key in process.env) {
+      for (const key in sourceEnv) {
        if (key.startsWith('GIT_CONFIG_')) {
          gitConfigKeys.push(key);
        }
@@ -479,7 +481,7 @@ export class ShellExecutionService {
      ],
    };

-    const sanitizedEnv = sanitizeEnvironment(process.env, sanitizationConfig);
+    const sanitizedEnv = sanitizeEnvironment(sourceEnv, sanitizationConfig);

    const baseEnv: Record<string, string | undefined> = {
      ...sanitizedEnv,
@@ -493,7 +495,7 @@ export class ShellExecutionService {
    if (!isInteractive) {
      // Ensure all GIT_CONFIG_* variables are preserved even if they were redacted
      for (const key of gitConfigKeys) {
-        baseEnv[key] = process.env[key];
+        baseEnv[key] = sourceEnv[key];
      }

      const gitConfigCount = parseInt(baseEnv['GIT_CONFIG_COUNT'] || '0', 10);
@@ -173,6 +173,7 @@ describe('UiTelemetryService', () => {
          totalRequests: 1,
          totalErrors: 0,
          totalLatencyMs: 500,
+          errorsByType: {},
        },
        tokens: {
          input: 5,
@@ -229,6 +230,7 @@ describe('UiTelemetryService', () => {
          totalRequests: 2,
          totalErrors: 0,
          totalLatencyMs: 1100,
+          errorsByType: {},
        },
        tokens: {
          input: 10,
@@ -305,6 +307,9 @@ describe('UiTelemetryService', () => {
          totalRequests: 1,
          totalErrors: 1,
          totalLatencyMs: 300,
+          errorsByType: {
+            UNKNOWN: 1,
+          },
        },
        tokens: {
          input: 0,
@@ -319,6 +324,42 @@ describe('UiTelemetryService', () => {
      });
    });

+    it('should track errors by error_type distinctly', () => {
+      const event1 = {
+        'event.name': EVENT_API_ERROR,
+        model: 'gemini-2.5-pro',
+        duration_ms: 200,
+        error: 'Empty response',
+        error_type: 'NO_RESPONSE_TEXT',
+      } as unknown as ApiErrorEvent & { 'event.name': typeof EVENT_API_ERROR };
+
+      const event2 = {
+        'event.name': EVENT_API_ERROR,
+        model: 'gemini-2.5-pro',
+        duration_ms: 250,
+        error: 'Malformed JSON',
+        error_type: 'MALFORMED_FUNCTION_CALL',
+      } as unknown as ApiErrorEvent & { 'event.name': typeof EVENT_API_ERROR };
+
+      const event3 = {
+        'event.name': EVENT_API_ERROR,
+        model: 'gemini-2.5-pro',
+        duration_ms: 100,
+        error: 'Another empty response',
+        error_type: 'NO_RESPONSE_TEXT',
+      } as unknown as ApiErrorEvent & { 'event.name': typeof EVENT_API_ERROR };
+
+      service.addEvent(event1);
+      service.addEvent(event2);
+      service.addEvent(event3);
+
+      const metrics = service.getMetrics();
+      expect(metrics.models['gemini-2.5-pro'].api.errorsByType).toEqual({
+        NO_RESPONSE_TEXT: 2,
+        MALFORMED_FUNCTION_CALL: 1,
+      });
+    });
+
    it('should aggregate ApiErrorEvents and ApiResponseEvents', () => {
      const responseEvent = {
        'event.name': EVENT_API_RESPONSE,
@@ -351,6 +392,9 @@ describe('UiTelemetryService', () => {
          totalRequests: 2,
          totalErrors: 1,
          totalLatencyMs: 800,
+          errorsByType: {
+            UNKNOWN: 1,
+          },
        },
        tokens: {
          input: 5,
@@ -56,6 +56,7 @@ export interface ModelMetrics {
    totalRequests: number;
    totalErrors: number;
    totalLatencyMs: number;
+    errorsByType?: Record<string, number>;
  };
  tokens: {
    input: number;
@@ -110,6 +111,7 @@ const createInitialModelMetrics = (): ModelMetrics => ({
    totalRequests: 0,
    totalErrors: 0,
    totalLatencyMs: 0,
+    errorsByType: {},
  },
  tokens: {
    input: 0,
@@ -170,6 +172,23 @@ export class UiTelemetryService extends EventEmitter {
    });
  }

+  recordSemanticValidationError(model: string, errorType: string): void {
+    const modelMetrics = this.getOrCreateModelMetrics(model);
+    modelMetrics.api.totalErrors++;
+
+    if (!modelMetrics.api.errorsByType) {
+      modelMetrics.api.errorsByType = {};
+    }
+    const type = errorType || 'INVALID_STREAM';
+    modelMetrics.api.errorsByType[type] =
+      (modelMetrics.api.errorsByType[type] || 0) + 1;
+
+    this.emit('update', {
+      metrics: this.#metrics,
+      lastPromptTokenCount: this.#lastPromptTokenCount,
+    });
+  }
+
  getMetrics(): SessionMetrics {
    return this.#metrics;
  }
@@ -326,6 +345,13 @@ export class UiTelemetryService extends EventEmitter {
    modelMetrics.api.totalErrors++;
    modelMetrics.api.totalLatencyMs += event.duration_ms;

+    if (!modelMetrics.api.errorsByType) {
+      modelMetrics.api.errorsByType = {};
+    }
+    const errorType = event.error_type || 'UNKNOWN';
+    modelMetrics.api.errorsByType[errorType] =
+      (modelMetrics.api.errorsByType[errorType] || 0) + 1;
+
    if (event.role) {
      if (!modelMetrics.roles[event.role]) {
        modelMetrics.roles[event.role] = createInitialRoleMetrics();
@@ -656,6 +656,7 @@ export class ShellToolInvocation extends BaseToolInvocation<
          this.context.config.isInteractiveShellEnabled(),
          {
            ...shellExecutionConfig,
+            env: this.context.config.env,
            sessionId: this.context.config?.getSessionId?.() ?? 'default',
            pager: 'cat',
            sanitizationConfig:
@@ -4,7 +4,7 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { Config } from '../config/config.js';
 import { MessageBus } from '../confirmation-bus/message-bus.js';
 import type { PolicyEngine } from '../policy/policy-engine.js';
@@ -30,6 +30,7 @@ describe('Tracker Tools Integration', () => {

  beforeEach(async () => {
    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'tracker-tools-test-'));
+    vi.stubEnv('GEMINI_CLI_HOME', tempDir);
    config = new Config({
      sessionId: `test-session-${Math.random().toString(36).substring(7)}`,
      targetDir: tempDir,
@@ -42,6 +43,7 @@ describe('Tracker Tools Integration', () => {
  });

  afterEach(async () => {
+    vi.unstubAllEnvs();
    await fs.rm(tempDir, { recursive: true, force: true });
  });

@@ -10,3 +10,24 @@ export const REFERENCE_CONTENT_END = '--- End of content ---';
 export const DEFAULT_MAX_LINES_TEXT_FILE = 2000;
 export const MAX_LINE_LENGTH_TEXT_FILE = 2000;
 export const MAX_FILE_SIZE_MB = 20;
+
+export const EMPTY_RESPONSE_COMPRESS_SUGGESTION =
+  'The model returned an empty text response. If your context window is near capacity, try using /compress.';
+
+export const THINKING_ONLY_COMPRESS_SUGGESTION =
+  'The model returned reasoning thoughts but no final response text. If your context window is near capacity, try using /compress.';
+
+export const MAX_TOKENS_EXCEEDED_SUGGESTION =
+  'Model response was truncated because it exceeded the token limit. Try using /compress to free up context space.';
+
+export const SAFETY_BLOCKED_MESSAGE =
+  'The model response was blocked due to safety settings.';
+
+export const RECITATION_BLOCKED_MESSAGE =
+  'The model response was blocked due to recitation/copyright filters.';
+
+export const OTHER_BLOCKED_MESSAGE =
+  'The model response was blocked due to other policy settings.';
+
+export const TRUE_EMPTY_RESPONSE_MESSAGE =
+  'The model returned an empty response with no text or thoughts. This may be a transient API issue; please try again.';
@@ -39,6 +39,10 @@ vi.mock('child_process', () => ({
  spawnSync: vi.fn(() => ({ error: null, status: 0 })),
 }));

+vi.mock('./headless.js', () => ({
+  isHeadlessMode: vi.fn(() => false),
+}));
+
 const originalPlatform = process.platform;

 describe('editor utils', () => {
@@ -9,6 +9,7 @@ import { promisify } from 'node:util';
 import { once } from 'node:events';
 import { debugLogger } from './debugLogger.js';
 import { coreEvents, CoreEvent, type EditorSelectedPayload } from './events.js';
+import { isHeadlessMode } from './headless.js';

 const GUI_EDITORS = [
  'vscode',
@@ -404,6 +405,13 @@ export async function openDiff(
  newPath: string,
  editor: EditorType,
 ): Promise<void> {
+  if (isHeadlessMode()) {
+    debugLogger.warn(
+      'External editor spawning is disabled in headless/server mode.',
+    );
+    return;
+  }
+
  const diffCommand = getDiffCommand(oldPath, newPath, editor);
  if (!diffCommand) {
    debugLogger.error('No diff tool available. Install a supported editor.');
@@ -107,6 +107,63 @@ describe('classifyGoogleError', () => {
    expect((result as RetryableQuotaError).retryDelayMs).toBe(9000);
  });

+  it('should return TerminalQuotaError for MODEL_CAPACITY_EXHAUSTED when no retry delay is specified', () => {
+    const apiError: GoogleApiError = {
+      code: 429,
+      message:
+        'No capacity available for model gemini-3.1-pro-preview on the server',
+      details: [
+        {
+          '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+          reason: 'MODEL_CAPACITY_EXHAUSTED',
+          domain: 'cloudcode-pa.googleapis.com',
+          metadata: { model: 'gemini-3.1-pro-preview' },
+        },
+      ],
+    };
+    vi.spyOn(errorParser, 'parseGoogleApiError').mockReturnValue(apiError);
+    const result = classifyGoogleError(new Error());
+    expect(result).toBeInstanceOf(TerminalQuotaError);
+  });
+
+  it('should return TerminalQuotaError for MODEL_CAPACITY_EXHAUSTED even when the domain is not a Cloud Code domain (domain-agnostic)', () => {
+    const apiError: GoogleApiError = {
+      code: 429,
+      message:
+        'No capacity available for model gemini-3.1-pro-preview on the server',
+      details: [
+        {
+          '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+          reason: 'MODEL_CAPACITY_EXHAUSTED',
+          domain: 'other.googleapis.com',
+          metadata: { model: 'gemini-3.1-pro-preview' },
+        },
+      ],
+    };
+    vi.spyOn(errorParser, 'parseGoogleApiError').mockReturnValue(apiError);
+    const result = classifyGoogleError(new Error());
+    expect(result).toBeInstanceOf(TerminalQuotaError);
+  });
+
+  it('should return TerminalQuotaError for MODEL_CAPACITY_EXCEEDED when no retry delay is specified', () => {
+    const apiError: GoogleApiError = {
+      code: 429,
+      message:
+        'No capacity available for model gemini-3.1-pro-preview on the server',
+      details: [
+        {
+          '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+          reason: 'MODEL_CAPACITY_EXCEEDED',
+          domain: 'cloudcode-pa.googleapis.com',
+          metadata: { model: 'gemini-3.1-pro-preview' },
+        },
+      ],
+    };
+    vi.spyOn(errorParser, 'parseGoogleApiError').mockReturnValue(apiError);
+    const result = classifyGoogleError(new Error());
+    expect(result).toBeInstanceOf(TerminalQuotaError);
+  });
+
  it('should return original error if code is not 429, 499 or 503', () => {
    const apiError: GoogleApiError = {
      code: 500,
@@ -330,6 +330,23 @@ export function classifyGoogleError(error: unknown): unknown {
      );
    }

+    if (
+      errorInfo.reason === 'MODEL_CAPACITY_EXHAUSTED' ||
+      errorInfo.reason === 'MODEL_CAPACITY_EXCEEDED'
+    ) {
+      // If no server backoff delay is specified, treat capacity exhaustion as a terminal error
+      // to trigger immediate model fallback without retrying on the same exhausted model.
+      if (delaySeconds === undefined) {
+        return new TerminalQuotaError(
+          googleApiError.message,
+          googleApiError,
+          delaySeconds,
+          errorInfo.reason,
+        );
+      }
+      // Otherwise, fall through to RetryableQuotaError to honor the server's requested delay.
+    }
+
    // New Cloud Code API quota handling
    if (errorInfo.domain) {
      if (isCloudCodeDomain(errorInfo.domain)) {
@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { isFunctionResponse, isFunctionCall } from './messageInspectors.js';
+
+describe('messageInspectors', () => {
+  describe('isFunctionResponse', () => {
+    it('should return false if content role is not user', () => {
+      const content = {
+        role: 'model',
+        parts: [
+          {
+            functionResponse: {
+              name: 'test_tool',
+              response: { success: true },
+            },
+          },
+        ],
+      };
+      expect(isFunctionResponse(content)).toBe(false);
+    });
+
+    it('should return false if content has no parts', () => {
+      const content = {
+        role: 'user',
+      };
+      expect(isFunctionResponse(content)).toBe(false);
+    });
+
+    it('should return false if parts are empty', () => {
+      const content = {
+        role: 'user',
+        parts: [],
+      };
+      expect(isFunctionResponse(content)).toBe(false);
+    });
+
+    it('should return false if none of the parts is a functionResponse', () => {
+      const content = {
+        role: 'user',
+        parts: [
+          {
+            text: 'Hello world',
+          },
+          {
+            fileData: {
+              mimeType: 'image/png',
+              fileUri: 'https://example.com/image.png',
+            },
+          },
+        ],
+      };
+      expect(isFunctionResponse(content)).toBe(false);
+    });
+
+    it('should return true if all parts are functionResponses', () => {
+      const content = {
+        role: 'user',
+        parts: [
+          {
+            functionResponse: {
+              name: 'test_tool_1',
+              response: { success: true },
+            },
+          },
+          {
+            functionResponse: {
+              name: 'test_tool_2',
+              response: { value: 42 },
+            },
+          },
+        ],
+      };
+      expect(isFunctionResponse(content)).toBe(true);
+    });
+
+    it('should return true if content is a mixed multimodal tool response containing functionResponse and sibling parts', () => {
+      const content = {
+        role: 'user',
+        parts: [
+          {
+            functionResponse: {
+              name: 'test_tool',
+              response: { success: true },
+            },
+          },
+          {
+            fileData: {
+              mimeType: 'image/png',
+              fileUri: 'https://example.com/image.png',
+            },
+          },
+        ],
+      };
+      expect(isFunctionResponse(content)).toBe(true);
+    });
+  });
+
+  describe('isFunctionCall', () => {
+    it('should return false if content role is not model', () => {
+      const content = {
+        role: 'user',
+        parts: [
+          {
+            functionCall: {
+              name: 'test_tool',
+              args: {},
+            },
+          },
+        ],
+      };
+      expect(isFunctionCall(content)).toBe(false);
+    });
+
+    it('should return false if content has no parts', () => {
+      const content = {
+        role: 'model',
+      };
+      expect(isFunctionCall(content)).toBe(false);
+    });
+
+    it('should return false if parts are empty', () => {
+      const content = {
+        role: 'model',
+        parts: [],
+      };
+      expect(isFunctionCall(content)).toBe(false);
+    });
+
+    it('should return false if none of the parts is a functionCall', () => {
+      const content = {
+        role: 'model',
+        parts: [
+          {
+            text: 'I am thinking...',
+          },
+        ],
+      };
+      expect(isFunctionCall(content)).toBe(false);
+    });
+
+    it('should return true if all parts are functionCalls', () => {
+      const content = {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'test_tool_1',
+              args: {},
+            },
+          },
+          {
+            functionCall: {
+              name: 'test_tool_2',
+              args: { query: 'foo' },
+            },
+          },
+        ],
+      };
+      expect(isFunctionCall(content)).toBe(true);
+    });
+  });
+});
@@ -10,7 +10,7 @@ export function isFunctionResponse(content: Content): boolean {
  return (
    content.role === 'user' &&
    !!content.parts &&
-    content.parts.every((part) => !!part.functionResponse)
+    content.parts.some((part) => !!part.functionResponse)
  );
 }

@@ -18,6 +18,7 @@ export function isFunctionCall(content: Content): boolean {
  return (
    content.role === 'model' &&
    !!content.parts &&
+    content.parts.length > 0 &&
    content.parts.every((part) => !!part.functionCall)
  );
 }
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli-devtools",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "license": "Apache-2.0",
  "type": "module",
  "main": "dist/src/index.js",
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli-sdk",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "description": "Gemini CLI SDK",
  "license": "Apache-2.0",
  "repository": {
@@ -1,6 +1,6 @@
 {
  "name": "@google/gemini-cli-test-utils",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "private": true,
  "main": "src/index.ts",
  "license": "Apache-2.0",
@@ -2,7 +2,7 @@
  "name": "gemini-cli-vscode-ide-companion",
  "displayName": "Gemini CLI Companion",
  "description": "Enable Gemini CLI with direct access to your IDE workspace.",
-  "version": "0.52.0",
+  "version": "0.54.1",
  "publisher": "google",
  "icon": "assets/icon.png",
  "repository": {
@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { collectInventory } from './utils/eval-inventory.js';
+import { buildToolRegistry } from './utils/tool-registry.js';
+import {
+  computeCoverage,
+  formatCoverageReport,
+} from './utils/eval-coverage.js';
+
+async function main() {
+  const rootFlagIndex = process.argv.indexOf('--root');
+  const rootFlagValue =
+    rootFlagIndex !== -1 ? process.argv[rootFlagIndex + 1] : undefined;
+
+  if (rootFlagIndex !== -1 && rootFlagValue === undefined) {
+    console.error(
+      'Error: --root requires a directory path argument but none was provided.',
+    );
+    process.exit(1);
+  }
+  if (rootFlagValue && rootFlagValue.startsWith('--')) {
+    console.error(
+      `Error: --root value "${rootFlagValue}" looks like a flag. Provide a valid directory path.`,
+    );
+    process.exit(1);
+  }
+
+  const repoRoot = rootFlagValue ?? process.cwd();
+  const inventory = await collectInventory(repoRoot);
+
+  if (inventory.totalFiles === 0) {
+    console.error('No eval files found under evals/.');
+    process.exit(1);
+  }
+
+  const registry = buildToolRegistry();
+  const result = computeCoverage(inventory, registry);
+
+  console.log(formatCoverageReport(result));
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
@@ -0,0 +1,510 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  computeCoverage,
+  formatCoverageReport,
+  type CoverageResult,
+  type CoveredToolEntry,
+} from '../utils/eval-coverage.js';
+import { buildToolRegistry } from '../utils/tool-registry.js';
+import { collectInventory } from '../utils/eval-inventory.js';
+import type { InventoryResult } from '../utils/eval-inventory.js';
+import type {
+  EvalCaseRecord,
+  EvalFileAnalysis,
+} from '../utils/eval-analysis.js';
+
+function makeCase(overrides: Partial<EvalCaseRecord> = {}): EvalCaseRecord {
+  return {
+    filePath: '/repo/evals/test.eval.ts',
+    relativePath: 'evals/test.eval.ts',
+    helperName: 'evalTest',
+    baseHelperName: 'evalTest',
+    policy: 'USUALLY_PASSES',
+    name: 'test case',
+    hasFiles: false,
+    hasPrompt: true,
+    toolReferences: [],
+    location: { line: 1, column: 1 },
+    ...overrides,
+  };
+}
+
+function makeInventory(
+  cases: EvalCaseRecord[],
+  overrides: Partial<InventoryResult> = {},
+): InventoryResult {
+  return {
+    totalFiles: 1,
+    totalCases: cases.length,
+    repoRoot: '/repo',
+    files: [] as EvalFileAnalysis[],
+    cases,
+    diagnostics: [],
+    ...overrides,
+  };
+}
+
+describe('eval-coverage', () => {
+  const registry = buildToolRegistry();
+
+  describe('computeCoverage', () => {
+    it('reports totals consistently with registry', () => {
+      const result = computeCoverage(makeInventory([]), registry);
+
+      expect(result.totalTools).toBe(registry.totalTools);
+      expect(result.coveredCount + result.uncoveredCount).toBe(
+        result.totalTools,
+      );
+    });
+
+    it('marks all tools uncovered when inventory is empty', () => {
+      const result = computeCoverage(makeInventory([]), registry);
+
+      expect(result.coveredCount).toBe(0);
+      expect(result.uncoveredCount).toBe(registry.totalTools);
+      expect(result.covered).toEqual([]);
+      expect(result.coveragePercent).toBe(0);
+    });
+
+    it('marks all tools uncovered when no eval case has tool references', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({ toolReferences: [] }),
+          makeCase({ name: 'another', toolReferences: [] }),
+        ]),
+        registry,
+      );
+
+      expect(result.coveredCount).toBe(0);
+      expect(result.uncoveredCount).toBe(registry.totalTools);
+    });
+
+    it('marks a single referenced tool as covered', () => {
+      const result = computeCoverage(
+        makeInventory([makeCase({ toolReferences: ['grep_search'] })]),
+        registry,
+      );
+
+      expect(result.coveredCount).toBe(1);
+      expect(result.covered[0].name).toBe('grep_search');
+      expect(result.covered[0].totalCaseCount).toBe(1);
+    });
+
+    it('counts multiple cases referencing the same tool', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({
+            relativePath: 'evals/a.eval.ts',
+            toolReferences: ['grep_search'],
+          }),
+          makeCase({
+            relativePath: 'evals/a.eval.ts',
+            toolReferences: ['grep_search'],
+          }),
+          makeCase({
+            relativePath: 'evals/b.eval.ts',
+            toolReferences: ['grep_search'],
+          }),
+        ]),
+        registry,
+      );
+
+      const grepEntry = result.covered.find((t) => t.name === 'grep_search');
+      expect(grepEntry).toBeDefined();
+      expect(grepEntry!.totalCaseCount).toBe(3);
+      expect(grepEntry!.files).toHaveLength(2);
+    });
+
+    it('correctly builds per-file case counts', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({
+            relativePath: 'evals/file-a.eval.ts',
+            toolReferences: ['glob'],
+          }),
+          makeCase({
+            relativePath: 'evals/file-a.eval.ts',
+            toolReferences: ['glob'],
+          }),
+          makeCase({
+            relativePath: 'evals/file-b.eval.ts',
+            toolReferences: ['glob'],
+          }),
+        ]),
+        registry,
+      );
+
+      const globEntry = result.covered.find((t) => t.name === 'glob');
+      expect(globEntry).toBeDefined();
+
+      const fileA = globEntry!.files.find(
+        (f) => f.relativePath === 'evals/file-a.eval.ts',
+      );
+      const fileB = globEntry!.files.find(
+        (f) => f.relativePath === 'evals/file-b.eval.ts',
+      );
+
+      expect(fileA?.caseCount).toBe(2);
+      expect(fileB?.caseCount).toBe(1);
+    });
+
+    it('computes correct policy distribution per tool', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({
+            policy: 'ALWAYS_PASSES',
+            toolReferences: ['read_file'],
+          }),
+          makeCase({
+            policy: 'USUALLY_PASSES',
+            toolReferences: ['read_file'],
+          }),
+          makeCase({
+            policy: 'USUALLY_PASSES',
+            toolReferences: ['read_file'],
+          }),
+        ]),
+        registry,
+      );
+
+      const readEntry = result.covered.find((t) => t.name === 'read_file');
+      expect(readEntry).toBeDefined();
+      expect(readEntry!.policyDistribution.ALWAYS_PASSES).toBe(1);
+      expect(readEntry!.policyDistribution.USUALLY_PASSES).toBe(2);
+      expect(readEntry!.policyDistribution.USUALLY_FAILS).toBeUndefined();
+    });
+
+    it('handles a case referencing multiple tools', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({
+            toolReferences: ['glob', 'grep_search', 'read_file'],
+          }),
+        ]),
+        registry,
+      );
+
+      const names = result.covered.map((t) => t.name);
+      expect(names).toContain('glob');
+      expect(names).toContain('grep_search');
+      expect(names).toContain('read_file');
+      expect(result.coveredCount).toBe(3);
+    });
+
+    it('resolves legacy aliases to canonical names', () => {
+      const result = computeCoverage(
+        makeInventory([makeCase({ toolReferences: ['search_file_content'] })]),
+        registry,
+      );
+
+      const names = result.covered.map((t) => t.name);
+      expect(names).toContain('grep_search');
+      expect(names).not.toContain('search_file_content');
+    });
+
+    it('ignores unrecognized tool names silently', () => {
+      const result = computeCoverage(
+        makeInventory([makeCase({ toolReferences: ['nonexistent_tool_xyz'] })]),
+        registry,
+      );
+
+      expect(result.covered.map((t) => t.name)).not.toContain(
+        'nonexistent_tool_xyz',
+      );
+      expect(result.coveredCount).toBe(0);
+    });
+
+    it('sorts covered tools alphabetically', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({ toolReferences: ['write_file'] }),
+          makeCase({ toolReferences: ['glob'] }),
+          makeCase({ toolReferences: ['grep_search'] }),
+        ]),
+        registry,
+      );
+
+      const names = result.covered.map((t) => t.name);
+      expect(names).toEqual([...names].sort());
+    });
+
+    it('sorts uncovered tools alphabetically', () => {
+      const result = computeCoverage(makeInventory([]), registry);
+      const names = result.uncovered.map((t) => t.name);
+      expect(names).toEqual([...names].sort());
+    });
+
+    it('sorts files within a covered entry alphabetically', () => {
+      const result = computeCoverage(
+        makeInventory([
+          makeCase({
+            relativePath: 'evals/z-last.eval.ts',
+            toolReferences: ['glob'],
+          }),
+          makeCase({
+            relativePath: 'evals/a-first.eval.ts',
+            toolReferences: ['glob'],
+          }),
+        ]),
+        registry,
+      );
+
+      const globEntry = result.covered.find((t) => t.name === 'glob')!;
+      expect(globEntry.files[0].relativePath).toBe('evals/a-first.eval.ts');
+      expect(globEntry.files[1].relativePath).toBe('evals/z-last.eval.ts');
+    });
+
+    it('computes coverage percent correctly', () => {
+      const totalTools = registry.totalTools;
+      const halfTools = [...registry.tools.keys()].slice(
+        0,
+        Math.floor(totalTools / 2),
+      );
+      const cases = halfTools.map((name) =>
+        makeCase({ toolReferences: [name] }),
+      );
+
+      const result = computeCoverage(makeInventory(cases), registry);
+
+      const expected = Math.round((halfTools.length / totalTools) * 1000) / 10;
+      expect(result.coveragePercent).toBe(expected);
+    });
+
+    it('coveragePercent is 0 for empty inventory', () => {
+      const result = computeCoverage(makeInventory([]), registry);
+      expect(result.coveragePercent).toBe(0);
+    });
+
+    it('resolves absolute diagnostic file paths to relative paths', () => {
+      const diagnostic = {
+        severity: 'warning' as const,
+        message: 'Could not resolve policy',
+        filePath: '/repo/evals/bad.eval.ts',
+        location: { line: 5, column: 3 },
+      };
+      const result = computeCoverage(
+        makeInventory([], { diagnostics: [diagnostic], repoRoot: '/repo' }),
+        registry,
+      );
+
+      expect(result.diagnostics).toHaveLength(1);
+      expect(result.diagnostics[0]).toMatchObject({
+        severity: 'warning',
+        message: 'Could not resolve policy',
+        filePath: 'evals/bad.eval.ts',
+        location: { line: 5, column: 3 },
+      });
+    });
+  });
+
+  describe('formatCoverageReport', () => {
+    function makeCoverageResult(
+      overrides: Partial<CoverageResult> = {},
+    ): CoverageResult {
+      return {
+        totalTools: 26,
+        coveredCount: 0,
+        uncoveredCount: 26,
+        coveragePercent: 0,
+        covered: [],
+        uncovered: [],
+        diagnostics: [],
+        ...overrides,
+      };
+    }
+
+    it('includes the title and summary line', () => {
+      const result = makeCoverageResult({
+        totalTools: 26,
+        coveredCount: 10,
+        uncoveredCount: 16,
+        coveragePercent: 38.5,
+      });
+
+      const report = formatCoverageReport(result);
+
+      expect(report).toContain('Eval Coverage Report');
+      expect(report).toContain('10 / 26 tools covered (38.5%)');
+    });
+
+    it('includes Covered Tools section header', () => {
+      const report = formatCoverageReport(makeCoverageResult());
+      expect(report).toContain('Covered Tools');
+    });
+
+    it('includes Uncovered Tools section header', () => {
+      const report = formatCoverageReport(makeCoverageResult());
+      expect(report).toContain('Uncovered Tools');
+    });
+
+    it('shows (none) when no tools are covered', () => {
+      const report = formatCoverageReport(makeCoverageResult());
+      expect(report).toContain('(none)');
+    });
+
+    it('shows full-coverage message when all tools are covered', () => {
+      const result = makeCoverageResult({
+        coveredCount: 26,
+        uncoveredCount: 0,
+        uncovered: [],
+      });
+      const report = formatCoverageReport(result);
+      expect(report).toContain('(none — full coverage!)');
+    });
+
+    it('lists covered tools with case and file counts', () => {
+      const coveredEntry: CoveredToolEntry = {
+        name: 'grep_search',
+        category: 'file-system',
+        totalCaseCount: 5,
+        files: [
+          {
+            relativePath: 'evals/grep_search_functionality.eval.ts',
+            caseCount: 5,
+            policyDistribution: { USUALLY_PASSES: 5 },
+          },
+        ],
+        policyDistribution: { USUALLY_PASSES: 5 },
+      };
+
+      const result = makeCoverageResult({
+        coveredCount: 1,
+        uncoveredCount: 25,
+        covered: [coveredEntry],
+      });
+
+      const report = formatCoverageReport(result);
+
+      expect(report).toContain('grep_search');
+      expect(report).toContain('5 cases');
+      expect(report).toContain('1 file');
+      expect(report).toContain('evals/grep_search_functionality.eval.ts');
+      expect(report).toContain('5 USUALLY_PASSES');
+    });
+
+    it('groups uncovered tools by category', () => {
+      const result = makeCoverageResult({
+        uncovered: [
+          { name: 'web_fetch', category: 'web' },
+          { name: 'google_web_search', category: 'web' },
+          { name: 'glob', category: 'file-system' },
+        ],
+      });
+
+      const report = formatCoverageReport(result);
+
+      expect(report).toContain('[web]');
+      expect(report).toContain('[file-system]');
+      expect(report).toContain('web_fetch');
+      expect(report).toContain('google_web_search');
+      expect(report).toContain('glob');
+    });
+
+    it('does not crash when a tool has an undefined category', () => {
+      const result = makeCoverageResult({
+        uncovered: [
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          { name: 'mystery_tool', category: undefined as any },
+        ],
+      });
+
+      expect(() => formatCoverageReport(result)).not.toThrow();
+      const report = formatCoverageReport(result);
+      expect(report).toContain('mystery_tool');
+    });
+
+    it('shows diagnostics section when diagnostics exist', () => {
+      const result = makeCoverageResult({
+        diagnostics: [
+          {
+            severity: 'warning',
+            message: 'Could not resolve policy',
+            filePath: 'evals/bad.eval.ts',
+            location: { line: 5, column: 3 },
+          },
+        ],
+      });
+
+      const report = formatCoverageReport(result);
+
+      expect(report).toContain('Diagnostics');
+      expect(report).toContain('⚠');
+      expect(report).toContain('Could not resolve policy');
+    });
+
+    it('omits diagnostics section when there are no diagnostics', () => {
+      const result = makeCoverageResult({ diagnostics: [] });
+      const report = formatCoverageReport(result);
+      expect(report).not.toContain('Diagnostics');
+      expect(report).not.toContain('⚠');
+    });
+
+    it('shows policy distribution inside file entries', () => {
+      const coveredEntry: CoveredToolEntry = {
+        name: 'glob',
+        category: 'file-system',
+        totalCaseCount: 3,
+        files: [
+          {
+            relativePath: 'evals/frugal.eval.ts',
+            caseCount: 3,
+            policyDistribution: {
+              ALWAYS_PASSES: 1,
+              USUALLY_PASSES: 2,
+            },
+          },
+        ],
+        policyDistribution: { ALWAYS_PASSES: 1, USUALLY_PASSES: 2 },
+      };
+
+      const result = makeCoverageResult({
+        coveredCount: 1,
+        covered: [coveredEntry],
+      });
+
+      const report = formatCoverageReport(result);
+
+      expect(report).toContain('1 ALWAYS_PASSES');
+      expect(report).toContain('2 USUALLY_PASSES');
+    });
+  });
+
+  describe('integration — real evals directory', () => {
+    it('produces a valid coverage result from the real eval suite', async () => {
+      const repoRoot = path.resolve(import.meta.dirname, '../../');
+      const inventory = await collectInventory(repoRoot);
+      const result = computeCoverage(inventory, registry);
+
+      expect(result.totalTools).toBe(registry.totalTools);
+      expect(result.coveredCount + result.uncoveredCount).toBe(
+        result.totalTools,
+      );
+      expect(result.coveragePercent).toBeGreaterThanOrEqual(0);
+      expect(result.coveragePercent).toBeLessThanOrEqual(100);
+      expect(result.coveredCount).toBeGreaterThanOrEqual(5);
+
+      const grepEntry = result.covered.find((t) => t.name === 'grep_search');
+      expect(grepEntry).toBeDefined();
+      expect(grepEntry!.totalCaseCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('formats the real coverage report without throwing', async () => {
+      const repoRoot = path.resolve(import.meta.dirname, '../../');
+      const inventory = await collectInventory(repoRoot);
+      const result = computeCoverage(inventory, registry);
+      const report = formatCoverageReport(result);
+
+      expect(typeof report).toBe('string');
+      expect(report).toContain('Eval Coverage Report');
+      expect(report).toContain('Covered Tools');
+      expect(report).toContain('Uncovered Tools');
+    });
+  });
+});
@@ -0,0 +1,294 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'node:path';
+import type { EvalAnalysisDiagnostic, EvalPolicy } from './eval-analysis.js';
+import type { InventoryResult } from './eval-inventory.js';
+import { type ToolCategory, type ToolRegistry } from './tool-registry.js';
+
+const POLICY_ORDER: EvalPolicy[] = [
+  'ALWAYS_PASSES',
+  'USUALLY_PASSES',
+  'USUALLY_FAILS',
+  'unknown',
+];
+
+const CATEGORY_ORDER: ToolCategory[] = [
+  'file-system',
+  'shell',
+  'web',
+  'planning',
+  'user-interaction',
+  'skills',
+  'task-tracker',
+  'agent',
+  'mcp',
+];
+
+export type PolicyDistribution = Partial<Record<EvalPolicy, number>>;
+
+export interface ToolEvalFileEntry {
+  relativePath: string;
+  caseCount: number;
+  policyDistribution: PolicyDistribution;
+}
+
+export interface CoveredToolEntry {
+  name: string;
+  category: ToolCategory;
+  totalCaseCount: number;
+  files: ToolEvalFileEntry[];
+  policyDistribution: PolicyDistribution;
+}
+
+export interface UncoveredToolEntry {
+  name: string;
+  category: ToolCategory;
+}
+
+export interface CoverageResult {
+  totalTools: number;
+  coveredCount: number;
+  uncoveredCount: number;
+  coveragePercent: number;
+  covered: CoveredToolEntry[];
+  uncovered: UncoveredToolEntry[];
+  diagnostics: readonly EvalAnalysisDiagnostic[];
+}
+
+/**
+ * Computes eval coverage by cross-referencing the inventory's tool references
+ * against the tool registry.
+ */
+export function computeCoverage(
+  inventory: InventoryResult,
+  registry: ToolRegistry,
+): CoverageResult {
+  const toolFileMap = new Map<
+    string,
+    Map<string, { caseCount: number; policyDist: PolicyDistribution }>
+  >();
+
+  for (const toolName of registry.tools.keys()) {
+    toolFileMap.set(toolName, new Map());
+  }
+
+  for (const evalCase of inventory.cases) {
+    for (const toolName of evalCase.toolReferences) {
+      const canonicalName = registry.aliasLookup.get(toolName) ?? toolName;
+      if (!registry.tools.has(canonicalName)) {
+        continue;
+      }
+
+      let fileMap = toolFileMap.get(canonicalName);
+      if (!fileMap) {
+        fileMap = new Map();
+        toolFileMap.set(canonicalName, fileMap);
+      }
+
+      const existingEntry = fileMap.get(evalCase.relativePath);
+      if (existingEntry) {
+        existingEntry.caseCount += 1;
+        existingEntry.policyDist[evalCase.policy] =
+          (existingEntry.policyDist[evalCase.policy] ?? 0) + 1;
+      } else {
+        const policyDist: PolicyDistribution = {};
+        policyDist[evalCase.policy] = 1;
+        fileMap.set(evalCase.relativePath, { caseCount: 1, policyDist });
+      }
+    }
+  }
+
+  const covered: CoveredToolEntry[] = [];
+  const uncovered: UncoveredToolEntry[] = [];
+
+  for (const [toolName, fileMap] of toolFileMap) {
+    const entry = registry.tools.get(toolName);
+    if (!entry) {
+      continue;
+    }
+
+    if (fileMap.size === 0) {
+      uncovered.push({ name: toolName, category: entry.category });
+      continue;
+    }
+
+    const files: ToolEvalFileEntry[] = [];
+    const aggregateDist: PolicyDistribution = {};
+    let totalCaseCount = 0;
+
+    for (const relativePath of [...fileMap.keys()].sort()) {
+      const fileEntry = fileMap.get(relativePath)!;
+      files.push({
+        relativePath,
+        caseCount: fileEntry.caseCount,
+        policyDistribution: fileEntry.policyDist,
+      });
+      totalCaseCount += fileEntry.caseCount;
+      for (const policy of POLICY_ORDER) {
+        const count = fileEntry.policyDist[policy];
+        if (count !== undefined) {
+          aggregateDist[policy] = (aggregateDist[policy] ?? 0) + count;
+        }
+      }
+    }
+
+    covered.push({
+      name: toolName,
+      category: entry.category,
+      totalCaseCount,
+      files,
+      policyDistribution: aggregateDist,
+    });
+  }
+
+  covered.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+  uncovered.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+
+  const totalTools = registry.totalTools;
+  const coveredCount = covered.length;
+  const uncoveredCount = uncovered.length;
+  const coveragePercent =
+    totalTools === 0 ? 0 : Math.round((coveredCount / totalTools) * 1000) / 10;
+
+  const filePathLookup = new Map<string, string>();
+  for (const f of inventory.files) {
+    filePathLookup.set(f.filePath, f.relativePath);
+  }
+
+  const resolvedDiagnostics: EvalAnalysisDiagnostic[] =
+    inventory.diagnostics.map((d) => {
+      if (d.filePath === '<inline>') {
+        return d;
+      }
+      const relative = filePathLookup.get(d.filePath);
+      if (relative !== undefined) {
+        return { ...d, filePath: relative };
+      }
+      if (path.isAbsolute(d.filePath) && inventory.repoRoot) {
+        return {
+          ...d,
+          filePath: path
+            .relative(inventory.repoRoot, d.filePath)
+            .replace(/\\/g, '/'),
+        };
+      }
+      return d;
+    });
+
+  return {
+    totalTools,
+    coveredCount,
+    uncoveredCount,
+    coveragePercent,
+    covered,
+    uncovered,
+    diagnostics: resolvedDiagnostics,
+  };
+}
+
+/**
+ * Formats a CoverageResult as a human-readable report string.
+ */
+export function formatCoverageReport(result: CoverageResult): string {
+  const lines: string[] = [];
+
+  lines.push('Eval Coverage Report');
+  lines.push('════════════════════');
+  lines.push('');
+  lines.push(
+    `${result.coveredCount} / ${result.totalTools} tools covered (${result.coveragePercent}%)`,
+  );
+  lines.push('');
+
+  lines.push('Covered Tools');
+  lines.push('─────────────');
+
+  if (result.covered.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const tool of result.covered) {
+      const caseLabel = tool.totalCaseCount === 1 ? 'case' : 'cases';
+      const fileLabel = tool.files.length === 1 ? 'file' : 'files';
+      lines.push(
+        `${tool.name} (${tool.totalCaseCount} ${caseLabel} across ${tool.files.length} ${fileLabel})`,
+      );
+      for (const file of tool.files) {
+        const policyParts = formatPolicyDistribution(file.policyDistribution);
+        lines.push(`  ${file.relativePath} (${policyParts})`);
+      }
+    }
+  }
+  lines.push('');
+
+  lines.push('Uncovered Tools');
+  lines.push('───────────────');
+
+  if (result.uncovered.length === 0) {
+    lines.push('  (none — full coverage!)');
+  } else {
+    const byCategory = new Map<string, string[]>();
+    for (const tool of result.uncovered) {
+      const category = tool.category || 'unknown';
+      const group = byCategory.get(category);
+      if (group) {
+        group.push(tool.name);
+      } else {
+        byCategory.set(category, [tool.name]);
+      }
+    }
+
+    const maxCatLen = Math.max(
+      ...CATEGORY_ORDER.filter((c) => byCategory.has(c)).map((c) => c.length),
+      ...[...byCategory.keys()]
+        .filter((c) => !CATEGORY_ORDER.includes(c as ToolCategory))
+        .map((c) => c.length),
+    );
+
+    const renderCategory = (category: string) => {
+      const names = byCategory.get(category);
+      if (!names || names.length === 0) {
+        return;
+      }
+      const padded = `[${category}]`.padEnd(maxCatLen + 2);
+      lines.push(`${padded}  ${names.join(', ')}`);
+    };
+
+    for (const category of CATEGORY_ORDER) {
+      renderCategory(category);
+    }
+    for (const category of byCategory.keys()) {
+      if (!CATEGORY_ORDER.includes(category as ToolCategory)) {
+        renderCategory(category);
+      }
+    }
+  }
+  lines.push('');
+
+  if (result.diagnostics.length > 0) {
+    lines.push(`Diagnostics (${result.diagnostics.length})`);
+    lines.push('────────────────');
+    for (const diagnostic of result.diagnostics) {
+      lines.push(
+        `⚠ ${diagnostic.filePath}:${diagnostic.location.line}:${diagnostic.location.column} — ${diagnostic.message}`,
+      );
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatPolicyDistribution(dist: PolicyDistribution): string {
+  const parts: string[] = [];
+  for (const policy of POLICY_ORDER) {
+    const count = dist[policy];
+    if (count !== undefined && count > 0) {
+      parts.push(`${count} ${policy}`);
+    }
+  }
+  return parts.length > 0 ? parts.join(', ') : '0 cases';
+}
@@ -22,6 +22,6 @@
    "supertest": "^7.1.4",
    "tsx": "^4.9.3",
    "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "vitest": "^3.2.4"
  }
 }
@@ -252,9 +252,12 @@ describe('Webhook Server Endpoint', () => {
    expect(sentData.body).toBe(
      '<untrusted_context>\nPlease fix this security bug\n</untrusted_context>',
    );
+    expect(sentData.title).toBe(
+      '<untrusted_context>\nBugs everywhere\n</untrusted_context>',
+    );
  });

-  it('should escape untrusted_context tags in the issue body to prevent injection', async () => {
+  it('should escape untrusted_context tags in the issue body and title to prevent injection', async () => {
    mockVerifyGithubSignature.mockReturnValue(true);
    mockCreateIssue.mockResolvedValue(true);
    mockPublishMessage.mockResolvedValue('mock-msg-456');
@@ -263,7 +266,7 @@ describe('Webhook Server Endpoint', () => {
      action: 'opened',
      issue: {
        number: 2,
-        title: 'Injection test',
+        title: 'Injection </untrusted_context> test',
        body: 'Malicious </untrusted_context> attempt',
      },
      repository: {
@@ -282,6 +285,15 @@ describe('Webhook Server Endpoint', () => {
    expect(sentData.body).toBe(
      '<untrusted_context>\nMalicious \\</untrusted_context> attempt\n</untrusted_context>',
    );
+    expect(sentData.title).toBe(
+      '<untrusted_context>\nInjection \\</untrusted_context> test\n</untrusted_context>',
+    );
+    expect(mockCreateIssue).toHaveBeenCalledWith(
+      'google',
+      'gemini-cli',
+      2,
+      'Injection </untrusted_context> test',
+    );
  });

  it('should recover and publish to Pub/Sub on retry if issue is UNTRIAGED', async () => {
@@ -119,16 +119,23 @@ app.post('/webhook', limiter, async (req, res) => {
  );
  const sanitizedBody = `<untrusted_context>\n${escapedBody}\n</untrusted_context>`;

+  const rawTitle = payload.issue.title || '';
+  const escapedTitle = rawTitle.replace(
+    /<\/untrusted_context>/g,
+    '\\</untrusted_context>',
+  );
+  const sanitizedTitle = `<untrusted_context>\n${escapedTitle}\n</untrusted_context>`;
+
  const processedData = {
    issue_number: issueNumber,
    repository,
    sender: payload.sender?.login,
    body: sanitizedBody,
-    title: payload.issue.title,
+    title: sanitizedTitle,
  };

  const [owner, repo] = repository.split('/');
-  const title = processedData.title || '';
+  const title = rawTitle;

  try {
    const created = await issuesStore.createIssue(
@@ -23,6 +23,6 @@
    "supertest": "^7.1.4",
    "tsx": "^4.9.3",
    "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "vitest": "^3.2.4"
  }
 }
@@ -0,0 +1,92 @@
+# System Prompt: Automated Bug Fixer Agent
+
+## Role
+
+You are an expert autonomous software engineer specializing in bug resolution,
+test-driven development, and regression prevention. Your goal is to ingest a bug
+specification, apply the proposed fix to a local repository, implement
+comprehensive tests, and verify the changes.
+
+## CRITICAL EXECUTION RULES
+
+1. **MANDATORY FILE EDITS**: You MUST use file editing tools
+   (`replace_file_content`, `multi_replace_file_content`, or `write_file`) to
+   modify the files listed in
+   `workable_spec.implementation_plan.files_to_modify` and add new test
+   assertions to `workable_spec.testing_strategy.test_file`.
+2. **DO NOT STOP AFTER VIEWING OR BASELINE TESTS**: Never conclude your session
+   or end your turn after only reading files or running unmodified tests. You
+   MUST produce concrete file modifications in the local workspace.
+3. **APPLY EDITS IMMEDIATELY**: Open and view the target files, immediately
+   apply the code fixes and test assertions using file editing tools, and then
+   verify the changes using `run_command`.
+
+## Input Specification
+
+You will receive a JSON payload containing a `workable_spec`. Key fields to
+extract:
+
+- `workable_spec.implementation_plan.files_to_modify`: List of target files.
+- `workable_spec.implementation_plan.steps`: Detailed instructions for the fix.
+- `workable_spec.testing_strategy.framework`: The testing framework to use
+  (e.g., Vitest, Jest, Pytest).
+- `workable_spec.testing_strategy.test_file`: The file where tests should be
+  added/updated.
+- `workable_spec.testing_strategy.verification_steps`: Specific
+  assertions/scenarios to test.
+
+## Workflow
+
+### Phase 1: Ingestion & Validation
+
+1.  **Parse the JSON input** (`firestore_doc.json`) and extract all relevant
+    details from the `workable_spec`.
+2.  **Verify the local environment**:
+    - Confirm you are in the root of the target repository.
+    - Check if the files listed in `files_to_modify` exist.
+    - Check if the `test_file` exists. If it does not, plan to create it.
+
+### Phase 2: Implementation (MANDATORY FILE EDITS)
+
+1.  **Apply Code Changes**:
+    - Use `replace_file_content` or `write_file` to modify the files in
+      `files_to_modify` strictly following the `steps` provided.
+    - Do not refactor unrelated code. Keep changes minimal and focused on the
+      bug fix.
+2.  **Implement Tests**:
+    - Open (or create) the `test_file`.
+    - Add new test cases that align with the `verification_steps`.
+    - Ensure the tests use the specified `framework`.
+    - Make sure tests are clean, readable, and properly mock external
+      dependencies if necessary.
+
+### Phase 3: Verification & Validation
+
+1.  **Run Target Tests**: Run only the tests in `test_file` to verify the fix
+    works as expected.
+    - Do NOT run `npm run preflight`.
+    - Use the targeted test runner command, e.g. for Vitest:
+      `npx vitest run <path/to/test_file>` or
+      `npm test -w <workspace> -- <path/to/test_file>`.
+2.  **Ensure Target Test Success**: Ensure that all test cases in the target
+    test file pass cleanly with zero failures.
+3.  **Iterate on Failure**: If targeted tests fail:
+    - Analyze the error output.
+    - Correct the implementation or target test cases using file edit tools.
+    - Re-run the targeted tests.
+    - Repeat until target tests pass cleanly.
+
+### Phase 4: Reporting
+
+- Provide a summary of the changes made and list the modified files.
+- List the tests that were run and their status (pass/fail).
+- Confirm that no regression was detected.
+
+## Constraints & Safety
+
+- **DO NOT** run `git commit`, `git push`, or any command that modifies the
+  remote repository. Leave the changes in the working directory.
+- **DO NOT** modify files outside of `files_to_modify` and `test_file` unless
+  explicitly justified (e.g., package configuration updates required for the
+  test framework).
+- Ensure all new code matches the style and patterns of the existing codebase.
@@ -0,0 +1,187 @@
+# System Prompt: Code Evaluator Agent
+
+## Role
+
+You are a masterful Code Quality and Security Assurance Agent. Your role is to
+critically evaluate code changes (provided as a diff file) against a bug
+specification (provided in `example_firestore.json`) to ensure correctness,
+security, readability, and overall quality. You act as the final gatekeeper
+before code is merged.
+
+## Inputs
+
+You will have access to:
+
+1.  **`example_firestore.json`**: Contains the `workable_spec`, including the
+    bug summary, implementation plan, and testing strategy.
+2.  **`changes.diff`** (or the generated diff content): The actual code changes
+    made to resolve the issue.
+3.  **Local Repository**: The codebase where the changes have been applied.
+
+## Workflow
+
+### Phase 1: Context Gathering & Initial Review
+
+1.  **Parse the JSON input** to understand:
+    - The original bug (`workable_spec.summary.problem` and `root_cause`).
+    - The expected behavior
+      (`workable_spec.testing_strategy.expected_behavior`).
+    - The target files (`workable_spec.implementation_plan.files_to_modify`).
+2.  **Read the Diff File**: Analyze the changes applied. Verify they match the
+    target files and intent of the implementation plan.
+
+### Phase 2: Evaluation Criteria
+
+Perform a rigorous evaluation across the following dimensions:
+
+#### 1. Correctness & Bug Resolution
+
+- **Verification**: Does the diff directly address the root cause described in
+  the spec?
+- **Logic Check**: Trace the logic in the diff. Are there any off-by-one errors,
+  incorrect conditionals, or potential null pointer exceptions?
+- **Scope**: Did the changes spill over into unrelated areas? (Minimize scope
+  creep).
+- **Test Coverage**: Ensure that the tests added/modified in the diff cover all
+  `verification_steps` in the `testing_strategy`.
+
+#### 2. Security Analysis
+
+- **Input Validation**: Ensure any new inputs or parsed data are validated.
+- **Regex Security**: If regex is used/modified (crucial for parser bugs),
+  ensure it is not vulnerable to Regular Expression Denial of Service (ReDoS).
+  Avoid overly permissive wildcards.
+- **Data Handling**: Check for insecure storage, exposure of sensitive data in
+  logs, or hardcoded credentials.
+- **Safe APIs**: Ensure safe standard library or third-party APIs are used
+  (e.g., avoiding raw execution of shell commands where safe APIs exist).
+
+#### 3. Readability & Coding Standards
+
+- **Style**: Ensure the code follows standard conventions for the language
+  (e.g., TS/JS guidelines if TypeScript).
+- **Naming**: Variable and function names should be descriptive and consistent.
+- **Complexity**: Functions should be short and adhere to the Single
+  Responsibility Principle. Avoid deep nesting.
+- **Comments**: Check for clear docstrings/comments where logic is non-trivial.
+  Avoid redundant comments that explain _what_ the code does instead of _why_.
+- **Readability Skill**: If specific project readability guidelines are
+  available in the repo (e.g., `.eslintrc`, `tsconfig`, or a style guide),
+  enforce them strictly.
+
+### Phase 3: Dynamic Verification (Execution)
+
+To verify style, readability, and consistency, you MUST NOT run the linter
+yourself. The orchestrator has already run the linter on the modified files and
+saved the output in `linter_output.txt`.
+
+1.  **Inspect Linter Output**:
+    - Read the contents of the file `linter_output.txt` in your workspace using
+      your `view_file` tool.
+    - Ensure the file indicates that the ESLint check succeeded without errors
+      for the files edited by the agent.
+    - **Scope Limitation**: When inspecting `linter_output.txt` and judging the
+      agent's linting results, you MUST ONLY consider and provide feedback on
+      files that were edited in the diff file (`changes.diff`). Ignore any lint
+      errors or warnings in files or code sections that were not modified by the
+      coding agent.
+    - Do NOT run `npm run lint`, `npm run lint:fix`, `npm run preflight`, or
+      `npm run test`.
+
+The linter check in `linter_output.txt` must succeed for the files edited in
+`changes.diff` before you approve the changes. If it fails on any files edited
+by the agent, copy those relevant linter errors from `linter_output.txt` into
+`pr_feedback.md` and set your verdict to `NEEDS_REVISION`. Do NOT reject the
+patch or request revisions for lint errors occurring in files or sections
+untouched by the coding agent.
+
+### Phase 4: Verdict and Feedback
+
+After completing the evaluation, you must render a verdict:
+
+- **Verdict Options**:
+
+  - `APPROVED`: The code is correct, secure, readable, passes all tests/lints,
+    and fully resolves the bug.
+  - `NEEDS_REVISION`: The code fails in one or more evaluation categories.
+
+- **Output Requirements**:
+  - Print the verdict clearly.
+  - If the verdict is `NEEDS_REVISION`, you **MUST** create a file named
+    `pr_feedback.md` in the working directory. `pr_feedback.md` must contain
+    detailed, actionable feedback grouped by category.
+  - If the verdict is `APPROVED`, you **MUST** create a file named
+    `pr_details.md` in the working directory. This file must specify the
+    recommended commit message and PR description.
+
+### Style Guide for `pr_details.md`
+
+If the verdict is `APPROVED`, write `pr_details.md` strictly in the following
+format:
+
+```markdown
+## Commit Message
+
+[SSR Agent] Issue Fix (<issue_number>): <short_commit_summary>
+
+## PR Description
+
+<pr_description_body>
+```
+
+**CRITICAL FORMATTING REQUIREMENT**: `## Commit Message` and `## PR Description`
+MUST be the ONLY Level 2 markdown headers (`## `) in this file. The
+orchestrator's regex parser relies on Level 2 headers to delimit sections.
+
+Follow these guidelines to construct the content:
+
+#### 1. Commit Message Guidelines
+
+- **Format**: `[SSR Agent] Issue Fix (<issue_number>): <short_commit_summary>`
+- **Issue Number**: Extract the issue number integer from
+  `github_metadata.issue_number` or the original spec (e.g., `25693`).
+- **Short Commit Summary**:
+  - Must be **no more than 10 words**.
+  - Must explain at a high level what issue needed to be fixed (e.g., "Fix skill
+    discovery with single-line description").
+  - Use active, imperative tone (e.g., "Fix", "Update", "Prevent").
+  - Do NOT use generic summaries like "Fix bug" or "Implement spec".
+
+#### 2. PR Description Guidelines
+
+- **Header Levels**: Any subsection headers within `<pr_description_body>` (such
+  as Context & Problem, Detailed Changes, or Verification) MUST use Level 3
+  headers (`### `) or lower. NEVER use Level 2 headers (`## `) inside the PR
+  description body, as that will prematurely terminate the orchestrator's regex
+  parser.
+- **Issue Number & URL**: You MUST explicitly write `fixes #<issue_number>` and
+  include the Original Issue URL constructed from `github_metadata` (e.g.,
+  `https://github.com/<owner>/<repo>/issues/<issue_number>`) at the top of the
+  PR description details.
+- **Context & Problem**: Read the fields in `workable_spec.summary`
+  (specifically `problem` and `root_cause`) to write a clear, 1-2 sentence
+  description explaining the issue and its root cause.
+- **Detailed Changes**: Observe the actual changes from the `changes.diff` file.
+  Summarize what modifications were made (which files were updated and what was
+  added/fixed).
+- **Verification**: Mention the specific verification tests that were executed
+  and passed (e.g., Vitest unit tests).
+- **Tone**: Keep it concise, structured with clear Markdown headers, and
+  professional. Do not refer to yourself as "I", refer to yourself as "the
+  agent" or write in the third person/passive voice.
+
+## Constraints
+
+- Do **NOT** attempt to fix the code yourself. Your job is only to evaluate and
+  report.
+- Do **NOT** commit or push any files.
+- When providing linting feedback or requesting revisions in `pr_feedback.md`,
+  ONLY consider and provide feedback on files that were edited in the diff file
+  (`changes.diff`). You must NOT encourage the coding agent to revise code, fix
+  lint errors, or refactor sections unrelated to its specific changes or goal.
+- If any command you execute (like `npm run lint` or `npm test`) crashes or
+  returns a non-zero exit code, you must treat this as a definitive failure.
+- DO NOT say you are "waiting in the background" or "scheduling" a check.
+- Immediately write `verdict.json` as {"verdict": "NEEDS_REVISION"}.
+- Write the exact linter/test error trace into `pr_feedback.md`.
+- Conclude your turn immediately. Do not make any more tool calls.
@@ -0,0 +1,115 @@
+# System Prompt: Code Revision Agent
+
+## Role
+
+You are an expert autonomous software engineer specializing in code revision,
+bug fix refinement, and iterative quality assurance. Your role is to carefully
+analyze evaluation feedback provided by the Code Evaluator Agent in
+`pr_feedback.md` (or `feedback.md`), address every issue raised across
+correctness, security, readability, and test coverage, and refine the local
+implementation until it meets rigorous production standards.
+
+## Inputs
+
+You will have access to:
+
+1.  **`pr_feedback.md` (or `feedback.md`)**: Contains detailed feedback from the
+    Evaluator Agent on previous iteration changes, grouped by category
+    (Correctness, Security, Readability, Test Failures) with specific file names
+    and line references.
+2.  **`firestore_doc.json` (or `example_firestore.json`)**: Contains the
+    original `workable_spec`, including the bug summary, implementation plan
+    (`files_to_modify`, `steps`), and testing strategy (`framework`,
+    `test_file`, `verification_steps`).
+3.  **Local Repository**: The codebase containing the previous iteration's code
+    changes and unit tests.
+
+## Workflow
+
+### Phase 1: Feedback Ingestion & Analysis
+
+1.  **Read the Evaluation Feedback**: Open and thoroughly inspect
+    `pr_feedback.md` (or `feedback.md`).
+2.  **Cross-Reference the Specification**: Consult `firestore_doc.json` to
+    ensure your planned revisions align with the original
+    `workable_spec.summary.problem`, `root_cause`, and
+    `testing_strategy.expected_behavior`.
+3.  **Categorize Issues**: Identify all specific action items listed in the
+    feedback across:
+    - Correctness & Logic gaps
+    - Security vulnerabilities or unsafe patterns
+    - Readability & Coding standard violations
+    - Missing or failing unit tests
+
+### Phase 2: Targeted Refinement & Implementation
+
+1.  **Apply Code Revisions**:
+    - Modify the target source files strictly to resolve every item identified
+      in the evaluator feedback.
+    - Keep changes focused and minimal; do not refactor unrelated code or
+      introduce scope creep.
+2.  **Uphold Strict Security Assertions**:
+    - **Input Validation**: Ensure any new inputs, parameters, or parsed data
+      structures are securely validated.
+    - **Regex Security**: Ensure any regular expressions are safe against
+      Regular Expression Denial of Service (ReDoS) and avoid overly permissive
+      wildcards.
+    - **Data Handling**: Check for secure storage and ensure no sensitive data
+      or hardcoded credentials are logged or exposed.
+    - **Safe APIs**: Ensure safe standard library or project-sanctioned APIs are
+      used rather than raw command strings or unsafe calls.
+3.  **Uphold Strict Quality & Readability Assertions**:
+    - **Style & Conventions**: Follow standard language guidelines (e.g.,
+      TypeScript/Node.js conventions) and any existing project style rules
+      (`.eslintrc`, `tsconfig`).
+    - **Naming & Simplicity**: Use descriptive, consistent names. Keep functions
+      short and modular, adhering to the Single Responsibility Principle.
+    - **Comments**: Add clear comments explaining _why_ non-trivial logic is
+      written, avoiding redundant explanations of obvious syntax.
+4.  **Refine & Expand Test Coverage**:
+    - Open `workable_spec.testing_strategy.test_file`.
+    - Fix any failing tests identified in the feedback.
+    - Add new test cases if the evaluator noted missing edge cases or incomplete
+      `verification_steps` coverage.
+    - Ensure all tests use the specified testing `framework` (e.g., Vitest,
+      Jest) and execute reliably in a headless environment.
+
+### Phase 3: Dynamic Verification & Regression Testing
+
+1.  **Run Linter**:
+    - Execute the project's linter command (e.g., `npm run lint` or
+      `npx eslint .`).
+    - Resolve any lint errors or warnings in the modified files until zero
+      errors remain.
+2.  **Run Target Test Suite**:
+    - Execute the target test file directly using your `run_command` tool (e.g.,
+      `npm test` or `npx vitest run <test_file>`).
+    - Verify that all revised code paths and edge cases pass.
+3.  **Run Regression Tests**:
+    - Execute relevant surrounding or full-project tests to ensure no existing
+      functionality was broken by the revisions.
+4.  **Iterate on Failure**:
+    - If any linter check or test fails, analyze the output, adjust the
+      implementation or test assertions, and re-run until 100% of tests pass.
+
+### Phase 4: Reporting
+
+- Provide a concise summary listing each point from `pr_feedback.md` and
+  explaining how it was resolved.
+- List the test and linter commands executed and confirm their passing status.
+- Confirm that all security, quality, and regression checks succeeded.
+
+## Constraints & Safety
+
+- **DO NOT** run `git commit`, `git push`, or any command that modifies the
+  remote repository. Leave the refined changes in the working directory.
+- **DO NOT** modify files outside of `files_to_modify` and `test_file` unless
+  explicitly justified (e.g., build/test framework configuration requirements).
+- Ensure all revised code matches the architectural patterns and style of the
+  existing codebase.
+- Your task is to apply the requested fixes based on `pr_feedback.md`.
+- DO NOT waste turns running exploratory git commands (like `git status`,
+  `git log`, or `git show`). You already have full access to the source code.
+- Apply the fixes directly in your very first turn, and use your next turn to
+  verify with tests.
+- You have a strict budget of 3 turns maximum to complete this task.
@@ -0,0 +1,251 @@
+"""Google Antigravity SDK Agent Runner and Context Management.
+
+Provides execution wrappers for executing Coding and Evaluator AI Agents using
+the Google Antigravity SDK. Includes serialized working directory controls
+and automatic local sandbox approvals.
+"""
+
+import asyncio
+import contextlib
+import logging
+import os
+from typing import Iterator
+
+
+@contextlib.contextmanager
+def working_directory(path: str | os.PathLike) -> Iterator[None]:
+    """Safely and temporarily changes the working directory.
+
+    Guarantees restoration of the original CWD even in the event of failures.
+
+    Args:
+        path: Directory path to switch to.
+
+    Yields:
+        None.
+    """
+    original_cwd = os.getcwd()
+    logging.debug("Switching working directory from %s to %s", original_cwd, path)
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        logging.debug("Restoring working directory to %s", original_cwd)
+        os.chdir(original_cwd)
+
+
+# Permitted tool allowlist for headless sandbox operations
+ALLOWED_SANDBOX_TOOLS = {
+    # Reading tools
+    "view_file",
+    "read_file",
+    # File writing & editing tools
+    "replace_file_content",
+    "multi_replace_file_content",
+    "write_file",
+    "write_to_file",
+    # Command execution
+    "run_command",
+}
+
+# Registering global agent hooks for local sandbox tool calls
+try:
+    from google.antigravity import Agent, LocalAgentConfig, hooks, policy
+except ImportError:
+    Agent, LocalAgentConfig, hooks, policy = None, None, None, None
+
+if hooks is not None:
+    @hooks.pre_tool_call_decide
+    def auto_approve_all_tools(context, tool_call) -> str:
+        """Only auto-approves safe, allowlisted tools in headless mode."""
+        if tool_call.name in ALLOWED_SANDBOX_TOOLS:
+            logging.debug("Auto-approving allowlisted sandbox tool call: %s", tool_call.name)
+            return "PROCEED"
+        logging.warning("Rejecting non-allowlisted tool call: %s", tool_call.name)
+        return "REJECT"
+
+
+class AgentRunnerError(Exception):
+    """Raised when the AI Agent fails to run or complete execution loops."""
+
+
+class AgentRunner:
+    """Manages AI Agent setups and coordinates conversation execution loops."""
+
+    _cwd_lock: asyncio.Lock | None = None
+
+    def __init__(
+        self,
+        project_id: str,
+        location: str = "global",
+        model_name: str = "gemini-3.5-flash",
+        script_dir: str | None = None,
+    ) -> None:
+        """Initializes the runner with target Vertex AI details.
+
+        Args:
+            project_id: Target Google Cloud Platform Project ID.
+            location: Global endpoint location of Vertex AI services (default: "global").
+            model_name: Base LLM version string.
+            script_dir: Directory containing system/prompt markdown files.
+        """
+        self.project_id = project_id
+        self.location = location or "global"
+        self.model_name = model_name
+        self.script_dir = script_dir or os.path.dirname(
+            os.path.abspath(__file__)
+        )
+
+    def _load_prompt_file(self, filename: str) -> str | None:
+        """Helper to read a localized system instruction prompt markdown file.
+
+        Args:
+            filename: Name of the prompt file inside the script directory.
+
+        Returns:
+            The text content if file exists, else None.
+        """
+        path = os.path.abspath(os.path.join(self.script_dir, filename))
+        if not path.startswith(os.path.abspath(self.script_dir)):
+            logging.warning("Path traversal attempt detected in prompt loading: %s", filename)
+            return None
+
+        if os.path.exists(path):
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    return f.read()
+            except IOError as e:
+                logging.warning(
+                    "Failed to read prompt file '%s': %s", filename, e
+                )
+        return None
+
+    async def run_agent(
+        self,
+        role: str,
+        prompt: str,
+        repo_path: str,
+        system_prompt_file: str | None = None,
+    ) -> str:
+        """Launches and manages an asynchronous conversation with an Antigravity Agent.
+
+        Args:
+            role: Label representing the agent's role (e.g., 'Coding Agent').
+            prompt: User message prompt guiding the immediate task.
+            repo_path: Target directory root of the repository to execute in.
+            system_prompt_file: Optional filename of system prompt markdown.
+
+        Returns:
+            A reconstructed single text block combining thoughts and outputs.
+
+        Raises:
+            AgentRunnerError: If Agent fails to run or execution fails.
+        """
+        if Agent is None:
+            raise AgentRunnerError("Google Antigravity SDK is not installed.")
+
+        logging.info("Initializing Agent '%s' inside %s", role, repo_path)
+
+        # Build fallback / configured system instructions
+        system_instructions = f"You are the {role}. You must complete the requested tasks in the workspace."
+        if system_prompt_file:
+            loaded_instructions = self._load_prompt_file(system_prompt_file)
+            if loaded_instructions:
+                system_instructions = loaded_instructions
+                logging.info(
+                    "System prompt successfully loaded from %s",
+                    system_prompt_file
+                )
+            else:
+                logging.warning(
+                    "Requested system prompt file '%s' not found. Reverting to default instructions.",
+                    system_prompt_file,
+                )
+
+        config = LocalAgentConfig(
+            vertex=True,
+            project=self.project_id,
+            location=self.location,
+            model=self.model_name,
+            system_instructions=system_instructions,
+            policies=[policy.allow_all()],
+            workspaces=[repo_path],
+        )
+
+        stdout_list: list[str] = []
+        thinking_list: list[str] = []
+
+        if AgentRunner._cwd_lock is None:
+            AgentRunner._cwd_lock = asyncio.Lock()
+
+        try:
+            # We change CWD to the repo workspace because the Antigravity SDK Agent
+            # interacts relative to the current working process directory.
+            # Since os.chdir is process-wide, we must serialize execution to prevent
+            # concurrent tasks from corrupting the CWD.
+            async with AgentRunner._cwd_lock:
+                with working_directory(repo_path):
+                    async with Agent(config) as agent:
+                        logging.info(
+                            "[%s] Sending initial task prompt to conversation loop...",
+                            role,
+                        )
+                        await agent.conversation.send(prompt)
+
+                        step_contents: dict[int, str] = {}
+                        step_thoughts: dict[int, str] = {}
+                        printed_steps: set[tuple[int, str]] = set()
+
+                        async for step in agent.conversation.receive_steps():
+                            if step.content:
+                                step_contents[step.step_index] = step.content
+
+                            # Retrieve thoughts if available via standard properties
+                            thinking = getattr(step, "thinking", None) or getattr(
+                                step, "thinking_delta", None
+                            )
+                            if thinking:
+                                step_thoughts[step.step_index] = str(thinking)
+
+                            step_key = (step.step_index, str(step.status))
+                            if step_key not in printed_steps:
+                                printed_steps.add(step_key)
+                                logging.info(
+                                    "[%s Step %s] Type: %s (Source: %s, Status: %s)",
+                                    role,
+                                    step.step_index,
+                                    step.type,
+                                    step.source,
+                                    step.status,
+                                )
+                                if step.content:
+                                    logging.info("[%s Content]: %s", role, step.content)
+                                if thinking:
+                                    logging.debug("[%s Thinking]: %s", role, thinking)
+                                if step.tool_calls:
+                                    for call in step.tool_calls:
+                                        logging.info(
+                                            "[%s Tool Call]: %s with args %s",
+                                            role,
+                                            call.name,
+                                            call.args,
+                                        )
+
+                        # Accumulate outputs
+                        for step_idx in sorted(step_contents.keys()):
+                            stdout_list.append(step_contents[step_idx])
+
+                        for step_idx in sorted(step_thoughts.keys()):
+                            thinking_list.append(step_thoughts[step_idx])
+
+            full_output = "\n".join(stdout_list)
+            if thinking_list:
+                joined_thoughts = "\n".join(thinking_list)
+                full_output += f"\nThoughts:\n{joined_thoughts}"
+
+            logging.info("Agent '%s' execution completed successfully.", role)
+            return full_output
+
+        except Exception as e:
+            logging.exception("Failed to execute agent loop for role: %s", role)
+            raise AgentRunnerError(f"Agent '{role}' execution failed: {e}") from e
@@ -0,0 +1,47 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Firestore db package for code generation orchestrator."""
+
+from .db_interface import (
+    ClaimAction,
+    IssueStatus,
+    ReleaseAction,
+    acquire_lock,
+    create_issue,
+    get_firestore_client,
+    get_firestore_id,
+    get_issue,
+    get_issue_ref,
+    mark_needs_human,
+    mark_pr_created,
+    release_lock,
+    update_status,
+)
+
+__all__ = [
+    "ClaimAction",
+    "IssueStatus",
+    "ReleaseAction",
+    "acquire_lock",
+    "create_issue",
+    "get_firestore_client",
+    "get_firestore_id",
+    "get_issue",
+    "get_issue_ref",
+    "mark_needs_human",
+    "mark_pr_created",
+    "release_lock",
+    "update_status",
+]
@@ -0,0 +1,428 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Firestore database interface for code generation worker and orchestrator.
+
+Provides helper functions for worker.py and orchestrator.py to interface with
+Firestore using the technical writeup specifications:
+- Concurrency dual-lock validation (lock.holder, lock.expires_at 15 mins).
+- Direct document ID resolution from the FIRESTORE_ID environment variable.
+- State transitions (COMMIT_GENERATION, PR_EVALUATION_PENDING, NEEDS_HUMAN, etc.).
+"""
+
+import os
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any
+from google.cloud import firestore
+
+
+class IssueStatus(str, Enum):
+    UNTRIAGED = "UNTRIAGED"
+    TRIAGING = "TRIAGING"
+    NEEDS_INFO = "NEEDS_INFO"
+    TRIAGED = "TRIAGED"
+    COMMIT_GENERATION = "COMMIT_GENERATION"
+    PR_EVALUATION_PENDING = "PR_EVALUATION_PENDING"
+    PR_REVISION = "PR_REVISION"
+    NEEDS_HUMAN = "NEEDS_HUMAN"
+    AUTO_CLOSE = "AUTO_CLOSE"
+
+
+class ClaimAction(Enum):
+    PROCEED = "PROCEED"
+    SKIP = "SKIP"
+    NEEDS_HUMAN = "NEEDS_HUMAN"
+
+
+class ReleaseAction(Enum):
+    COMPLETE = "COMPLETE"  # Complete / no retry needed (Exit code 0)
+    RETRY = "RETRY"        # Failed / trigger retry (Exit code 1)
+
+
+PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT", os.environ.get("PROJECT_ID"))
+DATABASE_NAME = os.environ.get("FIRESTORE_DATABASE")
+COLLECTION_NAME = os.environ.get("FIRESTORE_COLLECTION", "issues")
+
+_db_client: firestore.Client | None = None
+
+
+def get_firestore_client() -> firestore.Client:
+    """Lazily initializes and returns the Firestore client."""
+    global _db_client
+    if _db_client is None:
+        if DATABASE_NAME:
+            _db_client = firestore.Client(project=PROJECT_ID, database=DATABASE_NAME)
+        else:
+            _db_client = firestore.Client(project=PROJECT_ID)
+    return _db_client
+
+
+def get_firestore_id(
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+) -> str:
+    """Resolves the Firestore document ID.
+
+    Prioritizes the FIRESTORE_ID / firestore_id environment variable or explicit doc_id
+    over reconstructing the document ID from owner/repo/issue_number.
+    """
+    resolved_id = (
+        doc_id
+        or os.environ.get("FIRESTORE_ID")
+        or os.environ.get("firestore_id")
+    )
+    if resolved_id:
+        return resolved_id
+
+    if owner and repo and issue_number is not None:
+        return f"github_{owner}_{repo}_{issue_number}"
+
+    raise ValueError(
+        "Firestore document ID could not be resolved. Please set the 'FIRESTORE_ID' "
+        "environment variable or provide explicit doc_id or owner, repo, and issue_number."
+    )
+
+
+def get_issue_ref(
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+    doc_id: str | None = None,
+):
+    """Generates the Firestore DocumentReference for an issue using the resolved document ID."""
+    resolved_id = get_firestore_id(doc_id=doc_id, owner=owner, repo=repo, issue_number=issue_number)
+    return get_firestore_client().collection(COLLECTION_NAME).document(resolved_id)
+
+
+@firestore.transactional
+def _create_issue_tx(
+    transaction,
+    doc_ref,
+    owner: str,
+    repo: str,
+    issue_number: int,
+    title: str,
+    pr_number: str = "",
+    error: str = "",
+    doc_id: str | None = None,
+) -> bool:
+    snapshot = doc_ref.get(transaction=transaction)
+    if not snapshot.exists:
+        resolved_id = doc_id or doc_ref.id
+        new_issue = {
+            "status": IssueStatus.UNTRIAGED.value,
+            "triage_attempts": 0,
+            "generation_attempts": 0,
+            "workable_spec": {},
+            "lock": {
+                "holder": None,
+                "expires_at": None,
+            },
+            "created_at": firestore.SERVER_TIMESTAMP,
+            "updated_at": firestore.SERVER_TIMESTAMP,
+            "github_metadata": {
+                "owner": owner,
+                "repo": repo,
+                "issue_number": issue_number,
+                "title": title,
+                "pr_number": pr_number,
+            },
+            "error": error,
+        }
+        transaction.set(doc_ref, new_issue)
+        return True
+    return False
+
+
+def create_issue(
+    owner: str,
+    repo: str,
+    issue_number: int,
+    title: str,
+    pr_number: str = "",
+    error: str = "",
+    doc_id: str | None = None,
+) -> bool:
+    """Initializes a new issue document in a transaction."""
+    doc_ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)
+    transaction = get_firestore_client().transaction()
+    return _create_issue_tx(
+        transaction,
+        doc_ref,
+        owner,
+        repo,
+        issue_number,
+        title,
+        pr_number,
+        error,
+        doc_id,
+    )
+
+
+@firestore.transactional
+def _acquire_lock_tx(
+    transaction,
+    doc_ref,
+    lock_holder: str,
+    lock_duration_sec: int,
+    target_status: str,
+) -> ClaimAction:
+    """Transactional logic to validate and claim concurrency locks.
+
+    Step 1 & 2 (Lock Validation):
+    - If lock.expires_at is Null (or expired): no worker claimed, PROCEED.
+    - If lock.expires_at not elapsed, but lock.holder == current execution_id: crashed instance re-issue, PROCEED.
+    - Else (active lock held by another workflow): commit transaction with no changes and SKIP.
+    """
+    snapshot = doc_ref.get(transaction=transaction)
+    if not snapshot.exists:
+        return ClaimAction.SKIP
+
+    data = snapshot.to_dict() or {}
+    current_status = data.get("status")
+    attempts = data.get("generation_attempts", 0)
+
+    # Only allow PR generation to start for TRIAGED issues, recovering COMMIT_GENERATION jobs, or PR_REVISION
+    allowed_start_states = {
+        IssueStatus.TRIAGED.value,
+        IssueStatus.COMMIT_GENERATION.value,
+        IssueStatus.PR_REVISION.value,  # TODO: defensive programming for when PR revision is implemented
+    }
+    if current_status not in allowed_start_states:
+        return ClaimAction.SKIP
+
+    if attempts >= 2:
+        transaction.update(
+            doc_ref,
+            {
+                "status": IssueStatus.NEEDS_HUMAN.value,
+                "lock.holder": None,
+                "lock.expires_at": None,
+                "updated_at": firestore.SERVER_TIMESTAMP,
+            },
+        )
+        return ClaimAction.NEEDS_HUMAN
+
+    lock = data.get("lock") or {}
+    now = datetime.now(timezone.utc)
+    holder = lock.get("holder")
+    expires_at = lock.get("expires_at")
+
+    # Check active lock condition
+    lock_is_active = (expires_at is not None) and (now <= expires_at)
+
+    # If lock is active and held by another execution_id, exit cleanly
+    if lock_is_active and holder != lock_holder:
+        return ClaimAction.SKIP
+
+    # Acquire lock and set status (Step 3: COMMIT_GENERATION)
+    new_expires_at = now + timedelta(seconds=lock_duration_sec)
+    new_attempts = attempts + 1
+
+    transaction.update(
+        doc_ref,
+        {
+            "status": target_status,
+            "generation_attempts": new_attempts,
+            "lock.holder": lock_holder,
+            "lock.expires_at": new_expires_at,
+            "updated_at": firestore.SERVER_TIMESTAMP,
+        },
+    )
+    return ClaimAction.PROCEED
+
+
+def acquire_lock(
+    lock_holder: str,
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+    lock_duration_sec: int = 900,  # 15 minutes
+    target_status: str = IssueStatus.COMMIT_GENERATION.value,
+) -> ClaimAction:
+    """Attempts to acquire the processing lock for a Cloud Run workflow execution."""
+    doc_ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)
+    transaction = get_firestore_client().transaction()
+    return _acquire_lock_tx(
+        transaction,
+        doc_ref,
+        lock_holder,
+        lock_duration_sec,
+        target_status,
+    )
+
+
+@firestore.transactional
+def _release_lock_tx(
+    transaction,
+    doc_ref,
+    lock_holder: str,
+    success: bool,
+    status: str | None = None,
+    pr_number: str | None = None,
+    error: str | None = None,
+    workable_spec: dict[str, Any] | None = None,
+) -> ReleaseAction:
+    """Transactional logic to release the lock and update status."""
+    snapshot = doc_ref.get(transaction=transaction)
+    if not snapshot.exists:
+        return ReleaseAction.COMPLETE
+
+    data = snapshot.to_dict() or {}
+    lock = data.get("lock") or {}
+
+    if lock.get("holder") != lock_holder:
+        return ReleaseAction.COMPLETE
+
+    updates: dict[str, Any] = {
+        "lock.holder": None,
+        "lock.expires_at": None,
+        "updated_at": firestore.SERVER_TIMESTAMP,
+    }
+
+    if pr_number is not None:
+        updates["github_metadata.pr_number"] = pr_number
+
+    if error is not None:
+        updates["error"] = error
+
+    if success:
+        updates["generation_attempts"] = 0  # Defensive reset for multi-stage runs
+        if status:
+            updates["status"] = status
+        if workable_spec is not None:
+            updates["workable_spec"] = workable_spec
+        transaction.update(doc_ref, updates)
+        return ReleaseAction.COMPLETE
+    else:
+        target_status = status if status else IssueStatus.TRIAGED.value
+        attempts = data.get("generation_attempts", 0)
+        if attempts < 2:
+            updates["status"] = target_status
+            transaction.update(doc_ref, updates)
+            return ReleaseAction.RETRY
+        else:
+            updates["status"] = IssueStatus.NEEDS_HUMAN.value
+            transaction.update(doc_ref, updates)
+            return ReleaseAction.COMPLETE
+
+
+def release_lock(
+    lock_holder: str,
+    success: bool,
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+    status: str | None = None,
+    pr_number: str | None = None,
+    error: str | None = None,
+    workable_spec: dict[str, Any] | None = None,
+) -> ReleaseAction:
+    """Releases the processing lock for an issue and updates status."""
+    doc_ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)
+    transaction = get_firestore_client().transaction()
+    return _release_lock_tx(
+        transaction,
+        doc_ref,
+        lock_holder,
+        success,
+        status,
+        pr_number,
+        error,
+        workable_spec,
+    )
+
+
+def mark_pr_created(
+    lock_holder: str,
+    pr_number: str,
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+    status: str = IssueStatus.PR_EVALUATION_PENDING.value,
+) -> ReleaseAction:
+    """Moves issue to PR_EVALUATION_PENDING, records pr_number, and releases lock."""
+    return release_lock(
+        lock_holder=lock_holder,
+        success=True,
+        doc_id=doc_id,
+        owner=owner,
+        repo=repo,
+        issue_number=issue_number,
+        status=status,
+        pr_number=pr_number,
+    )
+
+
+def mark_needs_human(
+    lock_holder: str,
+    reason: str,
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+) -> ReleaseAction:
+    """Moves issue to NEEDS_HUMAN, records error, and releases lock."""
+    return release_lock(
+        lock_holder=lock_holder,
+        success=False,
+        doc_id=doc_id,
+        owner=owner,
+        repo=repo,
+        issue_number=issue_number,
+        status=IssueStatus.NEEDS_HUMAN.value,
+        error=reason,
+    )
+
+
+def get_issue(
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+) -> dict[str, Any] | None:
+    """Retrieves an issue document snapshot as a dictionary using FIRESTORE_ID."""
+    doc_ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)
+    snapshot = doc_ref.get()
+    if not snapshot.exists:
+        return None
+    return snapshot.to_dict()
+
+
+def update_status(
+    status: str,
+    doc_id: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+    issue_number: int | str | None = None,
+    pr_number: str | None = None,
+    error: str | None = None,
+) -> None:
+    """Updates issue status, PR number, and error message using FIRESTORE_ID."""
+    doc_ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)
+    updates: dict[str, Any] = {
+        "status": status,
+        "updated_at": firestore.SERVER_TIMESTAMP,
+    }
+    if pr_number is not None:
+        updates["github_metadata.pr_number"] = pr_number
+    if error is not None:
+        updates["error"] = error
+    doc_ref.update(updates)
@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+venv/
+experimental/
+tests/
+.env
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
David Pierce	3f5634951e	Update package.json from 0.54.1 to 0.54.2	2026-08-06 13:14:13 -04:00
gemini-cli-robot	ae5f5edb58	chore(release): v0.54.1	2026-08-06 16:13:54 +00:00
gemini-cli-robot	76a97cac0e	fix(patch): cherry-pick `56f9688` to release/v0.54.0-pr-28700 to patch version v0.54.0 and create version 0.54.1 (#28710 ) Co-authored-by: Adam Weidman <65992621+adamfweidman@users.noreply.github.com> Co-authored-by: David Pierce <davidapierce@google.com> Co-authored-by: Mpider-San <sarbojitrana47c@gmail.com>	2026-08-06 14:54:28 +00:00
gemini-cli-robot	a74b483d14	chore(release): v0.54.0	2026-08-06 01:28:51 +00:00
gemini-cli-robot	a81db2768f	chore(release): v0.54.0-preview.1	2026-07-31 21:33:01 +00:00
gemini-cli-robot	d3c51f158c	fix(patch): cherry-pick `f47d6c6` to release/v0.54.0-preview.0-pr-28566 to patch version v0.54.0-preview.0 and create version 0.54.0-preview.1 (#28609 ) Co-authored-by: David Pierce <davidapierce@google.com> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: luisfelipe-alt <luisfelipe@google.com>	2026-07-31 20:39:47 +00:00
gemini-cli-robot	5f9c117de2	chore(release): v0.54.0-preview.0	2026-07-28 21:28:13 +00:00
Adam Weidman	d29268d360	fix(core): skip merged function-response turns when finding the active loop (#28565 )	2026-07-28 20:16:53 +00:00
joneba-google	fccc043bd4	feat(pr-generator-db): implement Firestore concurrency dual-locking and test ingestion utilities (#28432 )	2026-07-28 19:21:50 +00:00
joneba-google	c5622fec27	feat(pr-generator-agent): implement Antigravity agent runner and prompt templates … (#28434 )	2026-07-28 19:21:30 +00:00
gemini-cli-robot	e07280eb4e	chore/release: bump version to 0.54.0-nightly.20260728.gbef611950 (#28552 )	2026-07-28 17:16:07 +00:00
luisfelipe-alt	bef6119500	fix(core): enforce explicit tag length and validation in file keychain (#28523 )	2026-07-27 17:36:48 +00:00
luisfelipe-alt	b94c9775b1	fix(a2a-server): normalize CRLF line endings to LF in getProposedContent (#28531 )	2026-07-27 17:18:58 +00:00
David Pierce	3818efbbfb	fix(core): filter out thought parts from getHistoryTurns when context management is disabled (#28509 )	2026-07-24 20:48:37 +00:00
amelidev	e2a5375d10	fix(core): enforce HTTPS for GoogleCredentialsAuthProvider to prevent cleartext leakage (#28517 )	2026-07-24 17:48:07 +00:00
Chad	69b51f8fa2	feat(caretaker-triage): post comment before auto-closing issues (#28411 )	2026-07-23 22:43:17 +00:00
amelidev	3c1bb8c35d	fix(core): rotate session ID on model fallback to prevent stateful API errors (#28469 )	2026-07-23 19:36:46 +00:00
Chad	d76d2d0742	chore(caretaker): update vitest to v3.2.4 and add package-lock.json files (#28409 )	2026-07-23 17:55:34 +00:00
Chad	a96259c9e5	fix(caretaker): sanitize and wrap issue title in untrusted_context (#28352 )	2026-07-23 17:55:24 +00:00
gemini-cli-robot	87f785192c	chore(release): bump version to 0.54.0-nightly.20260722.gf743ab579 (#28510 )	2026-07-23 06:56:57 +00:00
gemini-cli-robot	1c21640f97	Changelog for v0.52.0 (#28508 ) Co-authored-by: gemini-cli-robot <224641728+gemini-cli-robot@users.noreply.github.com>	2026-07-23 06:56:45 +00:00
gemini-cli-robot	455d721a0c	Changelog for v0.53.0-preview.0 (#28507 ) Co-authored-by: gemini-cli-robot <224641728+gemini-cli-robot@users.noreply.github.com>	2026-07-23 06:56:36 +00:00
Vedant Mahajan	9681621c6b	feat(evals): add eval coverage report command (#28169 )	2026-07-22 18:45:42 +00:00
luisfelipe-alt	f743ab5790	fix(core): sequentially verify cached credentials and restore GOOGLE_APPLICATION_CREDENTIALS fallback (#28472 ) Co-authored-by: David Pierce <davidapierce@google.com>	2026-07-22 16:09:52 +00:00
luisfelipe-alt	c776c665b0	fix(a2a-server): enforce workspace trust and task isolation to prevent RCE (#28470 )	2026-07-21 16:38:09 +00:00
amelidev	acae7124bd	fix(core): mitigate infinite ReAct loops and prompt injection loops (#28429 ) Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>	2026-07-17 21:03:46 +00:00
Om Patel	69e0c2659e	refactor(cli): align macOS permissive Seatbelt profiles with deny-default model (#28424 )	2026-07-17 18:06:01 +00:00
Chad	aea9e5e8ed	feat(caretaker-triage): implement LLM triage orchestrator and container build (#28345 )	2026-07-17 16:59:28 +00:00
luisfelipe-alt	3ff5ba20fc	fix(core,a2a): group cancelled tool responses and coalesce consecutive roles to prevent 400 Bad Request (#28407 )	2026-07-15 19:58:55 +00:00