chore(release): v0.22.0-preview.1

* Update docs.

* Update model docs.

.gemini/commands/frontend.toml

@@ -0,0 +1,54 @@
+description="Injects context of all relevant cli files"
+prompt = """
+The source code contains the content of absolutely every source code file in
+packages/cli and key files from packages/core. In addition to the source code, the following test files are
+included as they are test files that conform to the project's testing standards:
+`packages/cli/src/ui/components/InputPrompt.test.tsx` and `packages/cli/src/ui/App.test.tsx`.
+You should very rarely need to read any other files from packages/cli to resolve
+prompts.
+
+!{find packages/cli -path packages/cli/dist -prune -o -type f \\( -name "*.ts" -o -name "*.tsx" \\) ! -name "*.test.ts" ! -name "*.test.tsx" ! -name "*.d.ts" -exec echo "--- {} ---" \\; -exec cat {} \\; && echo "--- packages/cli/src/ui/components/InputPrompt.test.tsx ---" && cat packages/cli/src/ui/components/InputPrompt.test.tsx && echo "--- packages/cli/src/ui/App.test.tsx ---" && cat packages/cli/src/ui/App.test.tsx && echo "--- packages/core/src/core/coreToolScheduler.ts ---" && cat packages/core/src/core/coreToolScheduler.ts && echo "--- packages/core/src/core/nonInteractiveToolExecutor.ts ---" && cat packages/core/src/core/nonInteractiveToolExecutor.ts && echo "--- packages/core/src/confirmation-bus/message-bus.ts ---" && cat packages/core/src/confirmation-bus/message-bus.ts && echo "--- packages/core/src/confirmation-bus/types.ts ---" && cat packages/core/src/confirmation-bus/types.ts && echo "--- packages/core/src/utils/events.ts ---" && cat packages/core/src/utils/events.ts && echo "--- packages/core/src/core/client.ts ---" && cat packages/core/src/core/client.ts && echo "--- packages/core/src/core/geminiChat.ts ---" && cat packages/core/src/core/geminiChat.ts && echo "--- packages/core/src/core/turn.ts ---" && cat packages/core/src/core/turn.ts && echo "--- packages/core/src/agents/executor.ts ---" && cat packages/core/src/agents/executor.ts && echo "--- packages/core/src/telemetry/types.ts ---" && cat packages/core/src/telemetry/types.ts && echo "--- packages/core/src/telemetry/loggers.ts ---" && cat packages/core/src/telemetry/loggers.ts && echo "--- packages/core/src/telemetry/uiTelemetry.ts ---" && cat packages/core/src/telemetry/uiTelemetry.ts}
+
+**Pay extremely close attention to these files.** They define the project's
+core architecture, component patterns, and testing standards.
+
+In addition to the code context, you MUST strictly adhere to the following frontend-specific development guidelines while adding code to packages/cli.
+
+## Testing Standards
+*   **Async Testing**: ALWAYS use `waitFor` from `packages/cli/src/test-utils/async.ts` instead of `vi.waitFor` to prevent flakiness and `act` warnings. NEVER use fixed waits (e.g., `await delay(100)`).
+*   **State Changes**: Wrap all blocks that change component state in `act`.
+*   **Snapshots**: Use `toMatchSnapshot` to verify rendering.
+*   **Rendering**: Use `render` or `renderWithProviders` from `packages/cli/src/test-utils/render.tsx` instead of `ink-testing-library` directly.
+*   **Mocking**:
+    *   Reuse existing mocks/fakes where possible.
+    *   **Parameterized Tests**: Use parameterized tests with explicit types to reduce duplication and ensure type safety.
+    *   Avoid mocking the file system, os, or child_process if at all possible; if you have to mock the Mock critical dependencies (`fs`, `os`, `child_process`) do so ONLY at the top of the file.
+
+## React & Ink Architecture
+*   **Keyboard Handling**: You MUST use `useKeyPress.ts` from Gemini CLI for keyboard handling, NOT the standard ink library. This is critical for supporting slow terminals and multiple events per frame.
+    *   Handle multiple events gracefully (often requires a reducer pattern, see `text-buffer.ts`).
+*   **State Management**:
+    *   NEVER trigger side effects from within the body of a `setState` callback. Use a reducer or `useRef` if necessary.
+    *   Initialize state explicitly (e.g., use `undefined` rather than `true` if unknown).
+*   **Performance**:
+    *   Avoid synchronous file I/O in components.
+    *   Do not introduce excessive property drilling; leverage or extend existing providers.
+
+## Configuration & Settings
+*   **Settings vs Args**: Use settings for user-configurable options; do not add new CLI arguments.
+*   **Schema**: Add new settings to `packages/cli/src/config/settingsSchema.ts`.
+*   **Documentation**:
+    *   If `showInDialog: true`, document in `docs/get-started/configuration.md`.
+    *   Ensure `requiresRestart` is correctly set.
+
+## Keyboard Shortcuts
+*   **Registration**: Define new shortcuts in `packages/cli/src/config/keyBindings.ts`.
+*   **Documentation**: Document all new shortcuts in `docs/cli/keyboard-shortcuts.md`.
+*   **Compatibility**: Avoid function keys and common VSCode shortcuts. Be cautious with `Meta` key (Mac-limited support).
+
+## General
+*   **Logging**: Use `debugLogger` for errors. NEVER leave `console.log/warn/error` in the code.
+*   **TypeScript**: Avoid the non-null assertion operator (`!`).
+
+{{args}}. 
+ """

.gemini/commands/full-context.toml

@@ -0,0 +1,57 @@
+description="Injects context of all relevant cli files"
+prompt = """
+The following output contains the complete
+source code of the gemini cli library (`packages/cli`), and {packages/core} and representative test files
+(`packages/cli/src/ui/components/InputPrompt.test.tsx` and `packages/cli/src/ui/App.test.tsx`) that best conform to the project's testing standards.
+**Pay extremely close attention to these files.** They define the project's
+core architecture, component patterns, and testing standards.
+
+The source code contains the content of absolutely every source code file in
+packages/cli and packages/core. In addition to the source code, the following test files are
+included as they are test files that conform to the project's testing standards:
+`packages/cli/src/ui/components/InputPrompt.test.tsx` and `packages/cli/src/ui/App.test.tsx`.
+You should very rarely need to read any other files from packages/cli to resolve
+prompts.
+
+!{find packages/cli packages/core \\( -path packages/cli/dist -o -path packages/core/dist -o -name node_modules \\) -prune -o -type f \\( -name "*.ts" -o -name "*.tsx" \\) ! -name "*.test.ts" ! -name "*.test.tsx" ! -name "*.d.ts" -exec echo "--- {} ---" \\; -exec cat {} \\; && echo "--- packages/cli/src/ui/components/InputPrompt.test.tsx ---" && cat packages/cli/src/ui/components/InputPrompt.test.tsx && echo "--- packages/cli/src/ui/App.test.tsx ---" && cat packages/cli/src/ui/App.test.tsx}
+
+In addition to the code context, you MUST strictly adhere to the following frontend-specific development guidelines when writing code in packages/cli.
+
+## Testing Standards
+*   **Async Testing**: ALWAYS use `waitFor` from `packages/cli/src/test-utils/async.ts` instead of `vi.waitFor` to prevent flakiness and `act` warnings. NEVER use fixed waits (e.g., `await delay(100)`).
+*   **State Changes**: Wrap all blocks that change component state in `act`.
+*   **Snapshots**: Use `toMatchSnapshot` to verify rendering.
+*   **Rendering**: Use `render` or `renderWithProviders` from `packages/cli/src/test-utils/render.tsx` instead of `ink-testing-library` directly.
+*   **Mocking**:
+    *   Reuse existing mocks/fakes where possible.
+    *   **Parameterized Tests**: Use parameterized tests with explicit types to reduce duplication and ensure type safety.
+    *   Avoid mocking the file system, os, or child_process if at all possible; if you have to mock the Mock critical dependencies (`fs`, `os`, `child_process`) do so ONLY at the top of the file.
+
+## React & Ink Architecture
+*   **Keyboard Handling**: You MUST use `useKeyPress.ts` from Gemini CLI for keyboard handling, NOT the standard ink library. This is critical for supporting slow terminals and multiple events per frame.
+    *   Handle multiple events gracefully (often requires a reducer pattern, see `text-buffer.ts`).
+*   **State Management**:
+    *   NEVER trigger side effects from within the body of a `setState` callback. Use a reducer or `useRef` if necessary.
+    *   Initialize state explicitly (e.g., use `undefined` rather than `true` if unknown).
+*   **Performance**:
+    *   Avoid synchronous file I/O in components.
+    *   Do not introduce excessive property drilling; leverage or extend existing providers.
+
+## Configuration & Settings
+*   **Settings vs Args**: Use settings for user-configurable options; do not add new CLI arguments.
+*   **Schema**: Add new settings to `packages/cli/src/config/settingsSchema.ts`.
+*   **Documentation**:
+    *   If `showInDialog: true`, document in `docs/get-started/configuration.md`.
+    *   Ensure `requiresRestart` is correctly set.
+
+## Keyboard Shortcuts
+*   **Registration**: Define new shortcuts in `packages/cli/src/config/keyBindings.ts`.
+*   **Documentation**: Document all new shortcuts in `docs/cli/keyboard-shortcuts.md`.
+*   **Compatibility**: Avoid function keys and common VSCode shortcuts. Be cautious with `Meta` key (Mac-limited support).
+
+## General
+*   **Logging**: Use `debugLogger` for errors. NEVER leave `console.log/warn/error` in the code.
+*   **TypeScript**: Avoid the non-null assertion operator (`!`).
+
+{{args}}. 
+ """

.github/CODEOWNERS

@@ -11,3 +11,6 @@
 /.github/workflows/ @google-gemini/gemini-cli-askmode-approvers
 /packages/cli/package.json @google-gemini/gemini-cli-askmode-approvers
 /packages/core/package.json @google-gemini/gemini-cli-askmode-approvers
+
+# Docs have a dedicated approver group in addition to maintainers
+/docs/ @google-gemini/gemini-cli-maintainers @google-gemini/gemini-cli-docs

.github/workflows/chained_e2e.yml

@@ -1,4 +1,4 @@
-name: 'Test Chained E2E'
+name: 'Testing: E2E (Chained)'
 
 on:
   push:
@@ -37,14 +37,15 @@ jobs:
       - id: 'merge-queue-e2e-skipper'
         uses: 'cariad-tech/merge-queue-ci-skipper@1032489e59437862c90a08a2c92809c903883772' # ratchet:cariad-tech/merge-queue-ci-skipper@main
         with:
-          secret: '${{ secrets.GITHUB_TOKEN }}'
+          secret: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
     continue-on-error: true
 
   download_repo_name:
     runs-on: 'gemini-cli-ubuntu-16-core'
-    if: "github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_run'"
+    if: "${{github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_run'}}"
     outputs:
       repo_name: '${{ steps.output-repo-name.outputs.repo_name }}'
+      head_sha: '${{ steps.output-repo-name.outputs.head_sha }}'
     steps:
       - name: 'Mock Repo Artifact'
         if: "${{ github.event_name == 'workflow_dispatch' }}"
@@ -66,7 +67,7 @@ jobs:
           name: 'repo_name'
           run-id: '${{ env.RUN_ID }}'
           path: '${{ runner.temp }}/artifacts'
-      - name: 'Output Repo Name'
+      - name: 'Output Repo Name and SHA'
         id: 'output-repo-name'
         uses: 'actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd' # ratchet:actions/github-script@v8
         with:
@@ -75,8 +76,16 @@ jobs:
             const fs = require('fs');
             const path = require('path');
             const temp = '${{ runner.temp }}/artifacts';
-            const repo_name = String(fs.readFileSync(path.join(temp, 'repo_name')));
-            core.setOutput('repo_name', repo_name);
+            const repoPath = path.join(temp, 'repo_name');
+            if (fs.existsSync(repoPath)) {
+              const repo_name = String(fs.readFileSync(repoPath)).trim();
+              core.setOutput('repo_name', repo_name);
+            }
+            const shaPath = path.join(temp, 'head_sha');
+            if (fs.existsSync(shaPath)) {
+              const head_sha = String(fs.readFileSync(shaPath)).trim();
+              core.setOutput('head_sha', head_sha);
+            }
 
   parse_run_context:
     name: 'Parse run context'
@@ -91,7 +100,7 @@ jobs:
         name: 'Set dynamic repository and SHA'
         env:
           REPO: '${{ needs.download_repo_name.outputs.repo_name || github.repository }}'
-          SHA: '${{ github.event.inputs.head_sha || github.event.workflow_run.head_sha || github.sha }}'
+          SHA: '${{ needs.download_repo_name.outputs.head_sha || github.event.inputs.head_sha || github.event.workflow_run.head_sha || github.sha }}'
         shell: 'bash'
         run: |
           echo "REPO=$REPO" >> "$GITHUB_OUTPUT"
@@ -100,19 +109,20 @@ jobs:
   set_pending_status:
     runs-on: 'gemini-cli-ubuntu-16-core'
     permissions: 'write-all'
-    if: "github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_run'"
     needs:
       - 'parse_run_context'
+    if: 'always()'
     steps:
       - name: 'Set pending status'
         uses: 'myrotvorets/set-commit-status-action@16037e056d73b2d3c88e37e393ff369047f70886' # ratchet:myrotvorets/set-commit-status-action@master
         if: 'always()'
         with:
           allowForks: 'true'
-          repo: '${{ needs.parse_run_context.outputs.repository }}'
+          repo: '${{ github.repository }}'
           sha: '${{ needs.parse_run_context.outputs.sha }}'
-          token: '${{ secrets.GITHUB_TOKEN }}'
+          token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
           status: 'pending'
+          context: 'E2E (Chained)'
 
   e2e_linux:
     name: 'E2E Test (Linux) - ${{ matrix.sandbox }}'
@@ -121,7 +131,7 @@ jobs:
       - 'parse_run_context'
     runs-on: 'gemini-cli-ubuntu-16-core'
     if: |
-      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip != 'true')
     strategy:
       fail-fast: false
       matrix:
@@ -150,7 +160,7 @@ jobs:
         run: 'npm run build'
 
       - name: 'Set up Docker'
-        if: "matrix.sandbox == 'sandbox:docker'"
+        if: "${{matrix.sandbox == 'sandbox:docker'}}"
         uses: 'docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435' # ratchet:docker/setup-buildx-action@v3
 
       - name: 'Run E2E tests'
@@ -173,7 +183,7 @@ jobs:
       - 'parse_run_context'
     runs-on: 'macos-latest'
     if: |
-      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip != 'true')
     steps:
       - name: 'Checkout'
         uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
@@ -193,11 +203,11 @@ jobs:
         run: 'npm run build'
 
       - name: 'Fix rollup optional dependencies on macOS'
-        if: "runner.os == 'macOS'"
+        if: "${{runner.os == 'macOS'}}"
         run: |
           npm cache clean --force
       - name: 'Run E2E tests (non-Windows)'
-        if: "runner.os != 'Windows'"
+        if: "${{runner.os != 'Windows'}}"
         env:
           GEMINI_API_KEY: '${{ secrets.GEMINI_API_KEY }}'
           KEEP_OUTPUT: 'true'
@@ -211,7 +221,7 @@ jobs:
       - 'merge_queue_skipper'
       - 'parse_run_context'
     if: |
-      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip != 'true')
     runs-on: 'gemini-cli-windows-16-core'
     continue-on-error: true
 
@@ -269,7 +279,7 @@ jobs:
   e2e:
     name: 'E2E'
     if: |
-      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip != 'true')
     needs:
       - 'e2e_linux'
       - 'e2e_mac'
@@ -288,7 +298,7 @@ jobs:
   set_workflow_status:
     runs-on: 'gemini-cli-ubuntu-16-core'
     permissions: 'write-all'
-    if: "github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_run'"
+    if: 'always()'
     needs:
       - 'parse_run_context'
       - 'e2e'
@@ -298,7 +308,8 @@ jobs:
         if: 'always()'
         with:
           allowForks: 'true'
-          repo: '${{ needs.parse_run_context.outputs.repository }}'
+          repo: '${{ github.repository }}'
           sha: '${{ needs.parse_run_context.outputs.sha }}'
           token: '${{ secrets.GITHUB_TOKEN }}'
-          status: '${{ job.status }}'
+          status: '${{ needs.e2e.result }}'
+          context: 'E2E (Chained)'

.github/workflows/e2e.yml

@@ -1,247 +0,0 @@
-name: 'Testing: E2E'
-
-on:
-  push:
-    branches:
-      - 'main'
-  # This will run for PRs from the base repository, providing secrets.
-  pull_request:
-    branches:
-      - 'main'
-      - 'release/**'
-  # This will run for PRs from forks when a label is added.
-  pull_request_target:
-    types: ['labeled']
-  merge_group:
-  workflow_dispatch:
-    inputs:
-      branch_ref:
-        description: 'Branch to run on'
-        required: true
-        default: 'main'
-        type: 'string'
-
-concurrency:
-  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
-  cancel-in-progress: |-
-    ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/heads/release/') }}
-
-jobs:
-  merge_queue_skipper:
-    name: 'Merge Queue Skipper'
-    runs-on: 'gemini-cli-ubuntu-16-core'
-    permissions: 'read-all'
-    outputs:
-      skip: '${{ steps.merge-queue-e2e-skipper.outputs.skip-check }}'
-    steps:
-      - id: 'merge-queue-e2e-skipper'
-        uses: 'cariad-tech/merge-queue-ci-skipper@1032489e59437862c90a08a2c92809c903883772' # ratchet:cariad-tech/merge-queue-ci-skipper@main
-        with:
-          secret: '${{ secrets.GITHUB_TOKEN }}'
-    continue-on-error: true
-
-  e2e_linux:
-    name: 'E2E Test (Linux) - ${{ matrix.sandbox }}'
-    needs: 'merge_queue_skipper'
-    if: |
-      (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false') &&
-      (github.event_name == 'push' ||
-      github.event_name == 'merge_group' ||
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.pull_request.head.repo.full_name == github.repository) ||
-      (github.event.label.name == 'maintainer:e2e:ok'))
-    runs-on: 'gemini-cli-ubuntu-16-core'
-    strategy:
-      fail-fast: false
-      matrix:
-        sandbox:
-          - 'sandbox:none'
-          - 'sandbox:docker'
-        node-version:
-          - '20.x'
-
-    steps:
-      - name: 'Checkout (fork)'
-        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
-        if: "github.event_name == 'pull_request_target'"
-        with:
-          ref: '${{ github.event.pull_request.head.sha }}'
-          repository: '${{ github.event.pull_request.head.repo.full_name }}'
-
-      - name: 'Checkout (internal)'
-        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
-        if: "github.event_name != 'pull_request_target'"
-        with:
-          ref: '${{ github.event.inputs.branch_ref || github.ref }}'
-
-      - name: 'Set up Node.js ${{ matrix.node-version }}'
-        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions-node@v4
-        with:
-          node-version: '${{ matrix.node-version }}'
-
-      - name: 'Install dependencies'
-        run: 'npm ci'
-
-      - name: 'Build project'
-        run: 'npm run build'
-
-      - name: 'Set up Docker'
-        if: "matrix.sandbox == 'sandbox:docker'"
-        uses: 'docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435' # ratchet:docker/setup-buildx-action@v3
-
-      - name: 'Run E2E tests'
-        env:
-          GEMINI_API_KEY: '${{ secrets.GEMINI_API_KEY }}'
-          KEEP_OUTPUT: 'true'
-          VERBOSE: 'true'
-        shell: 'bash'
-        run: |
-          if [[ "${{ matrix.sandbox }}" == "sandbox:docker" ]]; then
-            npm run test:integration:sandbox:docker
-          else
-            npm run test:integration:sandbox:none
-          fi
-
-  e2e_mac:
-    name: 'E2E Test (macOS)'
-    needs: 'merge_queue_skipper'
-    if: |
-      (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false') &&
-      (github.event_name == 'push' ||
-      github.event_name == 'merge_group' ||
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.pull_request.head.repo.full_name == github.repository) ||
-      (github.event.label.name == 'maintainer:e2e:ok'))
-    runs-on: 'macos-latest'
-    steps:
-      - name: 'Checkout (fork)'
-        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
-        if: "github.event_name == 'pull_request_target'"
-        with:
-          ref: '${{ github.event.pull_request.head.sha }}'
-          repository: '${{ github.event.pull_request.head.repo.full_name }}'
-
-      - name: 'Checkout (internal)'
-        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
-        if: "github.event_name != 'pull_request_target'"
-        with:
-          ref: '${{ github.event.inputs.branch_ref || github.ref }}'
-
-      - name: 'Set up Node.js 20.x'
-        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions-node@v4
-        with:
-          node-version: '20.x'
-
-      - name: 'Install dependencies'
-        run: 'npm ci'
-
-      - name: 'Build project'
-        run: 'npm run build'
-
-      - name: 'Fix rollup optional dependencies on macOS'
-        if: "runner.os == 'macOS'"
-        run: |
-          npm cache clean --force
-      - name: 'Run E2E tests (non-Windows)'
-        if: "runner.os != 'Windows'"
-        env:
-          GEMINI_API_KEY: '${{ secrets.GEMINI_API_KEY }}'
-          KEEP_OUTPUT: 'true'
-          SANDBOX: 'sandbox:none'
-          VERBOSE: 'true'
-        run: 'npm run test:integration:sandbox:none'
-
-  e2e_windows:
-    name: 'Slow E2E - Win'
-    needs: 'merge_queue_skipper'
-    if: |
-      (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false') &&
-      (github.event_name == 'push' ||
-      github.event_name == 'merge_group' ||
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.pull_request.head.repo.full_name == github.repository) ||
-      (github.event.label.name == 'maintainer:e2e:ok'))
-    runs-on: 'gemini-cli-windows-16-core'
-    continue-on-error: true
-
-    steps:
-      - name: 'Checkout (fork)'
-        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
-        if: "github.event_name == 'pull_request_target'"
-        with:
-          ref: '${{ github.event.pull_request.head.sha }}'
-          repository: '${{ github.event.pull_request.head.repo.full_name }}'
-
-      - name: 'Checkout (internal)'
-        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
-        if: "github.event_name != 'pull_request_target'"
-        with:
-          ref: '${{ github.event.inputs.branch_ref || github.ref }}'
-
-      - name: 'Set up Node.js 20.x'
-        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions-node@v4
-        with:
-          node-version: '20.x'
-          cache: 'npm'
-
-      - name: 'Configure Windows Defender exclusions'
-        run: |
-          Add-MpPreference -ExclusionPath $env:GITHUB_WORKSPACE -Force
-          Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE\node_modules" -Force
-          Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE\packages" -Force
-          Add-MpPreference -ExclusionPath "$env:TEMP" -Force
-        shell: 'pwsh'
-
-      - name: 'Configure npm for Windows performance'
-        run: |
-          npm config set progress false
-          npm config set audit false
-          npm config set fund false
-          npm config set loglevel error
-          npm config set maxsockets 32
-          npm config set registry https://registry.npmjs.org/
-        shell: 'pwsh'
-
-      - name: 'Install dependencies'
-        run: 'npm ci'
-        shell: 'pwsh'
-
-      - name: 'Build project'
-        run: 'npm run build'
-        shell: 'pwsh'
-
-      - name: 'Run E2E tests'
-        env:
-          GEMINI_API_KEY: '${{ secrets.GEMINI_API_KEY }}'
-          KEEP_OUTPUT: 'true'
-          SANDBOX: 'sandbox:none'
-          VERBOSE: 'true'
-          NODE_OPTIONS: '--max-old-space-size=32768 --max-semi-space-size=256'
-          UV_THREADPOOL_SIZE: '32'
-          NODE_ENV: 'test'
-        shell: 'pwsh'
-        run: 'npm run test:integration:sandbox:none'
-
-  e2e:
-    name: 'E2E'
-    if: |
-      always() && (
-        github.event_name == 'push' ||
-        github.event_name == 'merge_group' ||
-        github.event_name == 'workflow_dispatch' ||
-        (github.event.pull_request.head.repo.full_name == github.repository) ||
-        (github.event.label.name == 'maintainer:e2e:ok')
-      )
-    needs:
-      - 'e2e_linux'
-      - 'e2e_mac'
-    runs-on: 'gemini-cli-ubuntu-16-core'
-    steps:
-      - name: 'Check E2E test results'
-        run: |
-          if [[ (${{ needs.e2e_linux.result }} != 'success' && ${{ needs.e2e_linux.result }} != 'skipped') || \
-               (${{ needs.e2e_mac.result }} != 'success' && ${{ needs.e2e_mac.result }} != 'skipped') ]]; then
-            echo "One or more E2E jobs failed."
-            exit 1
-          fi
-          echo "All required E2E jobs passed!"

.github/workflows/gemini-automated-issue-triage.yml

@@ -46,8 +46,7 @@ jobs:
           ))
         )
       ) &&
-      !contains(github.event.issue.labels.*.name, 'area/') &&
-      !contains(github.event.issue.labels.*.name, 'priority/')
+      !contains(github.event.issue.labels.*.name, 'area/')
     timeout-minutes: 5
     runs-on: 'ubuntu-latest'
     steps:
@@ -81,8 +80,8 @@ jobs:
             exit 1
           fi
 
-          if echo "${LABELS}" | grep -q 'area/' || echo "${LABELS}" | grep -q 'priority/'; then
-            echo "Issue #${ISSUE_NUMBER_INPUT} already has 'area/' or 'priority/' labels. Stopping workflow."
+          if echo "${LABELS}" | grep -q 'area/'; then
+            echo "Issue #${ISSUE_NUMBER_INPUT} already has 'area/' label. Stopping workflow."
             exit 1
           fi
 
@@ -110,11 +109,6 @@ jobs:
               repo: context.repo.repo,
             });
             const allowedLabels = [
-              'priority/p0',
-              'priority/p1',
-              'priority/p2',
-              'priority/p3',
-              'priority/unknown',
               'area/agent',
               'area/enterprise',
               'area/non-interactive',
@@ -161,21 +155,19 @@ jobs:
           prompt: |-
             ## Role
 
-            You are an issue triage assistant. Your role is to analyze a GitHub issue and determine the single most appropriate area/ label and the single most appropriate priority/ label based on the definitions provided.
+            You are an issue triage assistant. Your role is to analyze a GitHub issue and determine the single most appropriate area/ label based on the definitions provided.
 
             ## Steps
             1. Review the issue title and body: ${{ env.ISSUE_TITLE }} and ${{ env.ISSUE_BODY }}.
             2. Review the available labels: ${{ env.AVAILABLE_LABELS }}.
             3. Select exactly one area/ label that best matches the issue based on Reference 1: Area Definitions.
-            4. Select exactly one priority/ label that best matches the issue based on Reference 2: Priority Definitions.
-            5. Fallback Logic:
+            4. Fallback Logic:
                 - If you cannot confidently determine the correct area/ label from the definitions, you must use area/unknown.
-                - If you cannot confidently determine the correct priority/ label from the definitions, you must use priority/unknown.
-            6. Output your two selected labels in JSON format and nothing else. Example:
-                {"labels_to_set": ["area/core", "priority/p1"]}
+            5. Output your selected label in JSON format and nothing else. Example:
+                {"labels_to_set": ["area/core"]}
 
             ## Guidelines
-            - Your output must contain exactly one area/ label and exactly one priority/ label.
+            - Your output must contain exactly one area/ label.
             - Triage only the current issue based on its title and body.
             - Output only valid JSON format.
             - Do not include any explanation or additional text, just the JSON.
@@ -258,38 +250,6 @@ jobs:
             area/unknown
             - Description: Issues that do not clearly fit into any other defined area/ category, or where information is too limited to make a determination. Use this when no other area is appropriate.
 
-            Reference 2: Priority Definitions
-            priority/p0: Critical / Blocker
-            - Definition: A catastrophic failure that makes the CLI unusable for most users or poses a severe security risk. This includes installation failures, authentication failures, persistent crashes, or critical security vulnerabilities.
-            - Key Questions:
-              - Is the CLI failing to install or run?
-              - Does it fail to authenticate or connect to the Gemini API, making all commands useless?
-              - Is it consistently crashing on basic, common commands?
-              - Does this represent a critical security vulnerability?
-
-            priority/p1: High
-            - Definition: A severe issue where a core feature (e.g., text generation, code generation, file processing) is unusable, failing, has severe performance degradation, or providing fundamentally incorrect output formatting (e.g., truncated text, broken JSON). Affects many users, and there is no reasonable workaround.
-            - Key Questions:
-              - Is a core feature failing for a specific, large user group (e.g., all Windows users, all users of a specific shell)?
-              - Is the CLI failing to process a supported input or misinterpreting critical flags?
-              - Is the CLI's output formatting consistently broken, making the response unusable?
-              - Is a core command or feature extremely slow, making it impractical to use?
-
-            priority/p2: Medium
-            - Definition: A moderately impactful issue causing inconvenience or a non-optimal experience, but a reasonable workaround exists. This also includes failures in non-core features.
-            - Key Questions:
-              - Is a command or flag behaving incorrectly, but the user can achieve their goal via other means?
-              - Is there a significant, non-blocking UI/UX problem in the terminal (e.g., broken progress indicators, bad terminal coloring)?
-
-            priority/p3: Low
-            - Definition: A minor, low-impact issue with minimal effect on functionality. This includes most cosmetic defects, typos in documentation, or unclear help text.
-            - Key Questions:
-              - Is this a typo in the README.md, gemini --help text, or other documentation?
-              - Is this a minor cosmetic issue (e.g., text alignment in output, an extra newline) that doesn't affect usability?
-
-            priority/unknown
-            - Description: Issues that do not clearly fit into any other defined priority/ category, or where information is too limited to make a determination. Use this when no other priority is appropriate.
-
       - name: 'Apply Labels to Issue'
         if: |-
           ${{ steps.gemini_issue_analysis.outputs.summary != '' }}
@@ -327,8 +287,8 @@ jobs:
             const issueNumber = parseInt(process.env.ISSUE_NUMBER);
             const labelsToAdd = parsedLabels.labels_to_set || [];
 
-            if (labelsToAdd.length !== 2) {
-              core.setFailed(`Expected exactly 2 labels (one area/ and one priority/), but got ${labelsToAdd.length}. Labels: ${labelsToAdd.join(', ')}`);
+            if (labelsToAdd.length !== 1) {
+              core.setFailed(`Expected exactly 1 label (area/), but got ${labelsToAdd.length}. Labels: ${labelsToAdd.join(', ')}`);
               return;
             }
 

.github/workflows/gemini-automated-pr-size-labeler.yml

@@ -0,0 +1,127 @@
+name: 'Gemini Automated PR Labeler'
+
+on:
+  pull_request_target:
+    types: ['opened', 'reopened', 'synchronize']
+
+jobs:
+  label-pr:
+    timeout-minutes: 10
+    if: |-
+      ${{ github.repository == 'google-gemini/gemini-cli' }}
+    permissions:
+      pull-requests: 'write'
+      contents: 'read'
+      id-token: 'write'
+
+    concurrency:
+      group: '${{ github.workflow }}-${{ github.event.pull_request.number }}'
+      cancel-in-progress: true
+
+    runs-on: 'ubuntu-latest'
+
+    steps:
+      - name: 'Generate GitHub App Token'
+        id: 'generate_token'
+        uses: 'actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e' # v2
+        with:
+          app-id: '${{ secrets.APP_ID }}'
+          private-key: '${{ secrets.PRIVATE_KEY }}'
+          permission-pull-requests: 'write'
+
+      - name: 'Run Gemini PR size and complexity labeller'
+        uses: 'google-github-actions/run-gemini-cli@a3bf79042542528e91937b3a3a6fbc4967ee3c31' # Use the specific commit SHA
+        env:
+          GITHUB_TOKEN: '${{ steps.generate_token.outputs.token }}'
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+          REPOSITORY: '${{ github.repository }}'
+        with:
+          gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
+          gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
+          gcp_location: '${{ vars.GOOGLE_CLOUD_LOCATION }}'
+          gcp_service_account: '${{ vars.SERVICE_ACCOUNT_EMAIL }}'
+          gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
+          use_vertex_ai: '${{ vars.GOOGLE_GENAI_USE_VERTEXAI }}'
+          use_gemini_code_assist: '${{ vars.GOOGLE_GENAI_USE_GCA }}'
+          settings: |
+            {
+              "coreTools": [
+                "run_shell_command(gh pr diff)",
+                "run_shell_command(gh pr edit)",
+                "run_shell_command(gh pr comment)",
+                "run_shell_command(gh pr view)"
+              ],
+              "telemetry": {
+                "enabled": true,
+                "target": "gcp"
+              },
+              "sandbox": false
+            }
+          prompt: |
+            You are a Pull Request labeller and Feedback Assistant. Your primary goal is to improve review velocity and help maintainers prioritize their work by automatically labeling pull requests based on size and complexity, and providing guidance for overly large PRs.
+
+            Steps:
+            1. Retrieve Pull Request Information:
+               - Use `gh pr diff ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }}` to get the diff content.
+               - Parse the output from `gh pr diff` to determine the total lines of code added and deleted. Calculate `TOTAL_LINES_CHANGED`.
+
+            2. Determine Pull Request Size:
+               - Use `gh pr view ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }} --json labels` to get the current labels on the PR.
+               - Check the current labels and identify if any `size/*` labels already exist (e.g., `size/xs`, `size/s`, etc.).
+               - If an old `size/*` label is found and it is different from the newly calculated size, remove it using:
+                 `gh pr edit ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }} --remove-label "size-label-to-remove"`
+               - Based on `TOTAL_LINES_CHANGED`, select the appropriate new size label:
+                 - `size/xs`: < 10 lines changed
+                 - `size/s`: 10-50 lines changed
+                 - `size/m`: 51-200 lines changed
+                 - `size/l`: 201-1000 lines changed
+                 - `size/xl`: > 1000 lines changed
+               - Do not invent new size labels.
+               - Apply the newly determined `size/*` label to the pull request using:
+                 `gh pr edit ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }} --add-label "your-new-size-label"`
+
+            3. Analyze Pull Request Complexity:
+                - Perform Code Change Analysis: Examine the content of the code changes obtained from `gh pr diff ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }}`. Look for indicators of complexity such as:
+                 - Number of files changed (can be inferred from the diff headers).
+                 - Diversity of file types (e.g., changes across different languages, configuration files, documentation).
+                 - Presence of new external dependencies.
+                 - Introduction of new architectural components or significant refactoring.
+                 - Complexity of individual code changes (e.g., deeply nested logic, complex algorithms, extensive conditional statements).
+               - Apply Heuristic-based Complexity Assessment:
+                 - If the PR touches a small number of files with minor changes (e.g., typos, simple bug fixes, small feature additions), categorize it as `review/quick`.
+                 - If the PR involves changes across multiple files, introduces new features, significantly refactors existing code, or has a high line count (even within `size/l`), categorize it as `review/involved`.
+                 - Pay close attention to changes in critical or core modules as these inherently increase complexity.
+               - **Only use the labels `review/quick` or `review/involved` for complexity. Do not invent new complexity labels.**
+               - **Remove any previous `review/*` labels if they no longer apply, similar to the size label process.**
+               - Apply the determined `review/*` label to the pull request using:
+                 `gh pr edit ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }} --add-label "your-complexity-label"`
+
+            4. Handle Overly Large Pull Requests (`size/xl`):
+               - **Conditional Check:** If the pull request has been labeled `size/xl` (i.e., > 1000 lines of code changed) in Step 2, proceed to the next sub-step.
+               - **Post Constructive Comment:** Post a polite and helpful comment on the pull request using:
+                 `gh pr comment ${{ env.PR_NUMBER }} --repo ${{ env.REPOSITORY }} --body "Your comment here"`
+                 The comment body should be:
+                 """
+                 Thanks for your hard work on this pull request!
+
+                 This pull request is quite large, which can make it challenging and time-consuming for reviewers to go through thoroughly.
+
+                 To help us review it more efficiently and get your changes merged faster, we kindly request you consider breaking this into smaller, more focused pull requests. Each smaller PR should ideally address a single logical change or a small set of related changes.
+
+                 For example, you could separate out refactoring, new feature additions, and bug fixes into individual PRs. This makes it easier to understand, review, and test each component independently.
+
+                 We appreciate your understanding and cooperation. Feel free to reach out if you need any assistance with this!
+                 """
+
+            Guidelines:
+            - Automation Focus: All actions should be automated and not require manual intervention.
+            - Non-intrusive: The system should add labels and comments but not modify the code or close the pull request.
+            - Polite and Constructive: All communication, especially for large PRs, must be polite, encouraging, and constructive.
+            - Prioritize Clarity: The labels applied should clearly convey the PR's size and complexity to reviewers.
+            - Adhere to Defined Labels: Only use the specified `size/*` and `review/*` labels. Do not create or apply any other labels.
+            - Utilize `gh CLI`: Interact with GitHub using the `gh` command-line tool for diffing, label management, and commenting.
+            - Execute commands strictly as described in the steps. Do not invent new commands.
+            - In no case should you change other pull request that are not the one you are working on. Which can be found by using env.PR_NUMBER
+            - Execute each step that is defined in the steps section.
+            - In no case should you execute code from the pull request because this could be malicious code.
+            - If you fail to do this step log the errors you received

.github/workflows/gemini-scheduled-stale-issue-closer.yml

@@ -0,0 +1,152 @@
+name: '🔒 Gemini Scheduled Stale Issue Closer'
+
+on:
+  schedule:
+    - cron: '0 0 * * 0' # Every Sunday at midnight UTC
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Run in dry-run mode (no changes applied)'
+        required: false
+        default: false
+        type: 'boolean'
+
+concurrency:
+  group: '${{ github.workflow }}'
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: 'bash'
+
+jobs:
+  close-stale-issues:
+    runs-on: 'ubuntu-latest'
+    permissions:
+      issues: 'write'
+    steps:
+      - name: 'Generate GitHub App Token'
+        id: 'generate_token'
+        uses: 'actions/create-github-app-token@v1'
+        with:
+          app-id: '${{ secrets.APP_ID }}'
+          private-key: '${{ secrets.PRIVATE_KEY }}'
+          permission-issues: 'write'
+
+      - name: 'Process Stale Issues'
+        uses: 'actions/github-script@v7'
+        env:
+          DRY_RUN: '${{ inputs.dry_run }}'
+        with:
+          github-token: '${{ steps.generate_token.outputs.token }}'
+          script: |
+            const dryRun = process.env.DRY_RUN === 'true';
+            if (dryRun) {
+              core.info('DRY RUN MODE ENABLED: No changes will be applied.');
+            }
+            const batchLabel = 'Stale';
+
+            const threeMonthsAgo = new Date();
+            threeMonthsAgo.setMonth(threeMonthsAgo.getMonth() - 3);
+
+            const tenDaysAgo = new Date();
+            tenDaysAgo.setDate(tenDaysAgo.getDate() - 10);
+
+            core.info(`Cutoff date for creation: ${threeMonthsAgo.toISOString()}`);
+            core.info(`Cutoff date for updates: ${tenDaysAgo.toISOString()}`);
+
+            const query = `repo:${context.repo.owner}/${context.repo.repo} is:issue is:open created:<${threeMonthsAgo.toISOString()}`;
+            core.info(`Searching with query: ${query}`);
+
+            const itemsToCheck = await github.paginate(github.rest.search.issuesAndPullRequests, {
+              q: query,
+              sort: 'created',
+              order: 'asc',
+              per_page: 100
+            });
+
+            core.info(`Found ${itemsToCheck.length} open issues to check.`);
+
+            let processedCount = 0;
+
+            for (const issue of itemsToCheck) {
+              const createdAt = new Date(issue.created_at);
+              const updatedAt = new Date(issue.updated_at);
+              const reactionCount = issue.reactions.total_count;
+
+              // Basic thresholds
+              if (reactionCount >= 5) {
+                continue;
+              }
+
+              // Skip if it has a maintainer label
+              if (issue.labels.some(label => label.name.toLowerCase().includes('maintainer'))) {
+                continue;
+              }
+
+              let isStale = updatedAt < tenDaysAgo;
+
+              // If apparently active, check if it's only bot activity
+              if (!isStale) {
+                try {
+                  const comments = await github.rest.issues.listComments({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: issue.number,
+                    per_page: 100,
+                    sort: 'created',
+                    direction: 'desc'
+                  });
+
+                  const lastHumanComment = comments.data.find(comment => comment.user.type !== 'Bot');
+                  if (lastHumanComment) {
+                    isStale = new Date(lastHumanComment.created_at) < tenDaysAgo;
+                  } else {
+                    // No human comments. Check if creator is human.
+                    if (issue.user.type !== 'Bot') {
+                       isStale = createdAt < tenDaysAgo;
+                    } else {
+                       isStale = true; // Bot created, only bot comments
+                    }
+                  }
+                } catch (error) {
+                  core.warning(`Failed to fetch comments for issue #${issue.number}: ${error.message}`);
+                  continue;
+                }
+              }
+
+              if (isStale) {
+                processedCount++;
+                const message = `Closing stale issue #${issue.number}: "${issue.title}" (${issue.html_url})`;
+                core.info(message);
+
+                if (!dryRun) {
+                  // Add label
+                  await github.rest.issues.addLabels({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: issue.number,
+                    labels: [batchLabel]
+                  });
+
+                  // Add comment
+                  await github.rest.issues.createComment({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: issue.number,
+                    body: 'Hello! As part of our effort to keep our backlog manageable and focus on the most active issues, we are tidying up older reports.\n\nIt looks like this issue hasn\'t been active for a while, so we are closing it for now. However, if you are still experiencing this bug on the latest stable build, please feel free to comment on this issue or create a new one with updated details.\n\nThank you for your contribution!'
+                  });
+
+                  // Close issue
+                  await github.rest.issues.update({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: issue.number,
+                    state: 'closed',
+                    state_reason: 'not_planned'
+                  });
+                }
+              }
+            }
+
+            core.info(`\nTotal issues processed: ${processedCount}`);

.github/workflows/trigger_e2e.yml

@@ -3,11 +3,15 @@ name: 'Trigger E2E'
 on:
   workflow_dispatch:
     inputs:
-      branch_ref:
-        description: 'Branch to run on'
-        required: true
-        default: 'main'
+      repo_name:
+        description: 'Repository name (e.g., owner/repo)'
+        required: false
         type: 'string'
+      head_sha:
+        description: 'SHA of the commit to test'
+        required: false
+        type: 'string'
+  pull_request:
 
 jobs:
   save_repo_name:
@@ -15,11 +19,12 @@ jobs:
     steps:
       - name: 'Save Repo name'
         env:
-          # Replace with github.event.pull_request.head.repo.full_name when switched to listen on pull request events. This repo name does not contain the org which is needed for checkout.
-          REPO_NAME: '${{ github.event.repository.name }}'
+          REPO_NAME: '${{ github.event.inputs.repo_name || github.event.pull_request.head.repo.full_name }}'
+          HEAD_SHA: '${{ github.event.inputs.head_sha || github.event.pull_request.head.sha }}'
         run: |
           mkdir -p ./pr
           echo '${{ env.REPO_NAME }}' > ./pr/repo_name
+          echo '${{ env.HEAD_SHA }}' > ./pr/head_sha
       - uses: 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02' # ratchet:actions/upload-artifact@v4
         with:
           name: 'repo_name'

CONTRIBUTING.md

@@ -41,7 +41,9 @@ This project follows
 
 The process for contributing code is as follows:
 
-1.  **Find an issue** that you want to work on.
+1.  **Find an issue** that you want to work on. If an issue is tagged as
+    "🔒Maintainers only", this means it is reserved for project maintainers. We
+    will not accept pull requests related to these issues.
 2.  **Fork the repository** and create a new branch.
 3.  **Make your changes** in the `packages/` directory.
 4.  **Ensure all checks pass** by running `npm run preflight`.

README.md

@@ -1,7 +1,7 @@
 # Gemini CLI
 
 [![Gemini CLI CI](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml)
-[![Gemini CLI E2E](https://github.com/google-gemini/gemini-cli/actions/workflows/e2e.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/e2e.yml)
+[![Gemini CLI E2E (Chained)](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml)
 [![Version](https://img.shields.io/npm/v/@google/gemini-cli)](https://www.npmjs.com/package/@google/gemini-cli)
 [![License](https://img.shields.io/github/license/google-gemini/gemini-cli)](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE)
 [![View Code Wiki](https://www.gstatic.com/_/boq-sdlc-agents-ui/_/r/YUi5dj2UWvE.svg)](https://codewiki.google/github.com/google-gemini/gemini-cli)

docs/changelogs/index.md

@@ -1,15 +1,97 @@
-# Gemini CLI Changelog
+# Gemini CLI release notes
 
-Wondering what's new in Gemini CLI? This document provides key highlights and
-notable changes to Gemini CLI.
+Gemini CLI has three major release channels: nightly, preview, and stable. For
+most users, we recommend the stable release.
 
-## v0.15.0 - Gemini CLI weekly update - 2025-11-03
+On this page, you can find information regarding the current releases and
+announcements from each release.
 
-- **🎉 Seamless scrollable UI & mouse support:** We’ve given Gemini CLI a major
-  facelift to make your terminal experience smoother and much more polished. You
-  now get a flicker-free display with sticky headers that keep important context
-  visible and a stable input prompt that doesn't jump around. We even added
-  mouse support so you can click right where you need to type!
+For the full changelog, refer to
+[Releases - google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli/releases)
+on GitHub.
+
+## Current releases
+
+| Release channel       | Notes                                           |
+| :-------------------- | :---------------------------------------------- |
+| Nightly               | Nightly release with the most recent changes.   |
+| [Preview](preview.md) | Experimental features ready for early feedback. |
+| [Stable](latest.md)   | Stable, recommended for general use.            |
+
+## Announcements: v0.19.0 - 2025-11-24
+
+- 🎉 **New extensions:**
+  - **Eleven Labs:** Create, play, manage your audio play tracks with the Eleven
+    Labs Gemini CLI extension:
+    `gemini extensions install https://github.com/elevenlabs/elevenlabs-mcp`
+- **Zed integration:** Users can now leverage Gemini 3 within the Zed
+  integration after enabling "Preview Features" in their CLI’s `/settings`.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/13398) by
+  [@benbrandt](https://github.com/benbrandt))
+- **Interactive shell:**
+  - **Click-to-Focus:** When "Use Alternate Buffer" setting is enabled, users
+    can click within the embedded shell output to focus it for input.
+    ([pr](https://github.com/google-gemini/gemini-cli/pull/13341) by
+    [@galz10](https://github.com/galz10))
+  - **Loading phrase:** Clearly indicates when the interactive shell is awaiting
+    user input. ([vid](https://imgur.com/a/kjK8bUK),
+    [pr](https://github.com/google-gemini/gemini-cli/pull/12535) by
+    [@jackwotherspoon](https://github.com/jackwotherspoon))
+
+## Announcements: v0.18.0 - 2025-11-17
+
+- 🎉 **New extensions:**
+  - **Google Workspace**: Integrate Gemini CLI with your Workspace data. Write
+    docs, build slides, chat with others or even get your calc on in sheets:
+    `gemini extensions install https://github.com/gemini-cli-extensions/workspace`
+    - Blog:
+      [https://allen.hutchison.org/2025/11/19/bringing-the-office-to-the-terminal/](https://allen.hutchison.org/2025/11/19/bringing-the-office-to-the-terminal/)
+  - **Redis:** Manage and search data in Redis with natural language:
+    `gemini extensions install https://github.com/redis/mcp-redis`
+  - **Anomalo:** Query your data warehouse table metadata and quality status
+    through commands and natural language:
+    `gemini extensions install https://github.com/datagravity-ai/anomalo-gemini-extension`
+- **Experimental permission improvements:** We are now experimenting with a new
+  policy engine in Gemini CLI. This allows users and administrators to create
+  fine-grained policy for tool calls. Currently behind a flag. See
+  [https://geminicli.com/docs/core/policy-engine/](../core/policy-engine.md) for
+  more information.
+  - Blog:
+    [https://allen.hutchison.org/2025/11/26/the-guardrails-of-autonomy/](https://allen.hutchison.org/2025/11/26/the-guardrails-of-autonomy/)
+- **Gemini 3 support for paid:** Gemini 3 support has been rolled out to all API
+  key, Google AI Pro or Google AI Ultra (for individuals, not businesses) and
+  Gemini Code Assist Enterprise users. Enable it via `/settings` and toggling on
+  **Preview Features**.
+- **Updated UI rollback:** We’ve temporarily rolled back our updated UI to give
+  it more time to bake. This means for a time you won’t have embedded scrolling
+  or mouse support. You can re-enable with `/settings` -> **Use Alternate Screen
+  Buffer** -> `true`.
+- **Model in history:** Users can now toggle in `/settings` to display model in
+  their chat history. ([gif](https://imgur.com/a/uEmNKnQ),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/13034) by
+  [@scidomino](https://github.com/scidomino))
+- **Multi-uninstall:** Users can now uninstall multiple extensions with a single
+  command. ([pic](https://imgur.com/a/9Dtq8u2),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/13016) by
+  [@JayadityaGit](https://github.com/JayadityaGit))
+
+## Announcements: v0.16.0 - 2025-11-10
+
+- **Gemini 3 + Gemini CLI:** launch 🚀🚀🚀
+- **Data Commons Gemini CLI Extension** - A new Data Commons Gemini CLI
+  extension that lets you query open-source statistical data from
+  datacommons.org. **To get started, you'll need a Data Commons API key and uv
+  installed**. These and other details to get you started with the extension can
+  be found at
+  [https://github.com/gemini-cli-extensions/datacommons](https://github.com/gemini-cli-extensions/datacommons).
+
+## Announcements: v0.15.0 - 2025-11-03
+
+- **🎉 Seamless scrollable UI and mouse support:** We’ve given Gemini CLI a
+  major facelift to make your terminal experience smoother and much more
+  polished. You now get a flicker-free display with sticky headers that keep
+  important context visible and a stable input prompt that doesn't jump around.
+  We even added mouse support so you can click right where you need to type!
   ([gif](https://imgur.com/a/O6qc7bx),
   [@jacob314](https://github.com/jacob314)).
   - **Announcement:**
@@ -49,7 +131,7 @@ notable changes to Gemini CLI.
   correctly. ([pr](https://github.com/google-gemini/gemini-cli/pull/12186) by
   [@kevinjwang1](https://github.com/kevinjwang1)).
 
-## v0.12.0 - Gemini CLI weekly update - 2025-10-27
+## Announcements: v0.12.0 - 2025-10-27
 
 ![Codebase investigator subagent in Gemini CLI.](https://i.imgur.com/4J1njsx.png)
 
@@ -112,7 +194,7 @@ notable changes to Gemini CLI.
   ([pr](https://github.com/google-gemini/gemini-cli/pull/11593) by
   [@joshualitt](https://github.com/joshualitt)).
 
-## v0.11.0 - Gemini CLI weekly update - 2025-10-20
+## Announcements: v0.11.0 - 2025-10-20
 
 ![Gemini CLI and Jules](https://storage.googleapis.com/gweb-developer-goog-blog-assets/images/Jules_Extension_-_Blog_Header_O346JNt.original.png)
 
@@ -155,7 +237,7 @@ notable changes to Gemini CLI.
     ([pr](https://github.com/google-gemini/gemini-cli/pull/11318) by
     [@allenhutchison](https://github.com/allenhutchison))
 
-## v0.10.0 - Gemini CLI weekly update - 2025-10-13
+## Announcements: v0.10.0 - 2025-10-13
 
 - **Polish:** The team has been heads down bug fixing and investing heavily into
   polishing existing flows, tools, and interactions.
@@ -172,7 +254,7 @@ notable changes to Gemini CLI.
   ([pr](https://github.com/google-gemini/gemini-cli/pull/10819) by
   [@jerop](https://github.com/jerop)).
 
-## v0.9.0 - Gemini CLI weekly update - 2025-10-06
+## Announcements: v0.9.0 - 2025-10-06
 
 - 🎉 **Interactive Shell:** Run interactive commands like `vim`, `rebase -i`, or
   even `gemini` 😎 directly in Gemini CLI:
@@ -197,7 +279,7 @@ notable changes to Gemini CLI.
   ([pr](https://github.com/google-gemini/gemini-cli/pull/10108) by
   [@sgnagnarella](https://github.com/sgnagnarella))
 
-## v0.8.0 - Gemini CLI weekly update - 2025-09-29
+## Announcements: v0.8.0 - 2025-09-29
 
 - 🎉 **Announcing Gemini CLI Extensions** 🎉
   - Completely customize your Gemini CLI experience to fit your workflow.
@@ -236,7 +318,7 @@ notable changes to Gemini CLI.
   changes, smaller features, UI updates, reliability and bug fixes + general
   polish made it in this week!
 
-## v0.7.0 - Gemini CLI weekly update - 2025-09-22
+## Announcements: v0.7.0 - 2025-09-22
 
 - 🎉**Build your own Gemini CLI IDE plugin:** We've published a spec for
   creating IDE plugins to enable rich context-aware experiences and native
@@ -274,7 +356,7 @@ notable changes to Gemini CLI.
   changes, smaller features, UI updates, reliability and bug fixes + general
   polish made it in this week!
 
-## v0.6.0 - Gemini CLI weekly update - 2025-09-15
+## Announcements: v0.6.0 - 2025-09-15
 
 - 🎉 **Higher limits for Google AI Pro and Ultra subscribers:** We’re psyched to
   finally announce that Google AI Pro and AI Ultra subscribers now get access to
@@ -355,7 +437,7 @@ notable changes to Gemini CLI.
   changes, smaller features, UI updates, reliability and bug fixes + general
   polish made it in this week!
 
-## v0.5.0 - Gemini CLI weekly update - 2025-09-08
+## Announcements: v0.5.0 - 2025-09-08
 
 - 🎉**FastMCP + Gemini CLI**🎉: Quickly install and manage your Gemini CLI MCP
   servers with FastMCP ([video](https://imgur.com/a/m8QdCPh),
@@ -400,7 +482,7 @@ notable changes to Gemini CLI.
   changes, smaller features, UI updates, reliability and bug fixes + general
   polish made it in this week!
 
-## v0.4.0 - Gemini CLI weekly update - 2025-09-01
+## Announcements: v0.4.0 - 2025-09-01
 
 - 🎉**Gemini CLI CloudRun and Security Integrations**🎉: Automate app deployment
   and security analysis with CloudRun and Security extension integrations. Once

docs/changelogs/latest.md

@@ -0,0 +1,154 @@
+# Latest stable release: v0.19.0 - v0.19.4
+
+Released: December 1, 2025
+
+For most users, our latest stable release is the recommended release. Install
+the latest stable version with:
+
+```
+npm install -g @google/gemini-cli
+```
+
+## Highlights
+
+- **Zed integration:** Users can now leverage Gemini 3 within the Zed
+  integration after enabling "Preview Features" in their CLI’s `/settings`.
+- **Interactive shell:**
+  - **Click-to-Focus:** Go to `/settings` and enable **Use Alternate Buffer** to
+    click within the embedded shell output to focus it for input.
+  - **Loading phrase:** Clearly indicates when the interactive shell is awaiting
+    user input. ([vid](https://imgur.com/a/kjK8bUK),
+    [pr](https://github.com/google-gemini/gemini-cli/pull/12535) by
+    [@jackwotherspoon](https://github.com/jackwotherspoon))
+
+## What's Changed
+
+- Use lenient MCP output schema validator by @cornmander in
+  https://github.com/google-gemini/gemini-cli/pull/13521
+- Update persistence state to track counts of messages instead of times banner
+  has been displayed by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13428
+- update docs for http proxy by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13538
+- move stdio by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13528
+- chore(release): bump version to 0.19.0-nightly.20251120.8e531dc02 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13540
+- Skip pre-commit hooks for shadow repo (#13331) by @vishvananda in
+  https://github.com/google-gemini/gemini-cli/pull/13488
+- fix(ui): Correct mouse click cursor positioning for wide characters by
+  @SandyTao520 in https://github.com/google-gemini/gemini-cli/pull/13537
+- fix(core): correct bash @P prompt transformation detection by @pyrytakala in
+  https://github.com/google-gemini/gemini-cli/pull/13544
+- Optimize and improve test coverage for cli/src/config by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13485
+- Improve code coverage for cli/src/ui/privacy package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13493
+- docs: fix typos in source code and documentation by @fancive in
+  https://github.com/google-gemini/gemini-cli/pull/13577
+- Improved code coverage for cli/src/zed-integration by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13570
+- feat(ui): build interactive session browser component by @bl-ue in
+  https://github.com/google-gemini/gemini-cli/pull/13351
+- Fix multiple bugs with auth flow including using the implemented but unused
+  restart support. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13565
+- feat(core): add modelAvailabilityService for managing and tracking model
+  health by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13426
+- docs: fix grammar typo "a MCP" to "an MCP" by @noahacgn in
+  https://github.com/google-gemini/gemini-cli/pull/13595
+- feat: custom loading phrase when interactive shell requires input by
+  @jackwotherspoon in https://github.com/google-gemini/gemini-cli/pull/12535
+- docs: Update uninstall command to reflect multiple extension support by
+  @JayadityaGit in https://github.com/google-gemini/gemini-cli/pull/13582
+- bug(core): Ensure we use thinking budget on fallback to 2.5 by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13596
+- Remove useModelRouter experimental flag by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13593
+- feat(docs): Ensure multiline JS objects are rendered properly. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13535
+- Fix exp id logging by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13430
+- Moved client id logging into createBasicLogEvent by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13607
+- Restore bracketed paste mode after external editor exit by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13606
+- feat(core): Add support for custom aliases for model configs. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13546
+- feat(core): Add `BaseLlmClient.generateContent`. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13591
+- Turn off alternate buffer mode by default. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13623
+- fix(cli): Prevent stdout/stderr patching for extension commands by @chrstnb in
+  https://github.com/google-gemini/gemini-cli/pull/13600
+- Improve test coverage for cli/src/ui/components by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13598
+- Update ink version to 6.4.6 by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13631
+- chore/release: bump version to 0.19.0-nightly.20251122.42c2e1b21 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13637
+- chore/release: bump version to 0.19.0-nightly.20251123.dadd606c0 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13675
+- chore/release: bump version to 0.19.0-nightly.20251124.e177314a4 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13713
+- fix(core): Fix context window overflow warning for PDF files by @kkitase in
+  https://github.com/google-gemini/gemini-cli/pull/13548
+- feat :rephrasing the extension logging messages to run the explore command
+  when there are no extensions installed by @JayadityaGit in
+  https://github.com/google-gemini/gemini-cli/pull/13740
+- Improve code coverage for cli package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13724
+- Add session subtask in /stats command by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13750
+- feat(core): Migrate chatCompressionService to model configs. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/12863
+- feat(hooks): Hook Telemetry Infrastructure by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9082
+- fix: (some minor improvements to configs and getPackageJson return behaviour)
+  by @grMLEqomlkkU5Eeinz4brIrOVCUCkJuN in
+  https://github.com/google-gemini/gemini-cli/pull/12510
+- feat(hooks): Hook Event Handling by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9097
+- feat(hooks): Hook Agent Lifecycle Integration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9105
+- feat(core): Land bool for alternate system prompt. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13764
+- bug(core): Add default chat compression config. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13766
+- feat(model-availability): introduce ModelPolicy and PolicyCatalog by
+  @adamfweidman in https://github.com/google-gemini/gemini-cli/pull/13751
+- feat(hooks): Hook System Orchestration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9102
+- feat(config): add isModelAvailabilityServiceEnabled setting by @adamfweidman
+  in https://github.com/google-gemini/gemini-cli/pull/13777
+- chore/release: bump version to 0.19.0-nightly.20251125.f6d97d448 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13782
+- chore: remove console.error by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13779
+- fix: Add $schema property to settings.schema.json by @sacrosanctic in
+  https://github.com/google-gemini/gemini-cli/pull/12763
+- fix(cli): allow non-GitHub SCP-styled URLs for extension installation by @m0ps
+  in https://github.com/google-gemini/gemini-cli/pull/13800
+- fix(resume): allow passing a prompt via stdin while resuming using --resume by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13520
+- feat(sessions): add /resume slash command to open the session browser by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13621
+- docs(sessions): add documentation for chat recording and session management by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13667
+- Fix TypeError: "URL.parse is not a function" for Node.js < v22 by @macarronesc
+  in https://github.com/google-gemini/gemini-cli/pull/13698
+- fallback to flash for TerminalQuota errors by @sehoon38 in
+  https://github.com/google-gemini/gemini-cli/pull/13791
+- Update Code Wiki README badge by @PatoBeltran in
+  https://github.com/google-gemini/gemini-cli/pull/13768
+- Add Databricks auth support and custom header option to gemini cli by
+  @AarushiShah in https://github.com/google-gemini/gemini-cli/pull/11893
+- Update dependency for modelcontextprotocol/sdk to 1.23.0 by @bbiggs in
+  https://github.com/google-gemini/gemini-cli/pull/13827
+- fix(patch): cherry-pick 576fda1 to release/v0.19.0-preview.0-pr-14099
+  [CONFLICTS] by @gemini-cli-robot in
+  https://github.com/google-gemini/gemini-cli/pull/14402
+
+**Full Changelog**:
+https://github.com/google-gemini/gemini-cli/compare/v0.18.4...v0.19.0

docs/changelogs/preview.md

@@ -0,0 +1,141 @@
+# Preview release: Release v0.19.0-preview.0
+
+Released: November 25, 2025
+
+Our preview release includes the latest, new, and experimental features. This
+release may not be as stable as our [latest weekly release](latest.md).
+
+To install the preview release:
+
+```
+npm install -g @google/gemini-cli@preview
+```
+
+## What's changed
+
+- Use lenient MCP output schema validator by @cornmander in
+  https://github.com/google-gemini/gemini-cli/pull/13521
+- Update persistence state to track counts of messages instead of times banner
+  has been displayed by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13428
+- update docs for http proxy by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13538
+- move stdio by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13528
+- chore(release): bump version to 0.19.0-nightly.20251120.8e531dc02 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13540
+- Skip pre-commit hooks for shadow repo (#13331) by @vishvananda in
+  https://github.com/google-gemini/gemini-cli/pull/13488
+- fix(ui): Correct mouse click cursor positioning for wide characters by
+  @SandyTao520 in https://github.com/google-gemini/gemini-cli/pull/13537
+- fix(core): correct bash @P prompt transformation detection by @pyrytakala in
+  https://github.com/google-gemini/gemini-cli/pull/13544
+- Optimize and improve test coverage for cli/src/config by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13485
+- Improve code coverage for cli/src/ui/privacy package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13493
+- docs: fix typos in source code and documentation by @fancive in
+  https://github.com/google-gemini/gemini-cli/pull/13577
+- Improved code coverage for cli/src/zed-integration by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13570
+- feat(ui): build interactive session browser component by @bl-ue in
+  https://github.com/google-gemini/gemini-cli/pull/13351
+- Fix multiple bugs with auth flow including using the implemented but unused
+  restart support. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13565
+- feat(core): add modelAvailabilityService for managing and tracking model
+  health by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13426
+- docs: fix grammar typo "a MCP" to "an MCP" by @noahacgn in
+  https://github.com/google-gemini/gemini-cli/pull/13595
+- feat: custom loading phrase when interactive shell requires input by
+  @jackwotherspoon in https://github.com/google-gemini/gemini-cli/pull/12535
+- docs: Update uninstall command to reflect multiple extension support by
+  @JayadityaGit in https://github.com/google-gemini/gemini-cli/pull/13582
+- bug(core): Ensure we use thinking budget on fallback to 2.5 by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13596
+- Remove useModelRouter experimental flag by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13593
+- feat(docs): Ensure multiline JS objects are rendered properly. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13535
+- Fix exp id logging by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13430
+- Moved client id logging into createBasicLogEvent by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13607
+- Restore bracketed paste mode after external editor exit by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13606
+- feat(core): Add support for custom aliases for model configs. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13546
+- feat(core): Add `BaseLlmClient.generateContent`. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13591
+- Turn off alternate buffer mode by default. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13623
+- fix(cli): Prevent stdout/stderr patching for extension commands by @chrstnb in
+  https://github.com/google-gemini/gemini-cli/pull/13600
+- Improve test coverage for cli/src/ui/components by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13598
+- Update ink version to 6.4.6 by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13631
+- chore/release: bump version to 0.19.0-nightly.20251122.42c2e1b21 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13637
+- chore/release: bump version to 0.19.0-nightly.20251123.dadd606c0 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13675
+- chore/release: bump version to 0.19.0-nightly.20251124.e177314a4 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13713
+- fix(core): Fix context window overflow warning for PDF files by @kkitase in
+  https://github.com/google-gemini/gemini-cli/pull/13548
+- feat :rephrasing the extension logging messages to run the explore command
+  when there are no extensions installed by @JayadityaGit in
+  https://github.com/google-gemini/gemini-cli/pull/13740
+- Improve code coverage for cli package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13724
+- Add session subtask in /stats command by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13750
+- feat(core): Migrate chatCompressionService to model configs. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/12863
+- feat(hooks): Hook Telemetry Infrastructure by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9082
+- fix: (some minor improvements to configs and getPackageJson return behaviour)
+  by @grMLEqomlkkU5Eeinz4brIrOVCUCkJuN in
+  https://github.com/google-gemini/gemini-cli/pull/12510
+- feat(hooks): Hook Event Handling by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9097
+- feat(hooks): Hook Agent Lifecycle Integration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9105
+- feat(core): Land bool for alternate system prompt. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13764
+- bug(core): Add default chat compression config. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13766
+- feat(model-availability): introduce ModelPolicy and PolicyCatalog by
+  @adamfweidman in https://github.com/google-gemini/gemini-cli/pull/13751
+- feat(hooks): Hook System Orchestration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9102
+- feat(config): add isModelAvailabilityServiceEnabled setting by @adamfweidman
+  in https://github.com/google-gemini/gemini-cli/pull/13777
+- chore/release: bump version to 0.19.0-nightly.20251125.f6d97d448 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13782
+- chore: remove console.error by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13779
+- fix: Add $schema property to settings.schema.json by @sacrosanctic in
+  https://github.com/google-gemini/gemini-cli/pull/12763
+- fix(cli): allow non-GitHub SCP-styled URLs for extension installation by @m0ps
+  in https://github.com/google-gemini/gemini-cli/pull/13800
+- fix(resume): allow passing a prompt via stdin while resuming using --resume by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13520
+- feat(sessions): add /resume slash command to open the session browser by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13621
+- docs(sessions): add documentation for chat recording and session management by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13667
+- Fix TypeError: "URL.parse is not a function" for Node.js < v22 by @macarronesc
+  in https://github.com/google-gemini/gemini-cli/pull/13698
+- fallback to flash for TerminalQuota errors by @sehoon38 in
+  https://github.com/google-gemini/gemini-cli/pull/13791
+- Update Code Wiki README badge by @PatoBeltran in
+  https://github.com/google-gemini/gemini-cli/pull/13768
+- Add Databricks auth support and custom header option to gemini cli by
+  @AarushiShah in https://github.com/google-gemini/gemini-cli/pull/11893
+- Update dependency for modelcontextprotocol/sdk to 1.23.0 by @bbiggs in
+  https://github.com/google-gemini/gemini-cli/pull/13827
+
+**Full Changelog**:
+https://github.com/google-gemini/gemini-cli/compare/v0.18.0-preview.4...v0.19.0-preview.0

docs/changelogs/releases.md

@@ -0,0 +1,430 @@
+# Gemini CLI changelog
+
+Gemini CLI has three major release channels: nightly, preview, and stable. For
+most users, we recommend the stable release.
+
+On this page, you can find information regarding the current releases and
+highlights from each release.
+
+For the full changelog, including nightly releases, refer to
+[Releases - google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli/releases)
+on GitHub.
+
+## Current Releases
+
+| Release channel                            | Notes                                           |
+| :----------------------------------------- | :---------------------------------------------- |
+| Nightly                                    | Nightly release with the most recent changes.   |
+| [Preview](#release-v0190-preview0-preview) | Experimental features ready for early feedback. |
+| [Latest](#release-v0190---v0194-latest)    | Stable, recommended for general use.            |
+
+## Release v0.19.0 - v0.19.4 (Latest)
+
+## Highlights
+
+- **Zed integration:** Users can now leverage Gemini 3 within the Zed
+  integration after enabling "Preview Features" in their CLI’s `/settings`.
+- **Interactive shell:**
+  - **Click-to-Focus:** Go to `/settings` and enable **Use Alternate Buffer**
+    WhenUse Alternate Buffer" setting is enabled users can click within the
+    embedded shell output to focus it for input.
+  - **Loading phrase:** Clearly indicates when the interactive shell is awaiting
+    user input. ([vid](https://imgur.com/a/kjK8bUK),
+    [pr](https://github.com/google-gemini/gemini-cli/pull/12535) by
+    [@jackwotherspoon](https://github.com/jackwotherspoon))
+
+### What's Changed
+
+- Use lenient MCP output schema validator by @cornmander in
+  https://github.com/google-gemini/gemini-cli/pull/13521
+- Update persistence state to track counts of messages instead of times banner
+  has been displayed by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13428
+- update docs for http proxy by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13538
+- move stdio by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13528
+- chore(release): bump version to 0.19.0-nightly.20251120.8e531dc02 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13540
+- Skip pre-commit hooks for shadow repo (#13331) by @vishvananda in
+  https://github.com/google-gemini/gemini-cli/pull/13488
+- fix(ui): Correct mouse click cursor positioning for wide characters by
+  @SandyTao520 in https://github.com/google-gemini/gemini-cli/pull/13537
+- fix(core): correct bash @P prompt transformation detection by @pyrytakala in
+  https://github.com/google-gemini/gemini-cli/pull/13544
+- Optimize and improve test coverage for cli/src/config by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13485
+- Improve code coverage for cli/src/ui/privacy package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13493
+- docs: fix typos in source code and documentation by @fancive in
+  https://github.com/google-gemini/gemini-cli/pull/13577
+- Improved code coverage for cli/src/zed-integration by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13570
+- feat(ui): build interactive session browser component by @bl-ue in
+  https://github.com/google-gemini/gemini-cli/pull/13351
+- Fix multiple bugs with auth flow including using the implemented but unused
+  restart support. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13565
+- feat(core): add modelAvailabilityService for managing and tracking model
+  health by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13426
+- docs: fix grammar typo "a MCP" to "an MCP" by @noahacgn in
+  https://github.com/google-gemini/gemini-cli/pull/13595
+- feat: custom loading phrase when interactive shell requires input by
+  @jackwotherspoon in https://github.com/google-gemini/gemini-cli/pull/12535
+- docs: Update uninstall command to reflect multiple extension support by
+  @JayadityaGit in https://github.com/google-gemini/gemini-cli/pull/13582
+- bug(core): Ensure we use thinking budget on fallback to 2.5 by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13596
+- Remove useModelRouter experimental flag by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13593
+- feat(docs): Ensure multiline JS objects are rendered properly. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13535
+- Fix exp id logging by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13430
+- Moved client id logging into createBasicLogEvent by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13607
+- Restore bracketed paste mode after external editor exit by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13606
+- feat(core): Add support for custom aliases for model configs. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13546
+- feat(core): Add `BaseLlmClient.generateContent`. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13591
+- Turn off alternate buffer mode by default. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13623
+- fix(cli): Prevent stdout/stderr patching for extension commands by @chrstnb in
+  https://github.com/google-gemini/gemini-cli/pull/13600
+- Improve test coverage for cli/src/ui/components by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13598
+- Update ink version to 6.4.6 by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13631
+- chore/release: bump version to 0.19.0-nightly.20251122.42c2e1b21 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13637
+- chore/release: bump version to 0.19.0-nightly.20251123.dadd606c0 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13675
+- chore/release: bump version to 0.19.0-nightly.20251124.e177314a4 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13713
+- fix(core): Fix context window overflow warning for PDF files by @kkitase in
+  https://github.com/google-gemini/gemini-cli/pull/13548
+- feat :rephrasing the extension logging messages to run the explore command
+  when there are no extensions installed by @JayadityaGit in
+  https://github.com/google-gemini/gemini-cli/pull/13740
+- Improve code coverage for cli package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13724
+- Add session subtask in /stats command by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13750
+- feat(core): Migrate chatCompressionService to model configs. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/12863
+- feat(hooks): Hook Telemetry Infrastructure by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9082
+- fix: (some minor improvements to configs and getPackageJson return behaviour)
+  by @grMLEqomlkkU5Eeinz4brIrOVCUCkJuN in
+  https://github.com/google-gemini/gemini-cli/pull/12510
+- feat(hooks): Hook Event Handling by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9097
+- feat(hooks): Hook Agent Lifecycle Integration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9105
+- feat(core): Land bool for alternate system prompt. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13764
+- bug(core): Add default chat compression config. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13766
+- feat(model-availability): introduce ModelPolicy and PolicyCatalog by
+  @adamfweidman in https://github.com/google-gemini/gemini-cli/pull/13751
+- feat(hooks): Hook System Orchestration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9102
+- feat(config): add isModelAvailabilityServiceEnabled setting by @adamfweidman
+  in https://github.com/google-gemini/gemini-cli/pull/13777
+- chore/release: bump version to 0.19.0-nightly.20251125.f6d97d448 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13782
+- chore: remove console.error by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13779
+- fix: Add $schema property to settings.schema.json by @sacrosanctic in
+  https://github.com/google-gemini/gemini-cli/pull/12763
+- fix(cli): allow non-GitHub SCP-styled URLs for extension installation by @m0ps
+  in https://github.com/google-gemini/gemini-cli/pull/13800
+- fix(resume): allow passing a prompt via stdin while resuming using --resume by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13520
+- feat(sessions): add /resume slash command to open the session browser by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13621
+- docs(sessions): add documentation for chat recording and session management by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13667
+- Fix TypeError: "URL.parse is not a function" for Node.js < v22 by @macarronesc
+  in https://github.com/google-gemini/gemini-cli/pull/13698
+- fallback to flash for TerminalQuota errors by @sehoon38 in
+  https://github.com/google-gemini/gemini-cli/pull/13791
+- Update Code Wiki README badge by @PatoBeltran in
+  https://github.com/google-gemini/gemini-cli/pull/13768
+- Add Databricks auth support and custom header option to gemini cli by
+  @AarushiShah in https://github.com/google-gemini/gemini-cli/pull/11893
+- Update dependency for modelcontextprotocol/sdk to 1.23.0 by @bbiggs in
+  https://github.com/google-gemini/gemini-cli/pull/13827
+- fix(patch): cherry-pick 576fda1 to release/v0.19.0-preview.0-pr-14099
+  [CONFLICTS] by @gemini-cli-robot in
+  https://github.com/google-gemini/gemini-cli/pull/14402
+
+**Full Changelog**:
+https://github.com/google-gemini/gemini-cli/compare/v0.18.4...v0.19.0
+
+## Release v0.19.0-preview.0 (Preview)
+
+### What's Changed
+
+- Use lenient MCP output schema validator by @cornmander in
+  https://github.com/google-gemini/gemini-cli/pull/13521
+- Update persistence state to track counts of messages instead of times banner
+  has been displayed by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13428
+- update docs for http proxy by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13538
+- move stdio by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13528
+- chore(release): bump version to 0.19.0-nightly.20251120.8e531dc02 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13540
+- Skip pre-commit hooks for shadow repo (#13331) by @vishvananda in
+  https://github.com/google-gemini/gemini-cli/pull/13488
+- fix(ui): Correct mouse click cursor positioning for wide characters by
+  @SandyTao520 in https://github.com/google-gemini/gemini-cli/pull/13537
+- fix(core): correct bash @P prompt transformation detection by @pyrytakala in
+  https://github.com/google-gemini/gemini-cli/pull/13544
+- Optimize and improve test coverage for cli/src/config by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13485
+- Improve code coverage for cli/src/ui/privacy package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13493
+- docs: fix typos in source code and documentation by @fancive in
+  https://github.com/google-gemini/gemini-cli/pull/13577
+- Improved code coverage for cli/src/zed-integration by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13570
+- feat(ui): build interactive session browser component by @bl-ue in
+  https://github.com/google-gemini/gemini-cli/pull/13351
+- Fix multiple bugs with auth flow including using the implemented but unused
+  restart support. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13565
+- feat(core): add modelAvailabilityService for managing and tracking model
+  health by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13426
+- docs: fix grammar typo "a MCP" to "an MCP" by @noahacgn in
+  https://github.com/google-gemini/gemini-cli/pull/13595
+- feat: custom loading phrase when interactive shell requires input by
+  @jackwotherspoon in https://github.com/google-gemini/gemini-cli/pull/12535
+- docs: Update uninstall command to reflect multiple extension support by
+  @JayadityaGit in https://github.com/google-gemini/gemini-cli/pull/13582
+- bug(core): Ensure we use thinking budget on fallback to 2.5 by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13596
+- Remove useModelRouter experimental flag by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13593
+- feat(docs): Ensure multiline JS objects are rendered properly. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13535
+- Fix exp id logging by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13430
+- Moved client id logging into createBasicLogEvent by @owenofbrien in
+  https://github.com/google-gemini/gemini-cli/pull/13607
+- Restore bracketed paste mode after external editor exit by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13606
+- feat(core): Add support for custom aliases for model configs. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13546
+- feat(core): Add `BaseLlmClient.generateContent`. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13591
+- Turn off alternate buffer mode by default. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13623
+- fix(cli): Prevent stdout/stderr patching for extension commands by @chrstnb in
+  https://github.com/google-gemini/gemini-cli/pull/13600
+- Improve test coverage for cli/src/ui/components by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13598
+- Update ink version to 6.4.6 by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13631
+- chore/release: bump version to 0.19.0-nightly.20251122.42c2e1b21 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13637
+- chore/release: bump version to 0.19.0-nightly.20251123.dadd606c0 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13675
+- chore/release: bump version to 0.19.0-nightly.20251124.e177314a4 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13713
+- fix(core): Fix context window overflow warning for PDF files by @kkitase in
+  https://github.com/google-gemini/gemini-cli/pull/13548
+- feat :rephrasing the extension logging messages to run the explore command
+  when there are no extensions installed by @JayadityaGit in
+  https://github.com/google-gemini/gemini-cli/pull/13740
+- Improve code coverage for cli package by @megha1188 in
+  https://github.com/google-gemini/gemini-cli/pull/13724
+- Add session subtask in /stats command by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13750
+- feat(core): Migrate chatCompressionService to model configs. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/12863
+- feat(hooks): Hook Telemetry Infrastructure by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9082
+- fix: (some minor improvements to configs and getPackageJson return behaviour)
+  by @grMLEqomlkkU5Eeinz4brIrOVCUCkJuN in
+  https://github.com/google-gemini/gemini-cli/pull/12510
+- feat(hooks): Hook Event Handling by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9097
+- feat(hooks): Hook Agent Lifecycle Integration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9105
+- feat(core): Land bool for alternate system prompt. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13764
+- bug(core): Add default chat compression config. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13766
+- feat(model-availability): introduce ModelPolicy and PolicyCatalog by
+  @adamfweidman in https://github.com/google-gemini/gemini-cli/pull/13751
+- feat(hooks): Hook System Orchestration by @Edilmo in
+  https://github.com/google-gemini/gemini-cli/pull/9102
+- feat(config): add isModelAvailabilityServiceEnabled setting by @adamfweidman
+  in https://github.com/google-gemini/gemini-cli/pull/13777
+- chore/release: bump version to 0.19.0-nightly.20251125.f6d97d448 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13782
+- chore: remove console.error by @adamfweidman in
+  https://github.com/google-gemini/gemini-cli/pull/13779
+- fix: Add $schema property to settings.schema.json by @sacrosanctic in
+  https://github.com/google-gemini/gemini-cli/pull/12763
+- fix(cli): allow non-GitHub SCP-styled URLs for extension installation by @m0ps
+  in https://github.com/google-gemini/gemini-cli/pull/13800
+- fix(resume): allow passing a prompt via stdin while resuming using --resume by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13520
+- feat(sessions): add /resume slash command to open the session browser by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13621
+- docs(sessions): add documentation for chat recording and session management by
+  @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13667
+- Fix TypeError: "URL.parse is not a function" for Node.js < v22 by @macarronesc
+  in https://github.com/google-gemini/gemini-cli/pull/13698
+- fallback to flash for TerminalQuota errors by @sehoon38 in
+  https://github.com/google-gemini/gemini-cli/pull/13791
+- Update Code Wiki README badge by @PatoBeltran in
+  https://github.com/google-gemini/gemini-cli/pull/13768
+- Add Databricks auth support and custom header option to gemini cli by
+  @AarushiShah in https://github.com/google-gemini/gemini-cli/pull/11893
+- Update dependency for modelcontextprotocol/sdk to 1.23.0 by @bbiggs in
+  https://github.com/google-gemini/gemini-cli/pull/13827
+
+**Full Changelog**:
+https://github.com/google-gemini/gemini-cli/compare/v0.18.0-preview.4...v0.19.0-preview.0
+
+## Release v0.18.0 - v0.18.4
+
+### Highlights
+
+- **Experimental permission improvements**: We're experimenting with a new
+  policy engine in Gemini CLI, letting users and administrators create
+  fine-grained policies for tool calls. This setting is currently behind a flag.
+  See our [policy engine documentation](../core/policy-engine.md) to learn how
+  to use this feature.
+- **Gemini 3 support rolled out for some users**: Some users can now enable
+  Gemini 3 by using the `/settings` flag and toggling **Preview Features**. See
+  our [Gemini 3 on Gemini CLI documentation](../get-started/gemini-3.md) to find
+  out more about using Gemini 3.
+- **Updated UI rollback:** We've temporarily rolled back a previous UI update,
+  which enabled embedded scrolling and mouse support. This can be re-enabled by
+  using the `/settings` command and setting **Use Alternate Screen Buffer** to
+  `true`.
+- **Display your model in your chat history**: You can now go use `/settings`
+  and turn on **Show Model in Chat** to display the model in your chat history.
+- **Uninstall multiple extensions**: You can uninstall multiple extensions with
+  a single command: `gemini extensions uninstall`.
+
+![Uninstalling Gemini extensions with a single command](https://i.imgur.com/pi7nEBI.png)
+
+### What's changed
+
+- Remove obsolete reference to "help wanted" label in CONTRIBUTING.md by
+  @aswinashok44 in https://github.com/google-gemini/gemini-cli/pull/13291
+- chore(release): v0.18.0-nightly.20251118.86828bb56 by @skeshive in
+  https://github.com/google-gemini/gemini-cli/pull/13309
+- Docs: Access clarification. by @jkcinouye in
+  https://github.com/google-gemini/gemini-cli/pull/13304
+- Fix links in Gemini 3 Pro documentation by @gmackall in
+  https://github.com/google-gemini/gemini-cli/pull/13312
+- Improve keyboard code parsing by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13307
+- fix(core): Ensure `read_many_files` tool is available to zed. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13338
+- Support 3-parameter modifyOtherKeys sequences by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13342
+- Improve pty resize error handling for Windows by @galz10 in
+  https://github.com/google-gemini/gemini-cli/pull/13353
+- fix(ui): Clear input prompt on Escape key press by @SandyTao520 in
+  https://github.com/google-gemini/gemini-cli/pull/13335
+- bug(ui) showLineNumbers had the wrong default value. by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13356
+- fix(cli): fix crash on startup in NO_COLOR mode (#13343) due to ungua… by
+  @avilladsen in https://github.com/google-gemini/gemini-cli/pull/13352
+- fix: allow MCP prompts with spaces in name by @jackwotherspoon in
+  https://github.com/google-gemini/gemini-cli/pull/12910
+- Refactor createTransport to duplicate less code by @davidmcwherter in
+  https://github.com/google-gemini/gemini-cli/pull/13010
+- Followup from #10719 by @bl-ue in
+  https://github.com/google-gemini/gemini-cli/pull/13243
+- Capturing github action workflow name if present and send it to clearcut by
+  @MJjainam in https://github.com/google-gemini/gemini-cli/pull/13132
+- feat(sessions): record interactive-only errors and warnings to chat recording
+  JSON files by @bl-ue in https://github.com/google-gemini/gemini-cli/pull/13300
+- fix(zed-integration): Correctly handle cancellation errors by @benbrandt in
+  https://github.com/google-gemini/gemini-cli/pull/13399
+- docs: Add Code Wiki link to README by @holtskinner in
+  https://github.com/google-gemini/gemini-cli/pull/13289
+- Restore keyboard mode when exiting the editor by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13350
+- feat(core, cli): Bump genai version to 1.30.0 by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13435
+- [cli-ui] Keep header ASCII art colored on non-gradient terminals (#13373) by
+  @bniladridas in https://github.com/google-gemini/gemini-cli/pull/13374
+- Fix Copyright line in LICENSE by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13449
+- Fix typo in write_todos methodology instructions by @Smetalo in
+  https://github.com/google-gemini/gemini-cli/pull/13411
+- feat: update thinking mode support to exclude gemini-2.0 models and simplify
+  logic. by @kevin-ramdass in
+  https://github.com/google-gemini/gemini-cli/pull/13454
+- remove unneeded log by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13456
+- feat: add click-to-focus support for interactive shell by @galz10 in
+  https://github.com/google-gemini/gemini-cli/pull/13341
+- Add User email detail to about box by @ptone in
+  https://github.com/google-gemini/gemini-cli/pull/13459
+- feat(core): Wire up chat code path for model configs. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/12850
+- chore/release: bump version to 0.18.0-nightly.20251120.2231497b1 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13476
+- feat(core): Fix bug with incorrect model overriding. by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13477
+- Use synchronous writes when detecting keyboard modes by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13478
+- fix(cli): prevent race condition when restoring prompt after context overflow
+  by @SandyTao520 in https://github.com/google-gemini/gemini-cli/pull/13473
+- Revert "feat(core): Fix bug with incorrect model overriding." by @adamfweidman
+  in https://github.com/google-gemini/gemini-cli/pull/13483
+- Fix: Update system instruction when GEMINI.md memory is loaded or refreshed by
+  @lifefloating in https://github.com/google-gemini/gemini-cli/pull/12136
+- fix(zed-integration): Ensure that the zed integration is classified as
+  interactive by @benbrandt in
+  https://github.com/google-gemini/gemini-cli/pull/13394
+- Copy commands as part of setup-github by @gsehgal in
+  https://github.com/google-gemini/gemini-cli/pull/13464
+- Update banner design by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13420
+- Protect stdout and stderr so JavaScript code can't accidentally write to
+  stdout corrupting ink rendering by @jacob314 in
+  https://github.com/google-gemini/gemini-cli/pull/13247
+- Enable switching preview features on/off without restart by @Adib234 in
+  https://github.com/google-gemini/gemini-cli/pull/13515
+- feat(core): Use thinking level for Gemini 3 by @joshualitt in
+  https://github.com/google-gemini/gemini-cli/pull/13445
+- Change default compress threshold to 0.5 for api key users by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13517
+- remove duplicated mouse code by @scidomino in
+  https://github.com/google-gemini/gemini-cli/pull/13525
+- feat(zed-integration): Use default model routing for Zed integration by
+  @benbrandt in https://github.com/google-gemini/gemini-cli/pull/13398
+- feat(core): Incorporate Gemini 3 into model config hierarchy. by @joshualitt
+  in https://github.com/google-gemini/gemini-cli/pull/13447
+- fix(patch): cherry-pick 5e218a5 to release/v0.18.0-preview.0-pr-13623 to patch
+  version v0.18.0-preview.0 and create version 0.18.0-preview.1 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13626
+- fix(patch): cherry-pick d351f07 to release/v0.18.0-preview.1-pr-12535 to patch
+  version v0.18.0-preview.1 and create version 0.18.0-preview.2 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13813
+- fix(patch): cherry-pick 3e50be1 to release/v0.18.0-preview.2-pr-13428 to patch
+  version v0.18.0-preview.2 and create version 0.18.0-preview.3 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13821
+- fix(patch): cherry-pick d8a3d08 to release/v0.18.0-preview.3-pr-13791 to patch
+  version v0.18.0-preview.3 and create version 0.18.0-preview.4 by
+  @gemini-cli-robot in https://github.com/google-gemini/gemini-cli/pull/13826
+
+  **Full Changelog**:
+  https://github.com/google-gemini/gemini-cli/compare/v0.17.1...v0.18.0

docs/cli/enterprise.md

@@ -159,6 +159,50 @@ This results in the following merged configuration:
 By using the system settings file, you can enforce the security and
 configuration patterns described below.
 
+### Enforcing system settings with a wrapper script
+
+While the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` environment variable provides
+flexibility, a user could potentially override it to point to a different
+settings file, bypassing the centrally managed configuration. To mitigate this,
+enterprises can deploy a wrapper script or alias that ensures the environment
+variable is always set to the corporate-controlled path.
+
+This approach ensures that no matter how the user calls the `gemini` command,
+the enterprise settings are always loaded with the highest precedence.
+
+**Example wrapper script:**
+
+Administrators can create a script named `gemini` and place it in a directory
+that appears earlier in the user's `PATH` than the actual Gemini CLI binary
+(e.g., `/usr/local/bin/gemini`).
+
+```bash
+#!/bin/bash
+
+# Enforce the path to the corporate system settings file.
+# This ensures that the company's configuration is always applied.
+export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"
+
+# Find the original gemini executable.
+# This is a simple example; a more robust solution might be needed
+# depending on the installation method.
+REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)
+
+if [ -z "$REAL_GEMINI_PATH" ]; then
+  echo "Error: The original 'gemini' executable was not found." >&2
+  exit 1
+fi
+
+# Pass all arguments to the real Gemini CLI executable.
+exec "$REAL_GEMINI_PATH" "$@"
+```
+
+By deploying this script, the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` is set within
+the script's environment, and the `exec` command replaces the script process
+with the actual Gemini CLI process, which inherits the environment variable.
+This makes it significantly more difficult for a user to bypass the enforced
+settings.
+
 ## Restricting tool access
 
 You can significantly enhance security by controlling which tools the Gemini
@@ -434,7 +478,39 @@ prompted to switch to the enforced method. In non-interactive mode, the CLI will
 exit with an error if the configured authentication method does not match the
 enforced one.
 
-## Putting it all together: Example system `settings.json`
+### Restricting logins to corporate domains
+
+For enterprises using Google Workspace, you can enforce that users only
+authenticate with their corporate Google accounts. This is a network-level
+control that is configured on a proxy server, not within Gemini CLI itself. It
+works by intercepting authentication requests to Google and adding a special
+HTTP header.
+
+This policy prevents users from logging in with personal Gmail accounts or other
+non-corporate Google accounts.
+
+For detailed instructions, see the Google Workspace Admin Help article on
+[blocking access to consumer accounts](https://support.google.com/a/answer/1668854?hl=en#zippy=%2Cstep-choose-a-web-proxy-server%2Cstep-configure-the-network-to-block-certain-accounts).
+
+The general steps are as follows:
+
+1.  **Intercept Requests**: Configure your web proxy to intercept all requests
+    to `google.com`.
+2.  **Add HTTP Header**: For each intercepted request, add the
+    `X-GoogApps-Allowed-Domains` HTTP header.
+3.  **Specify Domains**: The value of the header should be a comma-separated
+    list of your approved Google Workspace domain names.
+
+**Example header:**
+
+```
+X-GoogApps-Allowed-Domains: my-corporate-domain.com, secondary-domain.com
+```
+
+When this header is present, Google's authentication service will only allow
+logins from accounts belonging to the specified domains.
+
+## Putting it all together: example system `settings.json`
 
 Here is an example of a system `settings.json` file that combines several of the
 patterns discussed above to create a secure, controlled environment for Gemini

docs/cli/model.md

@@ -1,8 +1,13 @@
 # Gemini CLI model selection (`/model` command)
 
-Select your Gemini CLI model. The `/model` command opens a dialog where you can
-configure the model used by Gemini CLI, giving you more control over your
-results.
+Select your Gemini CLI model. The `/model` command lets you configure the model
+used by Gemini CLI, giving you more control over your results. Use **Pro**
+models for complex tasks and reasoning, **Flash** models for high speed results,
+or the (recommended) **Auto** setting to choose the best model for your tasks.
+
+> **Note:** The `/model` command (and the `--model` flag) does not override the
+> model used by sub-agents. Consequently, even when using the `/model` flag you
+> may see other models used in your model usage reports.
 
 ## How to use the `/model` command
 
@@ -12,26 +17,25 @@ Use the following command in Gemini CLI:
 /model
 ```
 
-Running this command will open a dialog with your model options:
+Running this command will open a dialog with your options:
 
-| Option             | Description                                                   | Models                                                                                     |
-| ------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Auto (recommended) | Let the system choose the best model for your task.           | gemini-3-pro-preview (if enabled), gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite |
-| Pro                | For complex tasks that require deep reasoning and creativity. | gemini-3-pro-preview (if enabled), gemini-2.5-pro                                          |
-| Flash              | For tasks that need a balance of speed and reasoning.         | gemini-2.5-flash                                                                           |
-| Flash-Lite         | For simple tasks that need to be done quickly.                | gemini-2.5-flash-lite                                                                      |
+| Option            | Description                                                    | Models                                                                 |
+| ----------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Auto (Gemini 3)   | Let the system choose the best Gemini 3 model for your task.   | gemini-3-pro-preview (if enabled), gemini-3-flash-preview (if enabled) |
+| Auto (Gemini 2.5) | Let the system choose the best Gemini 2.5 model for your task. | gemini-2.5-pro, gemini-2.5-flash                                       |
+| Manual            | Select a specific model.                                       | Any available model.                                                   |
 
-### Gemini 3 Pro and preview features
+We recommend selecting one of the above **Auto** options. However, you can
+select **Manual** to select a specific model from those available.
 
-Note: Gemini 3 is not currently available on all account types. To learn more
-about Gemini 3 access, refer to
-[Gemini 3 Pro on Gemini CLI](../get-started/gemini-3.md).
+### Gemini 3 and preview features
 
-To enable Gemini 3 Pro (if available), enable
-[**Preview features** by using the `settings` command](../cli/settings.md). Once
-enabled, Gemini CLI will attempt to use Gemini 3 Pro when you select **Auto** or
-**Pro**. Both **Auto** and **Pro** will try to use Gemini 3 Pro before falling
-back to Gemini 2.5 Pro.
+> **Note:** Gemini 3 is not currently available on all account types. To learn
+> more about Gemini 3 access, refer to
+> [Gemini 3 on Gemini CLI](../get-started/gemini-3.md).
+
+To enable Gemini 3 Pro and Gemini 3 Flash (if available), enable
+[**Preview Features** by using the `settings` command](../cli/settings.md).
 
 You can also use the `--model` flag to specify a particular Gemini model on
 startup. For more details, refer to the
@@ -42,16 +46,16 @@ Gemini CLI.
 
 ## Best practices for model selection
 
-- **Default to Auto (recommended).** For most users, the _Auto (recommended)_
-  model provides a balance between speed and performance, automatically
-  selecting the correct model based on the complexity of the task. Example:
-  Developing a web application could include a mix of complex tasks (building
-  architecture and scaffolding the project) and simple tasks (generating CSS).
+- **Default to Auto.** For most users, the _Auto_ option model provides a
+  balance between speed and performance, automatically selecting the correct
+  model based on the complexity of the task. Example: Developing a web
+  application could include a mix of complex tasks (building architecture and
+  scaffolding the project) and simple tasks (generating CSS).
 
 - **Switch to Pro if you aren't getting the results you want.** If you think you
-  need your model to be a little "smarter," use Pro. Pro will provide you with
-  the highest levels of reasoning and creativity. Example: A complex or
-  multi-stage debugging task.
+  need your model to be a little "smarter," you can manually select Pro. Pro
+  will provide you with the highest levels of reasoning and creativity. Example:
+  A complex or multi-stage debugging task.
 
 - **Switch to Flash or Flash-Lite if you need faster results.** If you need a
   simple response quickly, Flash or Flash-Lite is the best option. Example:

docs/cli/settings.md

@@ -94,7 +94,7 @@ they appear in the UI.
 | Enable Tool Output Truncation    | `tools.enableToolOutputTruncation`   | Enable truncation of large tool outputs.                                                                        | `true`  |
 | Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold`  | Truncate tool output if it is larger than this many characters. Set to -1 to disable.                           | `10000` |
 | Tool Output Truncation Lines     | `tools.truncateToolOutputLines`      | The number of lines to keep when truncating tool output.                                                        | `100`   |
-| Enable Message Bus Integration   | `tools.enableMessageBusIntegration`  | Enable policy-based tool confirmation via message bus integration.                                              | `false` |
+| Enable Message Bus Integration   | `tools.enableMessageBusIntegration`  | Enable policy-based tool confirmation via message bus integration.                                              | `true`  |
 
 ### Security
 

docs/cli/telemetry.md

@@ -74,15 +74,16 @@ observability framework — Gemini CLI's observability system provides:
 All telemetry behavior is controlled through your `.gemini/settings.json` file.
 Environment variables can be used to override the settings in the file.
 
-| Setting        | Environment Variable             | Description                                       | Values            | Default                 |
-| -------------- | -------------------------------- | ------------------------------------------------- | ----------------- | ----------------------- |
-| `enabled`      | `GEMINI_TELEMETRY_ENABLED`       | Enable or disable telemetry                       | `true`/`false`    | `false`                 |
-| `target`       | `GEMINI_TELEMETRY_TARGET`        | Where to send telemetry data                      | `"gcp"`/`"local"` | `"local"`               |
-| `otlpEndpoint` | `GEMINI_TELEMETRY_OTLP_ENDPOINT` | OTLP collector endpoint                           | URL string        | `http://localhost:4317` |
-| `otlpProtocol` | `GEMINI_TELEMETRY_OTLP_PROTOCOL` | OTLP transport protocol                           | `"grpc"`/`"http"` | `"grpc"`                |
-| `outfile`      | `GEMINI_TELEMETRY_OUTFILE`       | Save telemetry to file (overrides `otlpEndpoint`) | file path         | -                       |
-| `logPrompts`   | `GEMINI_TELEMETRY_LOG_PROMPTS`   | Include prompts in telemetry logs                 | `true`/`false`    | `true`                  |
-| `useCollector` | `GEMINI_TELEMETRY_USE_COLLECTOR` | Use external OTLP collector (advanced)            | `true`/`false`    | `false`                 |
+| Setting        | Environment Variable             | Description                                         | Values            | Default                 |
+| -------------- | -------------------------------- | --------------------------------------------------- | ----------------- | ----------------------- |
+| `enabled`      | `GEMINI_TELEMETRY_ENABLED`       | Enable or disable telemetry                         | `true`/`false`    | `false`                 |
+| `target`       | `GEMINI_TELEMETRY_TARGET`        | Where to send telemetry data                        | `"gcp"`/`"local"` | `"local"`               |
+| `otlpEndpoint` | `GEMINI_TELEMETRY_OTLP_ENDPOINT` | OTLP collector endpoint                             | URL string        | `http://localhost:4317` |
+| `otlpProtocol` | `GEMINI_TELEMETRY_OTLP_PROTOCOL` | OTLP transport protocol                             | `"grpc"`/`"http"` | `"grpc"`                |
+| `outfile`      | `GEMINI_TELEMETRY_OUTFILE`       | Save telemetry to file (overrides `otlpEndpoint`)   | file path         | -                       |
+| `logPrompts`   | `GEMINI_TELEMETRY_LOG_PROMPTS`   | Include prompts in telemetry logs                   | `true`/`false`    | `true`                  |
+| `useCollector` | `GEMINI_TELEMETRY_USE_COLLECTOR` | Use external OTLP collector (advanced)              | `true`/`false`    | `false`                 |
+| `useCliAuth`   | `GEMINI_TELEMETRY_USE_CLI_AUTH`  | Use CLI credentials for telemetry (GCP target only) | `true`/`false`    | `false`                 |
 
 **Note on boolean environment variables:** For the boolean settings (`enabled`,
 `logPrompts`, `useCollector`), setting the corresponding environment variable to
@@ -130,6 +131,34 @@ Before using either method below, complete these steps:
      --project="$OTLP_GOOGLE_CLOUD_PROJECT"
    ```
 
+### Authenticating with CLI Credentials
+
+By default, the telemetry collector for Google Cloud uses Application Default
+Credentials (ADC). However, you can configure it to use the same OAuth
+credentials that you use to log in to the Gemini CLI. This is useful in
+environments where you don't have ADC set up.
+
+To enable this, set the `useCliAuth` property in your `telemetry` settings to
+`true`:
+
+```json
+{
+  "telemetry": {
+    "enabled": true,
+    "target": "gcp",
+    "useCliAuth": true
+  }
+}
+```
+
+**Important:**
+
+- This setting requires the use of **Direct Export** (in-process exporters).
+- It **cannot** be used with `useCollector: true`. If you enable both, telemetry
+  will be disabled and an error will be logged.
+- The CLI will automatically use your credentials to authenticate with Google
+  Cloud Trace, Metrics, and Logging APIs.
+
 ### Direct export (recommended)
 
 Sends telemetry directly to Google Cloud services. No collector needed.

docs/core/policy-engine.md

@@ -1,13 +1,32 @@
 # Policy engine
 
-:::note This feature is currently in testing. To enable it, set
-`tools.enableMessageBusIntegration` to `true` in your `settings.json` file. :::
-
 The Gemini CLI includes a powerful policy engine that provides fine-grained
 control over tool execution. It allows users and administrators to define rules
 that determine whether a tool call should be allowed, denied, or require user
 confirmation.
 
+## Quick start
+
+To create your first policy:
+
+1.  **Create the policy directory** if it doesn't exist:
+    ```bash
+    mkdir -p ~/.gemini/policies
+    ```
+2.  **Create a new policy file** (e.g., `~/.gemini/policies/my-rules.toml`). You
+    can use any filename ending in `.toml`; all such files in this directory
+    will be loaded and combined:
+    ```toml
+    [[rule]]
+    toolName = "run_shell_command"
+    commandPrefix = "git status"
+    decision = "allow"
+    priority = 100
+    ```
+3.  **Run a command** that triggers the policy (e.g., ask Gemini CLI to
+    `git status`). The tool will now execute automatically without prompting for
+    confirmation.
+
 ## Core concepts
 
 The policy engine operates on a set of rules. Each rule is a combination of
@@ -239,6 +258,8 @@ The Gemini CLI ships with a set of default policies to provide a safe
 out-of-the-box experience.
 
 - **Read-only tools** (like `read_file`, `glob`) are generally **allowed**.
+- **Agent delegation** (like `delegate_to_agent`) is **allowed** (sub-agent
+  actions are checked individually).
 - **Write tools** (like `write_file`, `run_shell_command`) default to
   **`ask_user`**.
 - In **`yolo`** mode, a high-priority rule allows all tools.

docs/extensions/index.md

@@ -163,11 +163,11 @@ The file has the following structure:
   your extension in the CLI. Note that we expect this name to match the
   extension directory name.
 - `version`: The version of the extension.
-- `mcpServers`: A map of MCP servers to configure. The key is the name of the
+- `mcpServers`: A map of MCP servers to settings. The key is the name of the
   server, and the value is the server configuration. These servers will be
-  loaded on startup just like MCP servers configured in a
+  loaded on startup just like MCP servers settingsd in a
   [`settings.json` file](../get-started/configuration.md). If both an extension
-  and a `settings.json` file configure an MCP server with the same name, the
+  and a `settings.json` file settings an MCP server with the same name, the
   server defined in the `settings.json` file takes precedence.
   - Note that all MCP server configuration options are supported except for
     `trust`.
@@ -223,6 +223,21 @@ When a user installs this extension, they will be prompted to enter their API
 key. The value will be saved to a `.env` file in the extension's directory
 (e.g., `<home>/.gemini/extensions/my-api-extension/.env`).
 
+You can view a list of an extension's settings by running:
+
+```
+gemini extensions settings list <extension name>
+```
+
+and you can update a given setting using:
+
+```
+gemini extensions settings set <extension name> <setting name> [--scope <scope>]
+```
+
+- `--scope`: The scope to set the setting in (`user` or `workspace`). This is
+  optional and will default to `user`.
+
 ### Custom commands
 
 Extensions can provide [custom commands](../cli/custom-commands.md) by placing

docs/get-started/configuration.md

@@ -367,6 +367,12 @@ their corresponding top-level category object in your `settings.json` file.
           "model": "gemini-3-pro-preview"
         }
       },
+      "gemini-3-flash-preview": {
+        "extends": "chat-base-3",
+        "modelConfig": {
+          "model": "gemini-3-flash-preview"
+        }
+      },
       "gemini-2.5-pro": {
         "extends": "chat-base-2.5",
         "modelConfig": {
@@ -496,6 +502,11 @@ their corresponding top-level category object in your `settings.json` file.
           "model": "gemini-3-pro-preview"
         }
       },
+      "chat-compression-3-flash": {
+        "modelConfig": {
+          "model": "gemini-3-flash-preview"
+        }
+      },
       "chat-compression-2.5-pro": {
         "modelConfig": {
           "model": "gemini-2.5-pro"
@@ -524,6 +535,11 @@ their corresponding top-level category object in your `settings.json` file.
     with (and override) the built-in aliases.
   - **Default:** `{}`
 
+- **`modelConfigs.customOverrides`** (array):
+  - **Description:** Custom model config overrides. These are merged with (and
+    added to) the built-in overrides.
+  - **Default:** `[]`
+
 - **`modelConfigs.overrides`** (array):
   - **Description:** Apply specific configuration overrides based on matches,
     with a primary key of model (or alias). The most specific match will be
@@ -668,7 +684,7 @@ their corresponding top-level category object in your `settings.json` file.
     integration. When enabled, tools automatically respect policy engine
     decisions (ALLOW/DENY/ASK_USER) without requiring individual tool
     implementations.
-  - **Default:** `false`
+  - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`tools.enableHooks`** (boolean):
@@ -767,6 +783,11 @@ their corresponding top-level category object in your `settings.json` file.
 
 #### `experimental`
 
+- **`experimental.enableAgents`** (boolean):
+  - **Description:** Enable local and remote subagents.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 - **`experimental.extensionManagement`** (boolean):
   - **Description:** Enable extension management features.
   - **Default:** `true`
@@ -811,15 +832,70 @@ their corresponding top-level category object in your `settings.json` file.
 
 - **`experimental.codebaseInvestigatorSettings.model`** (string):
   - **Description:** The model to use for the Codebase Investigator agent.
-  - **Default:** `"gemini-2.5-pro"`
+  - **Default:** `"auto"`
   - **Requires restart:** Yes
 
 #### `hooks`
 
-- **`hooks`** (object):
-  - **Description:** Hook configurations for intercepting and customizing agent
-    behavior.
-  - **Default:** `{}`
+- **`hooks.disabled`** (array):
+  - **Description:** List of hook names (commands) that should be disabled.
+    Hooks in this list will not execute even if configured.
+  - **Default:** `[]`
+
+- **`hooks.BeforeTool`** (array):
+  - **Description:** Hooks that execute before tool execution. Can intercept,
+    validate, or modify tool calls.
+  - **Default:** `[]`
+
+- **`hooks.AfterTool`** (array):
+  - **Description:** Hooks that execute after tool execution. Can process
+    results, log outputs, or trigger follow-up actions.
+  - **Default:** `[]`
+
+- **`hooks.BeforeAgent`** (array):
+  - **Description:** Hooks that execute before agent loop starts. Can set up
+    context or initialize resources.
+  - **Default:** `[]`
+
+- **`hooks.AfterAgent`** (array):
+  - **Description:** Hooks that execute after agent loop completes. Can perform
+    cleanup or summarize results.
+  - **Default:** `[]`
+
+- **`hooks.Notification`** (array):
+  - **Description:** Hooks that execute on notification events (errors,
+    warnings, info). Can log or alert on specific conditions.
+  - **Default:** `[]`
+
+- **`hooks.SessionStart`** (array):
+  - **Description:** Hooks that execute when a session starts. Can initialize
+    session-specific resources or state.
+  - **Default:** `[]`
+
+- **`hooks.SessionEnd`** (array):
+  - **Description:** Hooks that execute when a session ends. Can perform cleanup
+    or persist session data.
+  - **Default:** `[]`
+
+- **`hooks.PreCompress`** (array):
+  - **Description:** Hooks that execute before chat history compression. Can
+    back up or analyze conversation before compression.
+  - **Default:** `[]`
+
+- **`hooks.BeforeModel`** (array):
+  - **Description:** Hooks that execute before LLM requests. Can modify prompts,
+    inject context, or control model parameters.
+  - **Default:** `[]`
+
+- **`hooks.AfterModel`** (array):
+  - **Description:** Hooks that execute after LLM responses. Can process
+    outputs, extract information, or log interactions.
+  - **Default:** `[]`
+
+- **`hooks.BeforeToolSelection`** (array):
+  - **Description:** Hooks that execute before tool selection. Can filter or
+    prioritize available tools dynamically.
+  - **Default:** `[]`
   <!-- SETTINGS-AUTOGEN:END -->
 
 #### `mcpServers`

docs/get-started/gemini-3.md

@@ -1,64 +1,37 @@
-# Gemini 3 Pro on Gemini CLI (join the waitlist)
+# Gemini 3 Pro and Gemini 3 Flash on Gemini CLI
 
-We’re excited to bring Gemini 3 Pro to Gemini CLI. For Google AI Ultra users
-(Google AI Ultra for Business is not currently supported) and paid Gemini and
-Vertex API key holders, Gemini 3 Pro is already available and ready to enable.
-For everyone else, we're gradually expanding access
-[through a waitlist](https://goo.gle/geminicli-waitlist-signup). Sign up for the
-waitlist now to access Gemini 3 Pro once approved.
+Gemini 3 Pro and Gemini 3 Flash are now available on Gemini CLI! Currently, most
+paid customers of Gemini CLI will have access to both Gemini 3 Pro and Gemini 3
+Flash, including the following subscribers:
 
-**Note:** Please wait until you have been approved to use Gemini 3 Pro to enable
-**preview features**. If enabled early, the CLI will fallback to Gemini 2.5 Pro.
+- Google AI Pro and Google AI Ultra (excluding business customers).
+- Gemini Code Assist Standard and Enterprise (requires
+  [administrative enablement](#administrator-instructions)).
+- Paid Gemini API and Vertex API key holders.
 
-## Do I need to join the waitlist?
+For free tier users:
 
-The following users will be **automatically granted access** to Gemini 3 Pro on
-Gemini CLI:
+- If you signed up for the waitlist, please check your email for details. We’ve
+  onboarded everyone who signed up to the previously available waitlist.
+- If you were not on our waitlist, we’re rolling out additional access gradually
+  to ensure the experience remains fast and reliable. Stay tuned for more
+  details.
 
-- Google AI Ultra subscribers (excluding Google AI Ultra for Business, which is
-  on the roadmap).
-- Gemini API key users
-  [with access to Gemini 3](https://ai.google.dev/gemini-api/docs/rate-limits).
-- Vertex API key users
-  [with access to Gemini 3](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/quotas).
+## How to get started with Gemini 3 on Gemini CLI
 
-For **Gemini Code Assist Enterprise users**, access is coming soon.
+Get started by upgrading Gemini CLI to the latest version (0.21.1):
 
-Users not automatically granted access through one of these account types will
-need to join the waitlist. This includes Google AI Pro, Gemini Code Assist
-standard, and free tier users.
+```bash
+npm install -g @google/gemini-cli@latest
+```
 
-Note: Whether you’re automatically granted access or accepted from the waitlist,
-you’ll still need to enable Gemini 3 Pro
-[using the `/settings` command](../cli/settings.md).
+After you’ve confirmed your version is 0.21.1 or later:
 
-## How to join the waitlist
+1. Use the `/settings` command in Gemini CLI.
+2. Toggle **Preview Features** to `true`.
+3. Run `/model` and select **Auto (Gemini 3)**.
 
-Users not automatically granted access will need to join the waitlist. Follow
-these instructions to sign up:
-
-- Install Gemini CLI.
-- Authenticate using the **Login with Google** option. You’ll see a banner that
-  says “Gemini 3 is now available.” If you do not see this banner, update your
-  installation of Gemini CLI to the most recent version.
-- Fill out this Google form:
-  [Access Gemini 3 in Gemini CLI](https://goo.gle/geminicli-waitlist-signup).
-  Provide the email address of the account you used to authenticate with Gemini
-  CLI.
-
-Users will be onboarded in batches, subject to availability. When you’ve been
-granted access to Gemini 3 Pro, you’ll receive an acceptance email to your
-submitted email address.
-
-## How to use Gemini 3 Pro with Gemini CLI
-
-Once you receive your acceptance email–or if you are automatically granted
-access–you still need to enable Gemini 3 Pro within Gemini CLI.
-
-To enable Gemini 3 Pro, use the `/settings` command in Gemini CLI and set
-**Preview Features** to `true`.
-
-For more information, see [Gemini CLI Settings](../cli/settings.md).
+For more information, see [Gemini CLI model selection](../cli/model.md).
 
 ### Usage limits and fallback
 
@@ -76,12 +49,12 @@ There may be times when the Gemini 3 Pro model is overloaded. When that happens,
 Gemini CLI will ask you to decide whether you want to keep trying Gemini 3 Pro
 or fallback to Gemini 2.5 Pro.
 
-**Note:** The **Keep trying** option uses exponential backoff, in which Gemini
-CLI waits longer between each retry, when the system is busy. If the retry
-doesn't happen immediately, please wait a few minutes for the request to
-process.
+> **Note:** The **Keep trying** option uses exponential backoff, in which Gemini
+> CLI waits longer between each retry, when the system is busy. If the retry
+> doesn't happen immediately, please wait a few minutes for the request to
+> process.
 
-## Model selection and routing types
+### Model selection and routing types
 
 When using Gemini CLI, you may want to control how your requests are routed
 between models. By default, Gemini CLI uses **Auto** routing.
@@ -100,6 +73,39 @@ manage your usage limits:
 To learn more about selecting a model and routing, refer to
 [Gemini CLI Model Selection](../cli/model.md).
 
+## How to enable Gemini 3 with Gemini CLI on Gemini Code Assist
+
+If you're using Gemini Code Assist Standard or Gemini Code Assist Enterprise,
+enabling Gemini 3 Pro on Gemini CLI requires configuring your release channels.
+Using Gemini 3 Pro will require two steps: administrative enablement and user
+enablement.
+
+To learn more about these settings, refer to
+[Configure Gemini Code Assist release channels](https://developers.google.com/gemini-code-assist/docs/configure-release-channels).
+
+### Administrator instructions
+
+An administrator with **Google Cloud Settings Admin** permissions must follow
+these directions:
+
+- Navigate to the Google Cloud Project you're using with Gemini CLI for Code
+  Assist.
+- Go to **Admin for Gemini** > **Settings**.
+- Under **Release channels for Gemini Code Assist in local IDEs** select
+  **Preview**.
+- Click **Save changes**.
+
+### User instructions
+
+Wait for two to three minutes after your administrator has enabled **Preview**,
+then:
+
+- Open Gemini CLI.
+- Use the `/settings` command.
+- Set **Preview Features** to `true`.
+
+Restart Gemini CLI and you should have access to Gemini 3.
+
 ## Need help?
 
 If you need help, we recommend searching for an existing

docs/hooks/best-practices.md

@@ -0,0 +1,806 @@
+# Hooks on Gemini CLI: Best practices
+
+This guide covers security considerations, performance optimization, debugging
+techniques, and privacy considerations for developing and deploying hooks in
+Gemini CLI.
+
+## Security considerations
+
+### Validate all inputs
+
+Never trust data from hooks without validation. Hook inputs may contain
+user-provided data that could be malicious:
+
+```bash
+#!/usr/bin/env bash
+input=$(cat)
+
+# Validate JSON structure
+if ! echo "$input" | jq empty 2>/dev/null; then
+  echo "Invalid JSON input" >&2
+  exit 1
+fi
+
+# Validate required fields
+tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+if [ -z "$tool_name" ]; then
+  echo "Missing tool_name field" >&2
+  exit 1
+fi
+```
+
+### Use timeouts
+
+Set reasonable timeouts to prevent hooks from hanging indefinitely:
+
+```json
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "slow-validator",
+            "type": "command",
+            "command": "./hooks/validate.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Recommended timeouts:**
+
+- Fast validation: 1000-5000ms
+- Network requests: 10000-30000ms
+- Heavy computation: 30000-60000ms
+
+### Limit permissions
+
+Run hooks with minimal required permissions:
+
+```bash
+#!/usr/bin/env bash
+# Don't run as root
+if [ "$EUID" -eq 0 ]; then
+  echo "Hook should not run as root" >&2
+  exit 1
+fi
+
+# Check file permissions before writing
+if [ -w "$file_path" ]; then
+  # Safe to write
+else
+  echo "Insufficient permissions" >&2
+  exit 1
+fi
+```
+
+### Scan for secrets
+
+Use `BeforeTool` hooks to prevent committing sensitive data:
+
+```javascript
+const SECRET_PATTERNS = [
+  /api[_-]?key\s*[:=]\s*['"]?[a-zA-Z0-9_-]{20,}['"]?/i,
+  /password\s*[:=]\s*['"]?[^\s'"]{8,}['"]?/i,
+  /secret\s*[:=]\s*['"]?[a-zA-Z0-9_-]{20,}['"]?/i,
+  /AKIA[0-9A-Z]{16}/, // AWS access key
+  /ghp_[a-zA-Z0-9]{36}/, // GitHub personal access token
+  /sk-[a-zA-Z0-9]{48}/, // OpenAI API key
+];
+
+function containsSecret(content) {
+  return SECRET_PATTERNS.some((pattern) => pattern.test(content));
+}
+```
+
+### Review external scripts
+
+Always review hook scripts from untrusted sources before enabling them:
+
+```bash
+# Review before installing
+cat third-party-hook.sh | less
+
+# Check for suspicious patterns
+grep -E 'curl|wget|ssh|eval' third-party-hook.sh
+
+# Verify hook source
+ls -la third-party-hook.sh
+```
+
+### Sandbox untrusted hooks
+
+For maximum security, consider running untrusted hooks in isolated environments:
+
+```bash
+# Run hook in Docker container
+docker run --rm \
+  -v "$GEMINI_PROJECT_DIR:/workspace:ro" \
+  -i untrusted-hook-image \
+  /hook-script.sh < input.json
+```
+
+## Performance
+
+### Keep hooks fast
+
+Hooks run synchronously—slow hooks delay the agent loop. Optimize for speed by
+using parallel operations:
+
+```javascript
+// Sequential operations are slower
+const data1 = await fetch(url1).then((r) => r.json());
+const data2 = await fetch(url2).then((r) => r.json());
+const data3 = await fetch(url3).then((r) => r.json());
+
+// Prefer parallel operations for better performance
+const [data1, data2, data3] = await Promise.all([
+  fetch(url1).then((r) => r.json()),
+  fetch(url2).then((r) => r.json()),
+  fetch(url3).then((r) => r.json()),
+]);
+```
+
+### Cache expensive operations
+
+Store results between invocations to avoid repeated computation:
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const CACHE_FILE = '.gemini/hook-cache.json';
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeCache(data) {
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+}
+
+async function main() {
+  const cache = readCache();
+  const cacheKey = `tool-list-${(Date.now() / 3600000) | 0}`; // Hourly cache
+
+  if (cache[cacheKey]) {
+    console.log(JSON.stringify(cache[cacheKey]));
+    return;
+  }
+
+  // Expensive operation
+  const result = await computeExpensiveResult();
+  cache[cacheKey] = result;
+  writeCache(cache);
+
+  console.log(JSON.stringify(result));
+}
+```
+
+### Use appropriate events
+
+Choose hook events that match your use case to avoid unnecessary execution.
+`AfterAgent` fires once per agent loop completion, while `AfterModel` fires
+after every LLM call (potentially multiple times per loop):
+
+```json
+// If checking final completion, use AfterAgent instead of AfterModel
+{
+  "hooks": {
+    "AfterAgent": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "final-checker",
+            "command": "./check-completion.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Filter with matchers
+
+Use specific matchers to avoid unnecessary hook execution. Instead of matching
+all tools with `*`, specify only the tools you need:
+
+```json
+{
+  "matcher": "WriteFile|Edit",
+  "hooks": [
+    {
+      "name": "validate-writes",
+      "command": "./validate.sh"
+    }
+  ]
+}
+```
+
+### Optimize JSON parsing
+
+For large inputs, use streaming JSON parsers to avoid loading everything into
+memory:
+
+```javascript
+// Standard approach: parse entire input
+const input = JSON.parse(await readStdin());
+const content = input.tool_input.content;
+
+// For very large inputs: stream and extract only needed fields
+const { createReadStream } = require('fs');
+const JSONStream = require('JSONStream');
+
+const stream = createReadStream(0).pipe(JSONStream.parse('tool_input.content'));
+let content = '';
+stream.on('data', (chunk) => {
+  content += chunk;
+});
+```
+
+## Debugging
+
+### Log to files
+
+Write debug information to dedicated log files:
+
+```bash
+#!/usr/bin/env bash
+LOG_FILE=".gemini/hooks/debug.log"
+
+# Log with timestamp
+log() {
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"
+}
+
+input=$(cat)
+log "Received input: ${input:0:100}..."
+
+# Hook logic here
+
+log "Hook completed successfully"
+```
+
+### Use stderr for errors
+
+Error messages on stderr are surfaced appropriately based on exit codes:
+
+```javascript
+try {
+  const result = dangerousOperation();
+  console.log(JSON.stringify({ result }));
+} catch (error) {
+  console.error(`Hook error: ${error.message}`);
+  process.exit(2); // Blocking error
+}
+```
+
+### Test hooks independently
+
+Run hook scripts manually with sample JSON input:
+
+```bash
+# Create test input
+cat > test-input.json << 'EOF'
+{
+  "session_id": "test-123",
+  "cwd": "/tmp/test",
+  "hook_event_name": "BeforeTool",
+  "tool_name": "WriteFile",
+  "tool_input": {
+    "file_path": "test.txt",
+    "content": "Test content"
+  }
+}
+EOF
+
+# Test the hook
+cat test-input.json | .gemini/hooks/my-hook.sh
+
+# Check exit code
+echo "Exit code: $?"
+```
+
+### Check exit codes
+
+Ensure your script returns the correct exit code:
+
+```bash
+#!/usr/bin/env bash
+set -e  # Exit on error
+
+# Hook logic
+process_input() {
+  # ...
+}
+
+if process_input; then
+  echo "Success message"
+  exit 0
+else
+  echo "Error message" >&2
+  exit 2
+fi
+```
+
+### Enable telemetry
+
+Hook execution is logged when `telemetry.logPrompts` is enabled:
+
+```json
+{
+  "telemetry": {
+    "logPrompts": true
+  }
+}
+```
+
+View hook telemetry in logs to debug execution issues.
+
+### Use hook panel
+
+The `/hooks panel` command shows execution status and recent output:
+
+```bash
+/hooks panel
+```
+
+Check for:
+
+- Hook execution counts
+- Recent successes/failures
+- Error messages
+- Execution timing
+
+## Development
+
+### Start simple
+
+Begin with basic logging hooks before implementing complex logic:
+
+```bash
+#!/usr/bin/env bash
+# Simple logging hook to understand input structure
+input=$(cat)
+echo "$input" >> .gemini/hook-inputs.log
+echo "Logged input"
+```
+
+### Use JSON libraries
+
+Parse JSON with proper libraries instead of text processing:
+
+**Bad:**
+
+```bash
+# Fragile text parsing
+tool_name=$(echo "$input" | grep -oP '"tool_name":\s*"\K[^"]+')
+```
+
+**Good:**
+
+```bash
+# Robust JSON parsing
+tool_name=$(echo "$input" | jq -r '.tool_name')
+```
+
+### Make scripts executable
+
+Always make hook scripts executable:
+
+```bash
+chmod +x .gemini/hooks/*.sh
+chmod +x .gemini/hooks/*.js
+```
+
+### Version control
+
+Commit hooks to share with your team:
+
+```bash
+git add .gemini/hooks/
+git add .gemini/settings.json
+git commit -m "Add project hooks for security and testing"
+```
+
+**`.gitignore` considerations:**
+
+```gitignore
+# Ignore hook cache and logs
+.gemini/hook-cache.json
+.gemini/hook-debug.log
+.gemini/memory/session-*.jsonl
+
+# Keep hook scripts
+!.gemini/hooks/*.sh
+!.gemini/hooks/*.js
+```
+
+### Document behavior
+
+Add descriptions to help others understand your hooks:
+
+```json
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "WriteFile|Edit",
+        "hooks": [
+          {
+            "name": "secret-scanner",
+            "type": "command",
+            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh",
+            "description": "Scans code changes for API keys, passwords, and other secrets before writing"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Add comments in hook scripts:
+
+```javascript
+#!/usr/bin/env node
+/**
+ * RAG Tool Filter Hook
+ *
+ * This hook reduces the tool space from 100+ tools to ~15 relevant ones
+ * by extracting keywords from the user's request and filtering tools
+ * based on semantic similarity.
+ *
+ * Performance: ~500ms average, cached tool embeddings
+ * Dependencies: @google/generative-ai
+ */
+```
+
+## Troubleshooting
+
+### Hook not executing
+
+**Check hook name in `/hooks panel`:**
+
+```bash
+/hooks panel
+```
+
+Verify the hook appears in the list and is enabled.
+
+**Verify matcher pattern:**
+
+```bash
+# Test regex pattern
+echo "WriteFile" | grep -E "Write.*|Edit"
+```
+
+**Check disabled list:**
+
+```json
+{
+  "hooks": {
+    "disabled": ["my-hook-name"]
+  }
+}
+```
+
+**Ensure script is executable:**
+
+```bash
+ls -la .gemini/hooks/my-hook.sh
+chmod +x .gemini/hooks/my-hook.sh
+```
+
+**Verify script path:**
+
+```bash
+# Check path expansion
+echo "$GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh"
+
+# Verify file exists
+test -f "$GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh" && echo "File exists"
+```
+
+### Hook timing out
+
+**Check configured timeout:**
+
+```json
+{
+  "name": "slow-hook",
+  "timeout": 60000
+}
+```
+
+**Optimize slow operations:**
+
+```javascript
+// Before: Sequential operations (slow)
+for (const item of items) {
+  await processItem(item);
+}
+
+// After: Parallel operations (fast)
+await Promise.all(items.map((item) => processItem(item)));
+```
+
+**Use caching:**
+
+```javascript
+const cache = new Map();
+
+async function getCachedData(key) {
+  if (cache.has(key)) {
+    return cache.get(key);
+  }
+  const data = await fetchData(key);
+  cache.set(key, data);
+  return data;
+}
+```
+
+**Consider splitting into multiple faster hooks:**
+
+```json
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "WriteFile",
+        "hooks": [
+          {
+            "name": "quick-check",
+            "command": "./quick-validation.sh",
+            "timeout": 1000
+          }
+        ]
+      },
+      {
+        "matcher": "WriteFile",
+        "hooks": [
+          {
+            "name": "deep-check",
+            "command": "./deep-analysis.sh",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Invalid JSON output
+
+**Validate JSON before outputting:**
+
+```bash
+#!/usr/bin/env bash
+output='{"decision": "allow"}'
+
+# Validate JSON
+if echo "$output" | jq empty 2>/dev/null; then
+  echo "$output"
+else
+  echo "Invalid JSON generated" >&2
+  exit 1
+fi
+```
+
+**Ensure proper quoting and escaping:**
+
+```javascript
+// Bad: Unescaped string interpolation
+const message = `User said: ${userInput}`;
+console.log(JSON.stringify({ message }));
+
+// Good: Automatic escaping
+console.log(JSON.stringify({ message: `User said: ${userInput}` }));
+```
+
+**Check for binary data or control characters:**
+
+```javascript
+function sanitizeForJSON(str) {
+  return str.replace(/[\x00-\x1F\x7F-\x9F]/g, ''); // Remove control chars
+}
+
+const cleanContent = sanitizeForJSON(content);
+console.log(JSON.stringify({ content: cleanContent }));
+```
+
+### Exit code issues
+
+**Verify script returns correct codes:**
+
+```bash
+#!/usr/bin/env bash
+set -e  # Exit on error
+
+# Processing logic
+if validate_input; then
+  echo "Success"
+  exit 0
+else
+  echo "Validation failed" >&2
+  exit 2
+fi
+```
+
+**Check for unintended errors:**
+
+```bash
+#!/usr/bin/env bash
+# Don't use 'set -e' if you want to handle errors explicitly
+# set -e
+
+if ! command_that_might_fail; then
+  # Handle error
+  echo "Command failed but continuing" >&2
+fi
+
+# Always exit explicitly
+exit 0
+```
+
+**Use trap for cleanup:**
+
+```bash
+#!/usr/bin/env bash
+
+cleanup() {
+  # Cleanup logic
+  rm -f /tmp/hook-temp-*
+}
+
+trap cleanup EXIT
+
+# Hook logic here
+```
+
+### Environment variables not available
+
+**Check if variable is set:**
+
+```bash
+#!/usr/bin/env bash
+
+if [ -z "$GEMINI_PROJECT_DIR" ]; then
+  echo "GEMINI_PROJECT_DIR not set" >&2
+  exit 1
+fi
+
+if [ -z "$CUSTOM_VAR" ]; then
+  echo "Warning: CUSTOM_VAR not set, using default" >&2
+  CUSTOM_VAR="default-value"
+fi
+```
+
+**Debug available variables:**
+
+```bash
+#!/usr/bin/env bash
+
+# List all environment variables
+env > .gemini/hook-env.log
+
+# Check specific variables
+echo "GEMINI_PROJECT_DIR: $GEMINI_PROJECT_DIR" >> .gemini/hook-env.log
+echo "GEMINI_SESSION_ID: $GEMINI_SESSION_ID" >> .gemini/hook-env.log
+echo "GEMINI_API_KEY: ${GEMINI_API_KEY:+<set>}" >> .gemini/hook-env.log
+```
+
+**Use .env files:**
+
+```bash
+#!/usr/bin/env bash
+
+# Load .env file if it exists
+if [ -f "$GEMINI_PROJECT_DIR/.env" ]; then
+  source "$GEMINI_PROJECT_DIR/.env"
+fi
+```
+
+## Privacy considerations
+
+Hook inputs and outputs may contain sensitive information. Gemini CLI respects
+the `telemetry.logPrompts` setting for hook data logging.
+
+### What data is collected
+
+Hook telemetry may include:
+
+- **Hook inputs:** User prompts, tool arguments, file contents
+- **Hook outputs:** Hook responses, decision reasons, added context
+- **Standard streams:** stdout and stderr from hook processes
+- **Execution metadata:** Hook name, event type, duration, success/failure
+
+### Privacy settings
+
+**Enabled (default):**
+
+Full hook I/O is logged to telemetry. Use this when:
+
+- Developing and debugging hooks
+- Telemetry is redirected to a trusted enterprise system
+- You understand and accept the privacy implications
+
+**Disabled:**
+
+Only metadata is logged (event name, duration, success/failure). Hook inputs and
+outputs are excluded. Use this when:
+
+- Sending telemetry to third-party systems
+- Working with sensitive data
+- Privacy regulations require minimizing data collection
+
+### Configuration
+
+**Disable PII logging in settings:**
+
+```json
+{
+  "telemetry": {
+    "logPrompts": false
+  }
+}
+```
+
+**Disable via environment variable:**
+
+```bash
+export GEMINI_TELEMETRY_LOG_PROMPTS=false
+```
+
+### Sensitive data in hooks
+
+If your hooks process sensitive data:
+
+1. **Minimize logging:** Don't write sensitive data to log files
+2. **Sanitize outputs:** Remove sensitive data before outputting
+3. **Use secure storage:** Encrypt sensitive data at rest
+4. **Limit access:** Restrict hook script permissions
+
+**Example sanitization:**
+
+```javascript
+function sanitizeOutput(data) {
+  const sanitized = { ...data };
+
+  // Remove sensitive fields
+  delete sanitized.apiKey;
+  delete sanitized.password;
+
+  // Redact sensitive strings
+  if (sanitized.content) {
+    sanitized.content = sanitized.content.replace(
+      /api[_-]?key\s*[:=]\s*['"]?[a-zA-Z0-9_-]{20,}['"]?/gi,
+      '[REDACTED]',
+    );
+  }
+
+  return sanitized;
+}
+
+console.log(JSON.stringify(sanitizeOutput(hookOutput)));
+```
+
+## Learn more
+
+- [Hooks Reference](index.md) - Complete API reference
+- [Writing Hooks](writing-hooks.md) - Tutorial and examples
+- [Configuration](../cli/configuration.md) - Gemini CLI settings
+- [Hooks Design Document](../hooks-design.md) - Technical architecture

docs/hooks/index.md

@@ -0,0 +1,560 @@
+# Gemini CLI hooks
+
+Hooks are scripts or programs that Gemini CLI executes at specific points in the
+agentic loop, allowing you to intercept and customize behavior without modifying
+the CLI's source code.
+
+See [writing hooks guide](writing-hooks.md) for a tutorial on creating your
+first hook and a comprehensive example.
+
+See [best practices](best-practices.md) for guidelines on security, performance,
+and debugging.
+
+## What are hooks?
+
+With hooks, you can:
+
+- **Add context:** Inject relevant information before the model processes a
+  request
+- **Validate actions:** Review and block potentially dangerous operations
+- **Enforce policies:** Implement security and compliance requirements
+- **Log interactions:** Track tool usage and model responses
+- **Optimize behavior:** Dynamically adjust tool selection or model parameters
+
+Hooks run synchronously as part of the agent loop—when a hook event fires,
+Gemini CLI waits for all matching hooks to complete before continuing.
+
+## Core concepts
+
+### Hook events
+
+Hooks are triggered by specific events in Gemini CLI's lifecycle. The following
+table lists all available hook events:
+
+| Event                 | When It Fires                                 | Common Use Cases                           |
+| --------------------- | --------------------------------------------- | ------------------------------------------ |
+| `SessionStart`        | When a session begins                         | Initialize resources, load context         |
+| `SessionEnd`          | When a session ends                           | Clean up, save state                       |
+| `BeforeAgent`         | After user submits prompt, before planning    | Add context, validate prompts              |
+| `AfterAgent`          | When agent loop ends                          | Review output, force continuation          |
+| `BeforeModel`         | Before sending request to LLM                 | Modify prompts, add instructions           |
+| `AfterModel`          | After receiving LLM response                  | Filter responses, log interactions         |
+| `BeforeToolSelection` | Before LLM selects tools (after BeforeModel)  | Filter available tools, optimize selection |
+| `BeforeTool`          | Before a tool executes                        | Validate arguments, block dangerous ops    |
+| `AfterTool`           | After a tool executes                         | Process results, run tests                 |
+| `PreCompress`         | Before context compression                    | Save state, notify user                    |
+| `Notification`        | When a notification occurs (e.g., permission) | Auto-approve, log decisions                |
+
+### Hook types
+
+Gemini CLI currently supports **command hooks** that run shell commands or
+scripts:
+
+```json
+{
+  "type": "command",
+  "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh",
+  "timeout": 30000
+}
+```
+
+**Note:** Plugin hooks (npm packages) are planned for a future release.
+
+### Matchers
+
+For tool-related events (`BeforeTool`, `AfterTool`), you can filter which tools
+trigger the hook:
+
+```json
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "WriteFile|Edit",
+        "hooks": [
+          /* hooks for write operations */
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Matcher patterns:**
+
+- **Exact match:** `"ReadFile"` matches only `ReadFile`
+- **Regex:** `"Write.*|Edit"` matches `WriteFile`, `WriteBinary`, `Edit`
+- **Wildcard:** `"*"` or `""` matches all tools
+
+**Session event matchers:**
+
+- **SessionStart:** `startup`, `resume`, `clear`
+- **SessionEnd:** `exit`, `clear`, `logout`, `prompt_input_exit`
+- **PreCompress:** `manual`, `auto`
+- **Notification:** `ToolPermission`
+
+## Hook input/output contract
+
+### Command hook communication
+
+Hooks communicate via:
+
+- **Input:** JSON on stdin
+- **Output:** Exit code + stdout/stderr
+
+### Exit codes
+
+- **0:** Success - stdout shown to user (or injected as context for some events)
+- **2:** Blocking error - stderr shown to agent/user, operation may be blocked
+- **Other:** Non-blocking warning - logged but execution continues
+
+### Common input fields
+
+Every hook receives these base fields:
+
+```json
+{
+  "session_id": "abc123",
+  "cwd": "/path/to/project",
+  "hook_event_name": "BeforeTool",
+  "timestamp": "2025-12-01T10:30:00Z"
+  // ... event-specific fields
+}
+```
+
+### Event-specific fields
+
+#### BeforeTool
+
+**Input:**
+
+```json
+{
+  "tool_name": "WriteFile",
+  "tool_input": {
+    "file_path": "/path/to/file.ts",
+    "content": "..."
+  }
+}
+```
+
+**Output (JSON on stdout):**
+
+```json
+{
+  "decision": "allow|deny|ask|block",
+  "reason": "Explanation shown to agent",
+  "systemMessage": "Message shown to user"
+}
+```
+
+Or simple exit codes:
+
+- Exit 0 = allow (stdout shown to user)
+- Exit 2 = deny (stderr shown to agent)
+
+#### AfterTool
+
+**Input:**
+
+```json
+{
+  "tool_name": "ReadFile",
+  "tool_input": { "file_path": "..." },
+  "tool_response": "file contents..."
+}
+```
+
+**Output:**
+
+```json
+{
+  "decision": "allow|deny",
+  "hookSpecificOutput": {
+    "hookEventName": "AfterTool",
+    "additionalContext": "Extra context for agent"
+  }
+}
+```
+
+#### BeforeAgent
+
+**Input:**
+
+```json
+{
+  "prompt": "Fix the authentication bug"
+}
+```
+
+**Output:**
+
+```json
+{
+  "decision": "allow|deny",
+  "hookSpecificOutput": {
+    "hookEventName": "BeforeAgent",
+    "additionalContext": "Recent project decisions: ..."
+  }
+}
+```
+
+#### BeforeModel
+
+**Input:**
+
+```json
+{
+  "llm_request": {
+    "model": "gemini-2.0-flash-exp",
+    "messages": [{ "role": "user", "content": "Hello" }],
+    "config": { "temperature": 0.7 },
+    "toolConfig": {
+      "functionCallingConfig": {
+        "mode": "AUTO",
+        "allowedFunctionNames": ["ReadFile", "WriteFile"]
+      }
+    }
+  }
+}
+```
+
+**Output:**
+
+```json
+{
+  "decision": "allow",
+  "hookSpecificOutput": {
+    "hookEventName": "BeforeModel",
+    "llm_request": {
+      "messages": [
+        { "role": "system", "content": "Additional instructions..." },
+        { "role": "user", "content": "Hello" }
+      ]
+    }
+  }
+}
+```
+
+#### AfterModel
+
+**Input:**
+
+```json
+{
+  "llm_request": {
+    "model": "gemini-2.0-flash-exp",
+    "messages": [
+      /* ... */
+    ],
+    "config": {
+      /* ... */
+    },
+    "toolConfig": {
+      /* ... */
+    }
+  },
+  "llm_response": {
+    "text": "string",
+    "candidates": [
+      {
+        "content": {
+          "role": "model",
+          "parts": ["array of content parts"]
+        },
+        "finishReason": "STOP"
+      }
+    ]
+  }
+}
+```
+
+**Output:**
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "AfterModel",
+    "llm_response": {
+      "candidate": {
+        /* modified response */
+      }
+    }
+  }
+}
+```
+
+#### BeforeToolSelection
+
+**Input:**
+
+```json
+{
+  "llm_request": {
+    "model": "gemini-2.0-flash-exp",
+    "messages": [
+      /* ... */
+    ],
+    "toolConfig": {
+      "functionCallingConfig": {
+        "mode": "AUTO",
+        "allowedFunctionNames": [
+          /* 100+ tools */
+        ]
+      }
+    }
+  }
+}
+```
+
+**Output:**
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "BeforeToolSelection",
+    "toolConfig": {
+      "functionCallingConfig": {
+        "mode": "ANY",
+        "allowedFunctionNames": ["ReadFile", "WriteFile", "Edit"]
+      }
+    }
+  }
+}
+```
+
+Or simple output (comma-separated tool names sets mode to ANY):
+
+```bash
+echo "ReadFile,WriteFile,Edit"
+```
+
+#### SessionStart
+
+**Input:**
+
+```json
+{
+  "source": "startup|resume|clear"
+}
+```
+
+**Output:**
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "Loaded 5 project memories"
+  }
+}
+```
+
+#### SessionEnd
+
+**Input:**
+
+```json
+{
+  "reason": "exit|clear|logout|prompt_input_exit|other"
+}
+```
+
+No structured output expected (but stdout/stderr logged).
+
+#### PreCompress
+
+**Input:**
+
+```json
+{
+  "trigger": "manual|auto"
+}
+```
+
+**Output:**
+
+```json
+{
+  "systemMessage": "Compression starting..."
+}
+```
+
+#### Notification
+
+**Input:**
+
+```json
+{
+  "notification_type": "ToolPermission",
+  "message": "string",
+  "details": {
+    /* notification details */
+  }
+}
+```
+
+**Output:**
+
+```json
+{
+  "systemMessage": "Notification logged"
+}
+```
+
+## Configuration
+
+Hook definitions are configured in `settings.json` files using the `hooks`
+object. Configuration can be specified at multiple levels with defined
+precedence rules.
+
+### Configuration layers
+
+Hook configurations are applied in the following order of precedence (higher
+numbers override lower numbers):
+
+1. **System defaults:** Built-in default settings (lowest precedence)
+2. **User settings:** `~/.gemini/settings.json`
+3. **Project settings:** `.gemini/settings.json` in your project directory
+4. **System settings:** `/etc/gemini-cli/settings.json` (highest precedence)
+
+Within each level, hooks run in the order they are declared in the
+configuration.
+
+### Configuration schema
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "pattern",
+        "hooks": [
+          {
+            "name": "hook-identifier",
+            "type": "command",
+            "command": "./path/to/script.sh",
+            "description": "What this hook does",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Configuration properties:**
+
+- **`name`** (string, required): Unique identifier for the hook used in
+  `/hooks enable/disable` commands
+- **`type`** (string, required): Hook type - currently only `"command"` is
+  supported
+- **`command`** (string, required): Path to the script or command to execute
+- **`description`** (string, optional): Human-readable description shown in
+  `/hooks panel`
+- **`timeout`** (number, optional): Timeout in milliseconds (default: 60000)
+- **`matcher`** (string, optional): Pattern to filter when hook runs (event
+  matchers only)
+
+### Environment variables
+
+Hooks have access to:
+
+- `GEMINI_PROJECT_DIR`: Project root directory
+- `GEMINI_SESSION_ID`: Current session ID
+- `GEMINI_API_KEY`: Gemini API key (if configured)
+- All other environment variables from the parent process
+
+## Managing hooks
+
+### View registered hooks
+
+Use the `/hooks panel` command to view all registered hooks:
+
+```bash
+/hooks panel
+```
+
+This command displays:
+
+- All active hooks organized by event
+- Hook source (user, project, system)
+- Hook type (command or plugin)
+- Execution status and recent output
+
+### Enable and disable hooks
+
+You can temporarily enable or disable individual hooks using commands:
+
+```bash
+/hooks enable hook-name
+/hooks disable hook-name
+```
+
+These commands allow you to control hook execution without editing configuration
+files. The hook name should match the `name` field in your hook configuration.
+
+### Disabled hooks configuration
+
+To permanently disable hooks, add them to the `hooks.disabled` array in your
+`settings.json`:
+
+```json
+{
+  "hooks": {
+    "disabled": ["secret-scanner", "auto-test"]
+  }
+}
+```
+
+**Note:** The `hooks.disabled` array uses a UNION merge strategy. Disabled hooks
+from all configuration levels (user, project, system) are combined and
+deduplicated, meaning a hook disabled at any level remains disabled.
+
+## Migration from Claude Code
+
+If you have hooks configured for Claude Code, you can migrate them:
+
+```bash
+gemini hooks migrate --from-claude
+```
+
+This command:
+
+- Reads `.claude/settings.json`
+- Converts event names (`PreToolUse` → `BeforeTool`, etc.)
+- Translates tool names (`Bash` → `RunShellCommand`, `Edit` → `Edit`)
+- Updates matcher patterns
+- Writes to `.gemini/settings.json`
+
+### Event name mapping
+
+| Claude Code        | Gemini CLI     |
+| ------------------ | -------------- |
+| `PreToolUse`       | `BeforeTool`   |
+| `PostToolUse`      | `AfterTool`    |
+| `UserPromptSubmit` | `BeforeAgent`  |
+| `Stop`             | `AfterAgent`   |
+| `Notification`     | `Notification` |
+| `SessionStart`     | `SessionStart` |
+| `SessionEnd`       | `SessionEnd`   |
+| `PreCompact`       | `PreCompress`  |
+
+### Tool name mapping
+
+| Claude Code | Gemini CLI        |
+| ----------- | ----------------- |
+| `Bash`      | `RunShellCommand` |
+| `Edit`      | `Edit`            |
+| `Read`      | `ReadFile`        |
+| `Write`     | `WriteFile`       |
+
+## Learn more
+
+- [Writing Hooks](writing-hooks.md) - Tutorial and comprehensive example
+- [Best Practices](best-practices.md) - Security, performance, and debugging
+- [Custom Commands](../cli/custom-commands.md) - Create reusable prompt
+  shortcuts
+- [Configuration](../cli/configuration.md) - Gemini CLI configuration options
+- [Hooks Design Document](../hooks-design.md) - Technical architecture details

docs/index.md

@@ -102,6 +102,15 @@ This documentation is organized into the following sections:
 - **[Extension releasing](./extensions/extension-releasing.md):** How to release
   Gemini CLI extensions.
 
+### Hooks
+
+- **[Hooks](./hooks/index.md):** Intercept and customize Gemini CLI behavior at
+  key lifecycle points.
+- **[Writing Hooks](./hooks/writing-hooks.md):** Learn how to create your first
+  hook with a comprehensive example.
+- **[Best Practices](./hooks/best-practices.md):** Security, performance, and
+  debugging guidelines for hooks.
+
 ### IDE integration
 
 - **[Introduction to IDE integration](./ide-integration/index.md):** Connect the

docs/integration-tests.md

@@ -199,9 +199,9 @@ file, or case.
 ## Continuous integration
 
 To ensure the integration tests are always run, a GitHub Actions workflow is
-defined in `.github/workflows/e2e.yml`. This workflow automatically runs the
-integrations tests for pull requests against the `main` branch, or when a pull
-request is added to a merge queue.
+defined in `.github/workflows/chained_e2e.yml`. This workflow automatically runs
+the integrations tests for pull requests against the `main` branch, or when a
+pull request is added to a merge queue.
 
 The workflow runs the tests in different sandboxing environments to ensure
 Gemini CLI is tested across each:

docs/issue-and-pr-automation.md

@@ -14,6 +14,9 @@ feature), while the PR is the "how" (the implementation). This separation helps
 us track work, prioritize features, and maintain clear historical context. Our
 automation is built around this principle.
 
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.
+
 ---
 
 ## Detailed automation workflows

docs/release-confidence.md

@@ -33,7 +33,7 @@ nightly) or the release branch (for preview/stable).
 
 ### 2. End-to-end (E2E) tests
 
-All workflows in `.github/workflows/e2e.yml` must pass.
+All workflows in `.github/workflows/chained_e2e.yml` must pass.
 
 - **Platforms:** **Linux, macOS and Windows**.
 - **Sandboxing:** Tests must pass with both `sandbox:none` and `sandbox:docker`

docs/sidebar.json

@@ -24,7 +24,7 @@
         "slug": "docs/get-started"
       },
       {
-        "label": "Gemini 3 Pro on Gemini CLI",
+        "label": "Gemini 3 on Gemini CLI",
         "slug": "docs/get-started/gemini-3"
       },
       {
@@ -193,6 +193,23 @@
       }
     ]
   },
+  {
+    "label": "Hooks",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/hooks"
+      },
+      {
+        "label": "Writing hooks",
+        "slug": "docs/hooks/writing-hooks"
+      },
+      {
+        "label": "Best practices",
+        "slug": "docs/hooks/best-practices"
+      }
+    ]
+  },
   {
     "label": "IDE integration",
     "items": [
@@ -217,10 +234,6 @@
         "label": "Releases",
         "slug": "docs/releases"
       },
-      {
-        "label": "Changelog",
-        "slug": "docs/changelogs"
-      },
       {
         "label": "Integration tests",
         "slug": "docs/integration-tests"
@@ -231,6 +244,27 @@
       }
     ]
   },
+  {
+    "label": "Releases",
+    "items": [
+      {
+        "label": "Release notes",
+        "slug": "docs/changelogs/"
+      },
+      {
+        "label": "Latest release",
+        "slug": "docs/changelogs/latest"
+      },
+      {
+        "label": "Preview release",
+        "slug": "docs/changelogs/preview"
+      },
+      {
+        "label": "Changelog",
+        "slug": "docs/changelogs/releases"
+      }
+    ]
+  },
   {
     "label": "Support",
     "items": [

docs/tools/file-system.md

@@ -36,8 +36,9 @@ glob patterns.
 ## 2. `read_file` (ReadFile)
 
 `read_file` reads and returns the content of a specified file. This tool handles
-text, images (PNG, JPG, GIF, WEBP, SVG, BMP), and PDF files. For text files, it
-can read specific line ranges. Other binary file types are generally skipped.
+text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC,
+OGG, FLAC), and PDF files. For text files, it can read specific line ranges.
+Other binary file types are generally skipped.
 
 - **Tool name:** `read_file`
 - **Display name:** ReadFile
@@ -53,16 +54,16 @@ can read specific line ranges. Other binary file types are generally skipped.
   - For text files: Returns the content. If `offset` and `limit` are used,
     returns only that slice of lines. Indicates if content was truncated due to
     line limits or line length limits.
-  - For image and PDF files: Returns the file content as a base64-encoded data
-    structure suitable for model consumption.
+  - For image, audio, and PDF files: Returns the file content as a
+    base64-encoded data structure suitable for model consumption.
   - For other binary files: Attempts to identify and skip them, returning a
     message indicating it's a generic binary file.
 - **Output:** (`llmContent`):
   - For text files: The file content, potentially prefixed with a truncation
     message (e.g.,
     `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
-  - For image/PDF files: An object containing `inlineData` with `mimeType` and
-    base64 `data` (e.g.,
+  - For image/audio/PDF files: An object containing `inlineData` with `mimeType`
+    and base64 `data` (e.g.,
     `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
   - For other binary files: A message like
     `Cannot display content of binary file: /path/to/data.bin`.

docs/tools/mcp-server.md

@@ -16,8 +16,8 @@ An MCP server enables the Gemini CLI to:
   through standardized schema definitions.
 - **Execute tools:** Call specific tools with defined arguments and receive
   structured responses.
-- **Access resources:** Read data from specific resources (though the Gemini CLI
-  primarily focuses on tool execution).
+- **Access resources:** Read data from specific resources that the server
+  exposes (files, API payloads, reports, etc.).
 
 With an MCP server, you can extend the Gemini CLI's capabilities to perform
 actions beyond its built-in features, such as interacting with databases, APIs,
@@ -40,6 +40,7 @@ The discovery process is orchestrated by `discoverMcpTools()`, which:
 4. **Sanitizes and validates** tool schemas for compatibility with the Gemini
    API
 5. **Registers tools** in the global tool registry with conflict resolution
+6. **Fetches and registers resources** if the server exposes any
 
 ### Execution layer (`mcp-tool.ts`)
 
@@ -59,6 +60,32 @@ The Gemini CLI supports three MCP transport types:
 - **SSE Transport:** Connects to Server-Sent Events endpoints
 - **Streamable HTTP Transport:** Uses HTTP streaming for communication
 
+## Working with MCP resources
+
+Some MCP servers expose contextual “resources” in addition to the tools and
+prompts. Gemini CLI discovers these automatically and gives you the possibility
+to reference them in the chat.
+
+### Discovery and listing
+
+- When discovery runs, the CLI fetches each server’s `resources/list` results.
+- The `/mcp` command displays a Resources section alongside Tools and Prompts
+  for every connected server.
+
+This returns a concise, plain-text list of URIs plus metadata.
+
+### Referencing resources in a conversation
+
+You can use the same `@` syntax already known for referencing local files:
+
+```
+@server://resource/path
+```
+
+Resource URIs appear in the completion menu together with filesystem paths. When
+you submit the message, the CLI calls `resources/read` and injects the content
+in the conversation.
+
 ## How to set up your MCP server
 
 The Gemini CLI uses the `mcpServers` configuration in your `settings.json` file

docs/tools/todos.md

@@ -26,7 +26,7 @@ plan.
 
 - **Progress tracking:** The agent updates this list as it works, marking tasks
   as `completed` when done.
-- **Single socus:** Only one task will be marked `in_progress` at a time,
+- **Single focus:** Only one task will be marked `in_progress` at a time,
   indicating exactly what the agent is currently working on.
 - **Dynamic updates:** The plan may evolve as the agent discovers new
   information, leading to new tasks being added or unnecessary ones being

docs/troubleshooting.md

@@ -124,8 +124,7 @@ This is especially useful for scripting and automation.
 ## Debugging tips
 
 - **CLI debugging:**
-  - Use the `--verbose` flag (if available) with CLI commands for more detailed
-    output.
+  - Use the `--debug` flag for more detailed output.
   - Check the CLI logs, often found in a user-specific configuration or cache
     directory.
 
@@ -154,3 +153,6 @@ guide_, consider searching the Gemini CLI
 [Issue tracker on GitHub](https://github.com/google-gemini/gemini-cli/issues).
 If you can't find an issue similar to yours, consider creating a new GitHub
 Issue with a detailed description. Pull requests are also welcome!
+
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.

eslint.config.js

@@ -165,6 +165,8 @@ export default tseslint.config(
       'prefer-const': ['error', { destructuring: 'all' }],
       radix: 'error',
       'default-case': 'error',
+      '@typescript-eslint/no-floating-promises': ['error'],
+      '@typescript-eslint/no-unnecessary-type-assertion': ['error'],
     },
   },
   {

hello/commands/fs/grep-code.toml

@@ -1,6 +0,0 @@
-prompt = """
-Please summarize the findings for the pattern `{{args}}`.
-
-Search Results:
-!{grep -r {{args}} .}
-"""

hello/gemini-extension.json

@@ -1,4 +0,0 @@
-{
-  "name": "custom-commands",
-  "version": "1.0.0"
-}

integration-tests/ctrl-c-exit.test.ts

@@ -4,13 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as os from 'node:os';
 import { TestRig } from './test-helper.js';
 
 describe('Ctrl+C exit', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should exit gracefully on second Ctrl+C', async () => {
-    const rig = new TestRig();
     await rig.setup('should exit gracefully on second Ctrl+C', {
       settings: { tools: { useRipgrep: false } },
     });

integration-tests/extensions-install.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -20,8 +20,15 @@ const extensionUpdate = `{
 }`;
 
 describe('extension install', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('installs a local extension, verifies a command, and updates it', async () => {
-    const rig = new TestRig();
     rig.setup('extension install test');
     const testServerPath = join(rig.testDir!, 'gemini-extension.json');
     writeFileSync(testServerPath, extension);
@@ -47,7 +54,6 @@ describe('extension install', () => {
         'uninstall',
         'test-extension-install',
       ]);
-      await rig.cleanup();
     }
   });
 });

integration-tests/extensions-reload.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { expect, it, describe } from 'vitest';
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 import { TestMcpServer } from './test-mcp-server.js';
 import { writeFileSync } from 'node:fs';
@@ -18,10 +18,23 @@ import stripAnsi from 'strip-ansi';
 const itIf = (condition: boolean) => (condition ? it : it.skip);
 
 describe('extension reloading', () => {
-  const sandboxEnv = env['GEMINI_SANDBOX'];
+  let rig: TestRig;
 
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
+  const sandboxEnv = env['GEMINI_SANDBOX'];
+  // Fails in linux non-sandbox e2e tests
+  // TODO(#14527): Re-enable this once fixed
   // Fails in sandbox mode, can't check for local extension updates.
-  itIf((!sandboxEnv || sandboxEnv === 'false') && platform() !== 'win32')(
+  itIf(
+    (!sandboxEnv || sandboxEnv === 'false') &&
+      platform() !== 'win32' &&
+      platform() !== 'linux',
+  )(
     'installs a local extension, updates it, checks it was reloaded properly',
     async () => {
       const serverA = new TestMcpServer();
@@ -38,7 +51,6 @@ describe('extension reloading', () => {
         },
       };
 
-      const rig = new TestRig();
       rig.setup('extension reload test', {
         settings: {
           experimental: { extensionReloading: true },
@@ -70,7 +82,7 @@ describe('extension reloading', () => {
       writeFileSync(testServerPath, safeJsonStringify(extension, 2));
 
       // Start the CLI.
-      const run = await rig.runInteractive('--debug');
+      const run = await rig.runInteractive({ args: '--debug' });
       await run.expectText('You have 1 extension with an update available');
       // See the outdated extension
       await run.sendText('/extensions list');
@@ -140,7 +152,6 @@ describe('extension reloading', () => {
       await serverA.stop();
       await serverB.stop();
       await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
-      await rig.cleanup();
     },
   );
 });

integration-tests/file-system.test.ts

@@ -4,20 +4,29 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 
 describe('file-system', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should be able to read a file', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to read a file');
+    await rig.setup('should be able to read a file', {
+      settings: { tools: { core: ['read_file'] } },
+    });
     rig.createFile('test.txt', 'hello world');
 
-    const result = await rig.run(
-      `read the file test.txt and show me its contents`,
-    );
+    const result = await rig.run({
+      args: `read the file test.txt and show me its contents`,
+    });
 
     const foundToolCall = await rig.waitForToolCall('read_file');
 
@@ -39,11 +48,14 @@ describe('file-system', () => {
   });
 
   it('should be able to write a file', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to write a file');
+    await rig.setup('should be able to write a file', {
+      settings: { tools: { core: ['write_file', 'replace', 'read_file'] } },
+    });
     rig.createFile('test.txt', '');
 
-    const result = await rig.run(`edit test.txt to have a hello world message`);
+    const result = await rig.run({
+      args: `edit test.txt to have a hello world message`,
+    });
 
     // Accept multiple valid tools for editing files
     const foundToolCall = await rig.waitForAnyToolCall([
@@ -94,13 +106,14 @@ describe('file-system', () => {
   });
 
   it('should correctly handle file paths with spaces', async () => {
-    const rig = new TestRig();
-    await rig.setup('should correctly handle file paths with spaces');
+    await rig.setup('should correctly handle file paths with spaces', {
+      settings: { tools: { core: ['write_file', 'read_file'] } },
+    });
     const fileName = 'my test file.txt';
 
-    const result = await rig.run(
-      `write "hello" to "${fileName}" and then stop. Do not perform any other actions.`,
-    );
+    const result = await rig.run({
+      args: `write "hello" to "${fileName}" and then stop. Do not perform any other actions.`,
+    });
 
     const foundToolCall = await rig.waitForToolCall('write_file');
     if (!foundToolCall) {
@@ -116,13 +129,14 @@ describe('file-system', () => {
   });
 
   it('should perform a read-then-write sequence', async () => {
-    const rig = new TestRig();
-    await rig.setup('should perform a read-then-write sequence');
+    await rig.setup('should perform a read-then-write sequence', {
+      settings: { tools: { core: ['read_file', 'replace', 'write_file'] } },
+    });
     const fileName = 'version.txt';
     rig.createFile(fileName, '1.0.0');
 
     const prompt = `Read the version from ${fileName} and write the next version 1.0.1 back to the file.`;
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     await rig.waitForTelemetryReady();
     const toolLogs = rig.readToolLogs();
@@ -151,16 +165,15 @@ describe('file-system', () => {
   });
 
   it.skip('should replace multiple instances of a string', async () => {
-    const rig = new TestRig();
     rig.setup('should replace multiple instances of a string');
     const fileName = 'ambiguous.txt';
     const fileContent = 'Hey there, \ntest line\ntest line';
     const expectedContent = 'Hey there, \nnew line\nnew line';
     rig.createFile(fileName, fileContent);
 
-    const result = await rig.run(
-      `rewrite the file ${fileName} to replace all instances of "test line" with "new line"`,
-    );
+    const result = await rig.run({
+      args: `rewrite the file ${fileName} to replace all instances of "test line" with "new line"`,
+    });
 
     const validTools = ['write_file', 'edit'];
     const foundToolCall = await rig.waitForAnyToolCall(validTools);
@@ -203,13 +216,15 @@ describe('file-system', () => {
   });
 
   it('should fail safely when trying to edit a non-existent file', async () => {
-    const rig = new TestRig();
     await rig.setup(
       'should fail safely when trying to edit a non-existent file',
+      { settings: { tools: { core: ['read_file', 'replace'] } } },
     );
     const fileName = 'non_existent.txt';
 
-    const result = await rig.run(`In ${fileName}, replace "a" with "b"`);
+    const result = await rig.run({
+      args: `In ${fileName}, replace "a" with "b"`,
+    });
 
     await rig.waitForTelemetryReady();
     const toolLogs = rig.readToolLogs();

integration-tests/flicker.test.ts

@@ -4,36 +4,39 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 import { join } from 'node:path';
 
 describe('Flicker Detector', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should not detect a flicker under the max height budget', async () => {
-    const rig = new TestRig();
     rig.setup('flicker-detector-test', {
       fakeResponsesPath: join(
         import.meta.dirname,
         'flicker-detector.max-height.responses',
       ),
     });
-    try {
-      const run = await rig.runInteractive();
-      const prompt = 'Tell me a fun fact.';
-      await run.type(prompt);
-      await run.type('\r');
+    const run = await rig.runInteractive();
+    const prompt = 'Tell me a fun fact.';
+    await run.type(prompt);
+    await run.type('\r');
 
-      const hasUserPromptEvent = await rig.waitForTelemetryEvent('user_prompt');
-      expect(hasUserPromptEvent).toBe(true);
+    const hasUserPromptEvent = await rig.waitForTelemetryEvent('user_prompt');
+    expect(hasUserPromptEvent).toBe(true);
 
-      const hasSessionCountMetric = await rig.waitForMetric('session.count');
-      expect(hasSessionCountMetric).toBe(true);
+    const hasSessionCountMetric = await rig.waitForMetric('session.count');
+    expect(hasSessionCountMetric).toBe(true);
 
-      // We expect NO flicker event to be found.
-      const flickerMetric = rig.readMetric('ui.flicker.count');
-      expect(flickerMetric).toBeNull();
-    } finally {
-      await rig.cleanup();
-    }
+    // We expect NO flicker event to be found.
+    const flickerMetric = rig.readMetric('ui.flicker.count');
+    expect(flickerMetric).toBeNull();
   });
 });

integration-tests/google_web_search.test.ts

@@ -5,17 +5,26 @@
  */
 
 import { WEB_SEARCH_TOOL_NAME } from '../packages/core/src/tools/tool-names.js';
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 
-describe(WEB_SEARCH_TOOL_NAME, () => {
+describe('web search tool', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should be able to search the web', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to search the web');
+    await rig.setup('should be able to search the web', {
+      settings: { tools: { core: [WEB_SEARCH_TOOL_NAME] } },
+    });
 
     let result;
     try {
-      result = await rig.run(`what is the weather in London`);
+      result = await rig.run({ args: `what is the weather in London` });
     } catch (error) {
       // Network errors can occur in CI environments
       if (

integration-tests/hooks-system.compress-auto.responses

@@ -0,0 +1 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Devising a Greeting Phrase**\n\nI've been occupied by the constraint of constructing a five-word salutation. My goal is to make it natural and concise. I'm exploring various combinations to meet the specified word count precisely.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12587,"totalTokenCount":12612,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12587}],"thoughtsTokenCount":25}},{"candidates":[{"content":{"parts":[{"text":"Hello! How can I help you?","thoughtSignature":"CiQBcsjafHso9FUsdYOCTv1xOLlW4MnjbeYnUUBocz0KNgHSzOcKZAFyyNp8XuI6j2afRczgPL8v1dxfVwAJ+5XDKhWKIYf1/8TKGVHh7xXnPfdYBdQ07Ohe7OZXr92xL/IC7B1U2SHDuAOozC0CCW7aiDysu6Hbo6jzYfW5epKht4QjdxYgcKHySrkKMQFyyNp8jXWlHmox53O/CJPXXz2FAmw+ubHKBpYgRezBpA+byyEY2RbVYlZlEMSNkhs="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12587,"candidatesTokenCount":7,"totalTokenCount":12619,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12587}],"thoughtsTokenCount":25}}]}

integration-tests/hooks-system.disabled-via-command.responses

@@ -0,0 +1,4 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Creating the First Test File**\n\nI'll use the `write_file` tool to create `first-run.txt` with the content \"test1\".\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12779,"totalTokenCount":12824,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12779}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}],"thoughtsTokenCount":45}},{"candidates":[{"content":{"parts":[{"functionCall":{"name":"write_file","args":{"content":"test1","file_path":"first-run.txt"}},"thoughtSignature":"CiQBcsjafG+JDSqtKOK+ZvSjZQZmS91c1Gz0YyTiirI2u5+rhEIKZAFyyNp8DNXb+xHILTC+FVlEifqEHdrmfFNBLKojci1UIBhcZpQ4UXCMkxUXYKO34IjTlyLgSsjVbbXWEFXatb/z/RtTDcf51uc3YOEwlDScGempkJxfFgcPfIiD7bhuHBqdQfUKfAFyyNp8wZ71h+QjdfVw12PwDXWgGZ0Xed1GuyJXuqAwpWnwxDIvsDaPwDFYyLR1XDiIZZk4AvFCGt6HGMSLRuPh4K3i9CVnDc5hcjyvMIde0idAFMrgs2Mq5SARfCPrWkqyq2f0Q0WonUl2n7yr/sDQ78rx2E6qXyUJ8XMKfAFyyNp8DdTYLttyI0jknqAeZDxdFmHtpJUI8UKP5YHzpQc8Qn80OJcwhZSRH4HRKCqoC7Sukq/A5vJ5T468WqgjOoLlPLq02bYRTf/q6LC1ogEhdLHrcFv2jDeCdXJJ8NHv3O4DZAUAk1W5Gd0428zMFOxH3AgkWwEGuow="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12779,"candidatesTokenCount":24,"totalTokenCount":12848,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12779}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}],"thoughtsTokenCount":45}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"File created successfully. Active hook executed"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12951,"candidatesTokenCount":7,"totalTokenCount":12958,"cachedContentTokenCount":12202,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12951}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12202}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Creating the Second Test File**\n\nI'll use the `write_file` tool to create `second-run.txt` with the content \"test2\".\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12779,"totalTokenCount":12826,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12779}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}],"thoughtsTokenCount":47}},{"candidates":[{"content":{"parts":[{"functionCall":{"name":"write_file","args":{"content":"test2","file_path":"second-run.txt"}},"thoughtSignature":"CiQBcsjafG+JDSqtKOK+ZvSjZQZmS91c1Gz0YyTiirI2u5+rhEIKZAFyyNp8DNXb+xHILTC+FVlEifqEHdrmfFNBLKojci1UIBhcZpQ4UXCMkxUXYKO34IjTlyLgSsjVbbXWEFXatb/z/RtTDcf51uc3YOEwlDScGempkJxfFgcPfIiD7bhuHBqdQfUKfAFyyNp8wZ71h+QjdfVw12PwDXWgGZ0Xed1GuyJXuqAwpWnwxDIvsDaPwDFYyLR1XDiIZZk4AvFCGt6HGMSLRuPh4K3i9CVnDc5hcjyvMIde0idAFMrgs2Mq5SARfCPrWkqyq2f0Q0WonUl2n7yr/sDQ78rx2E6qXyUJ8XMKfAFyyNp8DdTYLttyI0jknqAeZDxdFmHtpJUI8UKP5YHzpQc8Qn80OJcwhZSRH4HRKCqoC7Sukq/A5vJ5T468WqgjOoLlPLq02bYRTf/q6LC1ogEhdLHrcFv2jDeCdXJJ8NHv3O4DZAUAk1W5Gd0428zMFOxH3AgkWwEGuow="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12779,"candidatesTokenCount":24,"totalTokenCount":12850,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12779}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}],"thoughtsTokenCount":47}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"File created successfully. Active hook executed"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12951,"candidatesTokenCount":7,"totalTokenCount":12958,"cachedContentTokenCount":12202,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12951}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12202}]}}]}

integration-tests/hooks-system.disabled-via-settings.responses

@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Creating the Test File**\n\nI'll use the `write_file` tool to create `disabled-test.txt` with the content \"test\".\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12779,"totalTokenCount":12820,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12779}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}],"thoughtsTokenCount":41}},{"candidates":[{"content":{"parts":[{"functionCall":{"name":"write_file","args":{"content":"test","file_path":"disabled-test.txt"}},"thoughtSignature":"CiQBcsjafG+JDSqtKOK+ZvSjZQZmS91c1Gz0YyTiirI2u5+rhEIKZAFyyNp8DNXb+xHILTC+FVlEifqEHdrmfFNBLKojci1UIBhcZpQ4UXCMkxUXYKO34IjTlyLgSsjVbbXWEFXatb/z/RtTDcf51uc3YOEwlDScGempkJxfFgcPfIiD7bhuHBqdQfUKfAFyyNp8wZ71h+QjdfVw12PwDXWgGZ0Xed1GuyJXuqAwpWnwxDIvsDaPwDFYyLR1XDiIZZk4AvFCGt6HGMSLRuPh4K3i9CVnDc5hcjyvMIde0idAFMrgs2Mq5SARfCPrWkqyq2f0Q0WonUl2n7yr/sDQ78rx2E6qXyUJ8XMKfAFyyNp8DdTYLttyI0jknqAeZDxdFmHtpJUI8UKP5YHzpQc8Qn80OJcwhZSRH4HRKCqoC7Sukq/A5vJ5T468WqgjOoLlPLq02bYRTf/q6LC1ogEhdLHrcFv2jDeCdXJJ8NHv3O4DZAUAk1W5Gd0428zMFOxH3AgkWwEGuow="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12779,"candidatesTokenCount":24,"totalTokenCount":12844,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12779}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}],"thoughtsTokenCount":41}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"File created successfully. Enabled hook executed."}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12951,"candidatesTokenCount":8,"totalTokenCount":12959,"cachedContentTokenCount":12202,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12951}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12202}]}}]}

integration-tests/hooks-system.multiple-events.responses

@@ -0,0 +1,4 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Formulating a Plan**\n\nOkay, I've outlined the initial steps: I'll use the `write_file` tool to make a file named `multi-event-test.txt` containing the text \"testing multiple events\". After that, I'll need to remember to reply with the phrase as requested. It seems straightforward so far.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12622,"totalTokenCount":12692,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12622}],"thoughtsTokenCount":70}},{"candidates":[{"content":{"parts":[{"text":"**Confirming the Procedure**\n\nI've solidified the steps. First, I'll create `multi-event-test.txt` using the `write_file` tool with the required content. Following that, my response will be \"BeforeAgent: User request processed.\" This ensures I fulfill both parts of the request.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12622,"totalTokenCount":12713,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12622}],"thoughtsTokenCount":91}},{"candidates":[{"content":{"parts":[{"functionCall":{"name":"write_file","args":{"file_path":"multi-event-test.txt","content":"testing multiple events"}},"thoughtSignature":"CiQBcsjafIqcYtNLIeBwJi3k5k8jho3QiWM+51Kw5vTQ7/V4qVQKZgFyyNp8mIIB0+Mvwhvo2fACDpTWpRYeOFPGrjZrc+N05S0WGEHzE4Dv9peHKdvZkjGNW+HyYHXoRpd5c/ScdhPxQoVZmZ9K7sRjVxv/nWVDoKnHlSsn94nJ8acjLnj1oqt9cHni0ApyAXLI2nwj5WuLHr+UFIxnqRKCUJboLo6bQMkqR1TsqXbjsgHp3zNQYT+xzbse4PKPLJV48FN6cL9MrrZ81E7k7AVo1cKyrC7ky7tdRH6gYHewIqgQWBIUgMKhLkePH/fYZ6fS7SMrf4Q6DFGHh6pIAAdRCooBAXLI2nxpudEZr+5jZAaAcCMIdij5oZq3s0xsQv/7iWVh8IossRuR0J4eMMSN8fV6+fjbSQ6YtJQfrxsm3a6gVIkJNno2b2PRZestS/0Z7DvPDGE6r1sGchvbcz8EW7Z/pvJvPBRFWlMTJ1eqY9vuyuNYMKeWlyt+5V9y2GUbcLWvcNDZSC43vQEKCo0BAXLI2nxP4INgBaSHInyFrG1/SEP0SUimKvP69FkcIBxx60x3iKqdtb2flLIhoOr/QuesASlflRfzNo3J5LOudrjZzNlRfVRqOZIyOVxZlviXtO7+w/oPCV61Sby6xPTGtFsWlt6GxEGF7iYLfvi4KWN9q/W9tlqEqUrpl/WMwS/4pYBi1xPcvXZNlJ6g"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12622,"candidatesTokenCount":28,"totalTokenCount":12741,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12622}],"thoughtsTokenCount":91}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12836,"totalTokenCount":12836,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12836}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}]}},{"candidates":[{"content":{"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12836,"totalTokenCount":12836,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12836}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12836,"totalTokenCount":12836,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12836}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}]}},{"candidates":[{"content":{"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12836,"totalTokenCount":12836,"cachedContentTokenCount":12204,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12836}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12204}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Echoing User Commands**\n\nI'm now tasked with echoing a specific phrase following a particular signal, but it's becoming complex. The user wants me to repeat \"BeforeAgent: User request processed\" when prompted. It appears I need to retain context from the previous turn, the user's initial request to create a file, to correctly respond now.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12759,"totalTokenCount":12827,"cachedContentTokenCount":12199,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12759}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12199}],"thoughtsTokenCount":68}},{"candidates":[{"content":{"parts":[{"text":"**Responding Precisely to Prompt**\n\nI've determined I need to repeat the phrase \"BeforeAgent: User request processed,\" even though the overall context and turn history are complex. The user has given several prompts, but has now provided a more direct command, which I believe is to follow up on the previous request. I am taking care to match the specific instructions the user provided.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12759,"totalTokenCount":12982,"cachedContentTokenCount":12199,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12759}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12199}],"thoughtsTokenCount":223}},{"candidates":[{"content":{"parts":[{"text":"BeforeAgent: User request processed","thoughtSignature":"CiQBcsjafAntJrb1JBgpnZaCNeYhOJXtbH6dKTeM1llglCdoOvUKYwFyyNp8PUj5sihYyITQJhdz4MqEeftyuUc4G+iTprve11gPN04eK9Y1Wi/wyln4RjRgroIrV5kByKzdGhECoyCeInpiILGhY0peIM7dZOKFdIOL7xAR9pmn4wMreqyH7l5WSAqJAQFyyNp8Cugemkt4YZWkIwEJYmUukLFx4d5EwP/9k/e4OH/svpM+uyuN3n1KVN3bFgRV5yuF0HnDLl+P7WVSSxMmWvXO2f7A1HALg+gCvZw9IV7Btgg1qp81dDoNcVkzSbTBtT4UrlJ5R6sclvHZOLUtKGwBEQ6zRonBugAgj9RV4BT1AJNOgdSsCokBAXLI2nyDGU1Iq30QVbqhgEwFa5sB6uPC+35BV8ZKGwK+YglO9rqXMrkXM+GcQi2hVIsOFXBYGTS6E2/mQfFbIKDytrb1JgP3q5xVd/bE23M2Nnf+q5TLbRpLAPmyfg0AGwhN0L7d5W6b/3ydqEPeA1/Vw/cnBzz5ND1LOTOX6BFqEs33/WHj7HIKpAEBcsjafEsn8//cZMWUQcSAucBQauojv/f7h11nbeMrZK84nEotR30BgMIWYiiWM6sGDy/4MzHwr+z2YdAz4PSgRvEf7DPxHps2nvZfAdtskgtdPl2JD81WpokSnJvCqU+cOuz+Nh3+fIiZ6vEsVpi/5cwEiGT0g3Z3I2ubyzv58oH8YnVQlKT3MsKRGb5//aXZJY57jNrexgDPzYAQsBgSuGBmqwqaAQFyyNp8sSIYw3It6GpZqC+oxJCC26pt4RxhG8rDZ3zuoADYlOpoUdSzbNuDB+iVHeen5OoCEAaH0GrFV4iZxgu40wu4ZD/VMfHi/Vm7vku23EUV/94U8mT+VEwPfd2gqv+3xPZ9MEHjOOox1Xq1984w2cA6u0Qn7wWHXeOGFVGSOHtdJtQ7ToNT8VEecblAVq8lm42sSccXQEEKmAEBcsjafONCvBhW2s8Bset20YFdbeSHelnILFDxXlCoYla5nP5UjGk4vpXu2+7RCFtKXfoyYEVEkmiGBRsmwJ82Q1nMkGkXMhuTdNhu4aCwI5m+STGxx26vkp9bcqGwMDHBotZL63PSrJacRoW8zfpDXD1PABLeTIfh5jgipQdgltyjlbc+3qfIfjBYNRSkE8ByErSz5rT7SwqSAQFyyNp8W2kut1PSJISxM7YJtbRdFqPBTikGDM6F/3l6ba6LpeRBfHdtueLChqFpwLH41VdIPQ7lRZflOq3KaZz+TQ11eDnYQbiaIdGOPgHJ/HH/0iQv2hnoOY5vg3gubFWFuZh9Bfun2VCYUI39tIxGC46TZWfgCdiP/O9CFOlpDfidPiz5ZS/4LhG9FA4Q85OuCpEBAXLI2nzpoEUA6jCZopeNTRA2uZ1r0DMm5cWVVXtFO4CoRS+19BbADNBRyNrR5qcf7bUflJBvMRVxx3mtmgK9aE5VmKYxK2Dqg15l9RUxjtqspC3VVmszVd6lOkf1BBQ/VtWDulqRetKE2u62Is9NNGuK9HsLzIBLRRc8QoML41WffuXQ+uxwyXpjx2USC44MGAqIAQFyyNp8gN3lOyHyk674W3Pyv+Egw1ZDUQK4xpvAfgnK+y53gclMGJ2IjOSvg4j0f1WO1OGqY2TBUFS7w21PXasvCkfxpqeStEb+U7Vm0r63LzXdGdug5/b1Ap6Phn4/vAYmfaKISKG4+QpjI+ehgEJzsIee2rgqOaePTP18fq8T7EDbF/B/iscKNQFyyNp8DWt2a8OetaCc5E/KsntbbOcNc7yikPZBdUezphrqIH4ztpicsHvEicYF002qWHoY"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12759,"candidatesTokenCount":4,"totalTokenCount":12986,"cachedContentTokenCount":12199,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12759}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":12199}],"thoughtsTokenCount":223}}]}

integration-tests/hooks-system.notification.responses

@@ -0,0 +1 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Executing the Command**\n\nI've got the command, \"echo test,\" ready to go. My focus is entirely on calling the `run_shell_command` tool now. The user's input is processed, and the next step is straightforward: using the tool to execute the supplied command.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12751,"totalTokenCount":12801,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12751}],"thoughtsTokenCount":50}},{"candidates":[{"content":{"parts":[{"functionCall":{"name":"run_shell_command","args":{"command":"echo test","description":"Running the command 'echo test'"}},"thoughtSignature":"CiQBcsjafL1lDlnUGmt38n1/gjwecXzy9S3qEW5sYMEno5Mr7LEKZgFyyNp8jMABmMAatt49FTdh7UiM62SI1GnjcyG+kV7xzcD73uMKHST/0D0vKP7x1equv5d6YiXnOslhVnnHotYPtVl0/kI/0unBZRdMzkBNrJXKUoSWXJXxNpV6JhJav3Uh9h1sPQqOAQFyyNp8PFeESLk0J5cPFP0EA7a13iA/rXTiKoHnjSCzDV9ALcXM78xv10/V028ZtDeQslYfT82q4++W8AlJwTQRTIrdscu2y+nCS8jnQizYN1V1yR42eMzuBU3txXcqEV8bmP6GGOe58vrqyS2zdnJKCgMntMB/niwlJlr5frhDestSOJk62tVDWKFzOiAKOAFyyNp81FtGXQTX+OSio/2PbzpCCuaQFqpEgCZpkaXXyvmXYDAI1qCq1tA+m/e5ozWdm8zTGuyb"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12751,"candidatesTokenCount":28,"totalTokenCount":12829,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12751}],"thoughtsTokenCount":50}}]}

integration-tests/hooks-system.sequential-execution.responses

@@ -0,0 +1 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Seeking Task Clarity**\n\nI'm currently focused on identifying the precise task. My initial assessment indicates the user is seeking assistance, but the specific requirements remain undefined. I will directly solicit a detailed task description from the user to clarify this.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12604,"totalTokenCount":12633,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12604}],"thoughtsTokenCount":29}},{"candidates":[{"content":{"parts":[{"text":"Hello! I'm ready to help. Please describe the task you'd like me to assist you with.","thoughtSignature":"CiQBcsjafM2CL00L595T19DK8M8zP5p9/tbFPPwdM2S6669z2FgKYQFyyNp8Ya0YVCtft9Asr/45XOCfNdPWbwZt8SvIeX3IxYzOFcOK14+DnoDIuTIrmRQBeUvdxD59QmEWx+/OaSxj9564L0IU703C1JX20buEtYhkRM4LhK0G4LG/z6IJauEKSQFyyNp8n784BnEcDTQGfZ8/s3pl/TNaNzjQx0o8wYCYZH1qsRbVa3YJAvRGrVXL6y9ka10w0lhEsrQ8vOiw6ilZKirA5DjLz4U="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12604,"candidatesTokenCount":22,"totalTokenCount":12655,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12604}],"thoughtsTokenCount":29}}]}

integration-tests/hooks-system.session-clear.responses

@@ -0,0 +1 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Greeting the User**\n\nI've registered the user's greeting. I'm primed to respond with a friendly welcome and signal my availability to assist. My focus now is drafting a suitable response.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12761,"totalTokenCount":12787,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12761}],"thoughtsTokenCount":26}},{"candidates":[{"content":{"parts":[{"text":"Hello! I'm ready to help. What can I do for you?","thoughtSignature":"CikBcsjafBz/0rqJuIv9woxRvivjZyAqBjpoJhOTSPfcbMWCawTfcyKImQpxAXLI2nxyuBo6dqZmTxkH7XxPxjq7mNoacRa48wc/eT5caK/4tu0Y9fJ1ScpJZb+tCNzrqTNwVXa98ppjB2O/X4eejJN+hUr3LCalDFRdRLO17PFUI5qgYSbSgIGzhbnQASgzOArvvqzDPPgqXWVIDj8KMQFyyNp8ayfqBNRkBykRSTDtzOKVGkjLW1dXWamLB4ojeEVHSOgne4vlYaKs44pitsg="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12761,"candidatesTokenCount":15,"totalTokenCount":12802,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12761}],"thoughtsTokenCount":26}}]}

integration-tests/hooks-system.session-startup.responses

@@ -0,0 +1 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"**Initiating a Dialogue**\n\nI've successfully received and understood the user's initial request. My next move will be to output a simple \"Hello\" as a greeting, fulfilling the basic instruction I was given. This constitutes the first step in the interaction, and I'm ready to move forward based on the user's subsequent input.\n\n\n","thought":true}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12588,"totalTokenCount":12607,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12588}],"thoughtsTokenCount":19}},{"candidates":[{"content":{"parts":[{"text":"Hello","thoughtSignature":"CikBcsjafB9jXawgyqQ5mpEJ4ihpLD/B2i8GR75sod00ZF3TCbrLHS9YjgpeAXLI2nx1fmJO2VIiwBpF+vLBPhYE/B2992PVW6XM20cEYx4g0leDNs6BIhzEipm6RYOxzgz8KxH9+ZkCnd8bVZr59lbDCgqSCSB6IKA+csXHKsF9g3UMRAtoSBwiBw=="}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12588,"totalTokenCount":12607,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12588}],"thoughtsTokenCount":19}}]}

integration-tests/json-output.test.ts

@@ -22,11 +22,9 @@ describe('JSON output', () => {
   });
 
   it('should return a valid JSON with response and stats', async () => {
-    const result = await rig.run(
-      'What is the capital of France?',
-      '--output-format',
-      'json',
-    );
+    const result = await rig.run({
+      args: ['What is the capital of France?', '--output-format', 'json'],
+    });
     const parsed = JSON.parse(result);
 
     expect(parsed).toHaveProperty('response');
@@ -37,6 +35,17 @@ describe('JSON output', () => {
     expect(typeof parsed.stats).toBe('object');
   });
 
+  it('should return a valid JSON with a session ID', async () => {
+    const result = await rig.run({
+      args: ['Hello', '--output-format', 'json'],
+    });
+    const parsed = JSON.parse(result);
+
+    expect(parsed).toHaveProperty('session_id');
+    expect(typeof parsed.session_id).toBe('string');
+    expect(parsed.session_id).not.toBe('');
+  });
+
   it('should return a JSON error for sd auth mismatch before running', async () => {
     process.env['GOOGLE_GENAI_USE_GCA'] = 'true';
     await rig.setup('json-output-auth-mismatch', {
@@ -49,7 +58,7 @@ describe('JSON output', () => {
 
     let thrown: Error | undefined;
     try {
-      await rig.run('Hello', '--output-format', 'json');
+      await rig.run({ args: ['Hello', '--output-format', 'json'] });
       expect.fail('Expected process to exit with error');
     } catch (e) {
       thrown = e as Error;
@@ -87,6 +96,9 @@ describe('JSON output', () => {
       "enforced authentication type is 'gemini-api-key'",
     );
     expect(payload.error.message).toContain("current type is 'oauth-personal'");
+    expect(payload).toHaveProperty('session_id');
+    expect(typeof payload.session_id).toBe('string');
+    expect(payload.session_id).not.toBe('');
   });
 
   it('should not exit on tool errors and allow model to self-correct in JSON mode', async () => {
@@ -96,12 +108,14 @@ describe('JSON output', () => {
         'json-output.error.responses',
       ),
     });
-    const result = await rig.run(
-      `Read the contents of ${rig.testDir}/path/to/nonexistent/file.txt and tell me what it says. ` +
-        'On error, respond to the user with exactly the text "File not found".',
-      '--output-format',
-      'json',
-    );
+    const result = await rig.run({
+      args: [
+        `Read the contents of ${rig.testDir}/path/to/nonexistent/file.txt and tell me what it says. ` +
+          'On error, respond to the user with exactly the text "File not found".',
+        '--output-format',
+        'json',
+      ],
+    });
 
     const parsed = JSON.parse(result);
 
@@ -129,5 +143,9 @@ describe('JSON output', () => {
 
     // Should NOT have an error field at the top level
     expect(parsed.error).toBeUndefined();
+
+    expect(parsed).toHaveProperty('session_id');
+    expect(typeof parsed.session_id).toBe('string');
+    expect(parsed.session_id).not.toBe('');
   });
 });

integration-tests/list_directory.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it } from 'vitest';
+import { describe, it, beforeEach, afterEach } from 'vitest';
 import {
   TestRig,
   poll,
@@ -15,9 +15,18 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 describe('list_directory', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should be able to list a directory', async () => {
-    const rig = new TestRig();
-    rig.setup('should be able to list a directory');
+    await rig.setup('should be able to list a directory', {
+      settings: { tools: { core: ['list_directory'] } },
+    });
     rig.createFile('file1.txt', 'file 1 content');
     rig.mkdir('subdir');
     rig.sync();
@@ -36,7 +45,7 @@ describe('list_directory', () => {
 
     const prompt = `Can you list the files in the current directory.`;
 
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     try {
       await rig.expectToolCallSuccess(['list_directory']);

integration-tests/mcp_server_cyclic_schema.test.ts

@@ -23,7 +23,7 @@
 
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { beforeAll, describe, it } from 'vitest';
+import { describe, it, afterEach, beforeEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 
 // Create a minimal MCP server that doesn't require external dependencies
@@ -166,9 +166,15 @@ rpc.send({
 `;
 
 describe('mcp server with cyclic tool schema is detected', () => {
-  const rig = new TestRig();
+  let rig: TestRig;
 
-  beforeAll(async () => {
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
+  it('mcp tool list should include tool with cyclic tool schema', async () => {
     // Setup test directory with MCP server configuration
     await rig.setup('cyclic-schema-mcp-server', {
       settings: {
@@ -190,9 +196,7 @@ describe('mcp server with cyclic tool schema is detected', () => {
       const { chmodSync } = await import('node:fs');
       chmodSync(testServerPath, 0o755);
     }
-  });
 
-  it('mcp tool list should include tool with cyclic tool schema', async () => {
     const run = await rig.runInteractive();
 
     await run.type('/mcp list');

integration-tests/mixed-input-crash.test.ts

@@ -4,24 +4,29 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 
 describe('mixed input crash prevention', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should not crash when using mixed prompt inputs', async () => {
-    const rig = new TestRig();
     rig.setup('should not crash when using mixed prompt inputs');
 
     // Test: echo "say '1'." | gemini --prompt-interactive="say '2'." say '3'.
     const stdinContent = "say '1'.";
 
     try {
-      await rig.run(
-        { stdin: stdinContent },
-        '--prompt-interactive',
-        "say '2'.",
-        "say '3'.",
-      );
+      await rig.run({
+        args: ['--prompt-interactive', "say '2'.", "say '3'."],
+        stdin: stdinContent,
+      });
       throw new Error('Expected the command to fail, but it succeeded');
     } catch (error: unknown) {
       expect(error).toBeInstanceOf(Error);
@@ -40,15 +45,13 @@ describe('mixed input crash prevention', () => {
   });
 
   it('should provide clear error message for mixed input', async () => {
-    const rig = new TestRig();
     rig.setup('should provide clear error message for mixed input');
 
     try {
-      await rig.run(
-        { stdin: 'test input' },
-        '--prompt-interactive',
-        'test prompt',
-      );
+      await rig.run({
+        args: ['--prompt-interactive', 'test prompt'],
+        stdin: 'test input',
+      });
       throw new Error('Expected the command to fail, but it succeeded');
     } catch (error: unknown) {
       expect(error).toBeInstanceOf(Error);

integration-tests/read_many_files.test.ts

@@ -4,19 +4,28 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 
 describe('read_many_files', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it.skip('should be able to read multiple files', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to read multiple files');
+    await rig.setup('should be able to read multiple files', {
+      settings: { tools: { core: ['read_many_files', 'read_file'] } },
+    });
     rig.createFile('file1.txt', 'file 1 content');
     rig.createFile('file2.txt', 'file 2 content');
 
     const prompt = `Use the read_many_files tool to read the contents of file1.txt and file2.txt and then print the contents of each file.`;
 
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     // Check for either read_many_files or multiple read_file calls
     const allTools = rig.readToolLogs();
@@ -43,6 +52,5 @@ describe('read_many_files', () => {
 
     // Validate model output - will throw if no output
     validateModelOutput(result, null, 'Read many files test');
-    await rig.cleanup();
   });
 });

integration-tests/replace.test.ts

@@ -4,13 +4,21 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 
 describe('replace', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
   it('should be able to replace content in a file', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to replace content in a file');
+    await rig.setup('should be able to replace content in a file', {
+      settings: { tools: { core: ['replace', 'read_file'] } },
+    });
 
     const fileName = 'file_to_replace.txt';
     const originalContent = 'foo content';
@@ -18,7 +26,9 @@ describe('replace', () => {
 
     rig.createFile(fileName, originalContent);
 
-    await rig.run(`Replace 'foo' with 'bar' in the file 'file_to_replace.txt'`);
+    await rig.run({
+      args: `Replace 'foo' with 'bar' in the file 'file_to_replace.txt'`,
+    });
 
     const foundToolCall = await rig.waitForToolCall('replace');
     expect(foundToolCall, 'Expected to find a replace tool call').toBeTruthy();
@@ -27,9 +37,9 @@ describe('replace', () => {
   });
 
   it.skip('should handle $ literally when replacing text ending with $', async () => {
-    const rig = new TestRig();
     await rig.setup(
       'should handle $ literally when replacing text ending with $',
+      { settings: { tools: { core: ['replace', 'read_file'] } } },
     );
 
     const fileName = 'regex.yml';
@@ -38,9 +48,9 @@ describe('replace', () => {
 
     rig.createFile(fileName, originalContent);
 
-    await rig.run(
-      "Open regex.yml and append ' # updated' after the line containing ^[sv]d[a-z]$ without breaking the $ character.",
-    );
+    await rig.run({
+      args: "Open regex.yml and append ' # updated' after the line containing ^[sv]d[a-z]$ without breaking the $ character.",
+    });
 
     const foundToolCall = await rig.waitForToolCall('replace');
     expect(foundToolCall, 'Expected to find a replace tool call').toBeTruthy();
@@ -49,8 +59,9 @@ describe('replace', () => {
   });
 
   it.skip('should insert a multi-line block of text', async () => {
-    const rig = new TestRig();
-    await rig.setup('should insert a multi-line block of text');
+    await rig.setup('should insert a multi-line block of text', {
+      settings: { tools: { core: ['replace', 'read_file'] } },
+    });
     const fileName = 'insert_block.txt';
     const originalContent = 'Line A\n<INSERT_TEXT_HERE>\nLine C';
     const newBlock = 'First line\nSecond line\nThird line';
@@ -59,7 +70,7 @@ describe('replace', () => {
     rig.createFile(fileName, originalContent);
 
     const prompt = `In ${fileName}, replace "<INSERT_TEXT_HERE>" with:\n${newBlock}. Use unix style line endings.`;
-    await rig.run(prompt);
+    await rig.run({ args: prompt });
 
     const foundToolCall = await rig.waitForToolCall('replace');
     expect(foundToolCall, 'Expected to find a replace tool call').toBeTruthy();
@@ -68,8 +79,9 @@ describe('replace', () => {
   });
 
   it.skip('should delete a block of text', async () => {
-    const rig = new TestRig();
-    await rig.setup('should delete a block of text');
+    await rig.setup('should delete a block of text', {
+      settings: { tools: { core: ['replace', 'read_file'] } },
+    });
     const fileName = 'delete_block.txt';
     const blockToDelete =
       '## DELETE THIS ##\nThis is a block of text to delete.\n## END DELETE ##';
@@ -77,9 +89,9 @@ describe('replace', () => {
     const expectedContent = 'Hello\nWorld';
     rig.createFile(fileName, originalContent);
 
-    await rig.run(
-      `In ${fileName}, delete the entire block from "## DELETE THIS ##" to "## END DELETE ##" including the markers and the newline that follows it.`,
-    );
+    await rig.run({
+      args: `In ${fileName}, delete the entire block from "## DELETE THIS ##" to "## END DELETE ##" including the markers and the newline that follows it.`,
+    });
 
     const foundToolCall = await rig.waitForToolCall('replace');
     expect(foundToolCall, 'Expected to find a replace tool call').toBeTruthy();

integration-tests/run_shell_command.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 import { getShellConfiguration } from '../packages/core/src/utils/shell-utils.js';
 
@@ -84,13 +84,21 @@ function getChainedEchoCommand(): { allowPattern: string; command: string } {
 }
 
 describe('run_shell_command', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
   it('should be able to run a shell command', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to run a shell command');
+    await rig.setup('should be able to run a shell command', {
+      settings: { tools: { core: ['run_shell_command'] } },
+    });
 
     const prompt = `Please run the command "echo hello-world" and show me the output`;
 
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     const foundToolCall = await rig.waitForToolCall('run_shell_command');
 
@@ -117,8 +125,9 @@ describe('run_shell_command', () => {
   });
 
   it('should be able to run a shell command via stdin', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to run a shell command via stdin');
+    await rig.setup('should be able to run a shell command via stdin', {
+      settings: { tools: { core: ['run_shell_command'] } },
+    });
 
     const prompt = `Please run the command "echo test-stdin" and show me what it outputs`;
 
@@ -145,7 +154,6 @@ describe('run_shell_command', () => {
   });
 
   it.skip('should run allowed sub-command in non-interactive mode', async () => {
-    const rig = new TestRig();
     await rig.setup('should run allowed sub-command in non-interactive mode');
 
     const testFile = rig.createFile('test.txt', 'Lorem\nIpsum\nDolor\n');
@@ -153,13 +161,11 @@ describe('run_shell_command', () => {
     const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
     // Provide the prompt via stdin to simulate non-interactive mode
-    const result = await rig.run(
-      {
-        stdin: prompt,
-        yolo: false,
-      },
-      `--allowed-tools=run_shell_command(${tool})`,
-    );
+    const result = await rig.run({
+      args: [`--allowed-tools=run_shell_command(${tool})`],
+      stdin: prompt,
+      yolo: false,
+    });
 
     const foundToolCall = await rig.waitForToolCall('run_shell_command', 15000);
 
@@ -192,20 +198,17 @@ describe('run_shell_command', () => {
   });
 
   it.skip('should succeed with no parens in non-interactive mode', async () => {
-    const rig = new TestRig();
     await rig.setup('should succeed with no parens in non-interactive mode');
 
     const testFile = rig.createFile('test.txt', 'Lorem\nIpsum\nDolor\n');
     const { command } = getLineCountCommand();
     const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
-    const result = await rig.run(
-      {
-        stdin: prompt,
-        yolo: false,
-      },
-      '--allowed-tools=run_shell_command',
-    );
+    const result = await rig.run({
+      args: '--allowed-tools=run_shell_command',
+      stdin: prompt,
+      yolo: false,
+    });
 
     const foundToolCall = await rig.waitForToolCall('run_shell_command', 15000);
 
@@ -229,15 +232,16 @@ describe('run_shell_command', () => {
   });
 
   it('should succeed with --yolo mode', async () => {
-    const rig = new TestRig();
-    await rig.setup('should succeed with --yolo mode');
+    await rig.setup('should succeed with --yolo mode', {
+      settings: { tools: { core: ['run_shell_command'] } },
+    });
 
     const testFile = rig.createFile('test.txt', 'Lorem\nIpsum\nDolor\n');
     const { command } = getLineCountCommand();
     const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
     const result = await rig.run({
-      prompt: prompt,
+      args: prompt,
       yolo: true,
     });
 
@@ -263,20 +267,17 @@ describe('run_shell_command', () => {
   });
 
   it.skip('should work with ShellTool alias', async () => {
-    const rig = new TestRig();
     await rig.setup('should work with ShellTool alias');
 
     const testFile = rig.createFile('test.txt', 'Lorem\nIpsum\nDolor\n');
     const { tool, command } = getLineCountCommand();
     const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
-    const result = await rig.run(
-      {
-        stdin: prompt,
-        yolo: false,
-      },
-      `--allowed-tools=ShellTool(${tool})`,
-    );
+    const result = await rig.run({
+      args: `--allowed-tools=ShellTool(${tool})`,
+      stdin: prompt,
+      yolo: false,
+    });
 
     const foundToolCall = await rig.waitForToolCall('run_shell_command', 15000);
 
@@ -311,7 +312,6 @@ describe('run_shell_command', () => {
   // TODO(#11062): Un-skip this once we can make it reliable by using hard coded
   // model responses.
   it.skip('should combine multiple --allowed-tools flags', async () => {
-    const rig = new TestRig();
     await rig.setup('should combine multiple --allowed-tools flags');
 
     const { tool, command } = getLineCountCommand();
@@ -319,14 +319,14 @@ describe('run_shell_command', () => {
       `use both ${command} and ls to count the number of lines in files in this ` +
       `directory. Do not pipe these commands into each other, run them separately.`;
 
-    const result = await rig.run(
-      {
-        stdin: prompt,
-        yolo: false,
-      },
-      `--allowed-tools=run_shell_command(${tool})`,
-      '--allowed-tools=run_shell_command(ls)',
-    );
+    const result = await rig.run({
+      args: [
+        `--allowed-tools=run_shell_command(${tool})`,
+        '--allowed-tools=run_shell_command(ls)',
+      ],
+      stdin: prompt,
+      yolo: false,
+    });
 
     for (const expected in ['ls', tool]) {
       const foundToolCall = await rig.waitForToolCall(
@@ -361,8 +361,9 @@ describe('run_shell_command', () => {
   });
 
   it('should reject commands not on the allowlist', async () => {
-    const rig = new TestRig();
-    await rig.setup('should reject commands not on the allowlist');
+    await rig.setup('should reject commands not on the allowlist', {
+      settings: { tools: { core: ['run_shell_command'] } },
+    });
 
     const testFile = rig.createFile('test.txt', 'Disallowed command check\n');
     const allowedCommand = getAllowedListCommand();
@@ -373,13 +374,11 @@ describe('run_shell_command', () => {
       `If the command fails because it is not permitted, respond with the single word FAIL. ` +
       `If it succeeds, respond with SUCCESS.`;
 
-    const result = await rig.run(
-      {
-        stdin: prompt,
-        yolo: false,
-      },
-      `--allowed-tools=run_shell_command(${allowedCommand})`,
-    );
+    const result = await rig.run({
+      args: `--allowed-tools=run_shell_command(${allowedCommand})`,
+      stdin: prompt,
+      yolo: false,
+    });
 
     if (!result.toLowerCase().includes('fail')) {
       printDebugInfo(rig, result, {
@@ -429,7 +428,6 @@ describe('run_shell_command', () => {
 
   // TODO(#11966): Deflake this test and re-enable once the underlying race is resolved.
   it.skip('should reject chained commands when only the first segment is allowlisted in non-interactive mode', async () => {
-    const rig = new TestRig();
     await rig.setup(
       'should reject chained commands when only the first segment is allowlisted',
     );
@@ -437,13 +435,11 @@ describe('run_shell_command', () => {
     const chained = getChainedEchoCommand();
     const shellInjection = `!{${chained.command}}`;
 
-    await rig.run(
-      {
-        stdin: `${shellInjection}\n`,
-        yolo: false,
-      },
-      `--allowed-tools=ShellTool(${chained.allowPattern})`,
-    );
+    await rig.run({
+      args: `--allowed-tools=ShellTool(${chained.allowPattern})`,
+      stdin: `${shellInjection}\n`,
+      yolo: false,
+    });
 
     // CLI should refuse to execute the chained command without scheduling run_shell_command.
     const toolLogs = rig
@@ -458,22 +454,24 @@ describe('run_shell_command', () => {
   });
 
   it('should allow all with "ShellTool" and other specific tools', async () => {
-    const rig = new TestRig();
     await rig.setup(
       'should allow all with "ShellTool" and other specific tools',
+      {
+        settings: { tools: { core: ['run_shell_command'] } },
+      },
     );
 
     const { tool } = getLineCountCommand();
     const prompt = `Please run the command "echo test-allow-all" and show me the output`;
 
-    const result = await rig.run(
-      {
-        stdin: prompt,
-        yolo: false,
-      },
-      `--allowed-tools=run_shell_command(${tool})`,
-      '--allowed-tools=run_shell_command',
-    );
+    const result = await rig.run({
+      args: [
+        `--allowed-tools=run_shell_command(${tool})`,
+        '--allowed-tools=run_shell_command',
+      ],
+      stdin: prompt,
+      yolo: false,
+    });
 
     const foundToolCall = await rig.waitForToolCall('run_shell_command', 15000);
 
@@ -505,8 +503,9 @@ describe('run_shell_command', () => {
   });
 
   it('should propagate environment variables to the child process', async () => {
-    const rig = new TestRig();
-    await rig.setup('should propagate environment variables');
+    await rig.setup('should propagate environment variables', {
+      settings: { tools: { core: ['run_shell_command'] } },
+    });
 
     const varName = 'GEMINI_CLI_TEST_VAR';
     const varValue = `test-value-${Math.random().toString(36).substring(7)}`;
@@ -514,7 +513,7 @@ describe('run_shell_command', () => {
 
     try {
       const prompt = `Use echo to learn the value of the environment variable named ${varName} and tell me what it is.`;
-      const result = await rig.run(prompt);
+      const result = await rig.run({ args: prompt });
 
       const foundToolCall = await rig.waitForToolCall('run_shell_command');
 
@@ -537,13 +536,12 @@ describe('run_shell_command', () => {
   });
 
   it.skip('should run a platform-specific file listing command', async () => {
-    const rig = new TestRig();
     await rig.setup('should run platform-specific file listing');
     const fileName = `test-file-${Math.random().toString(36).substring(7)}.txt`;
     rig.createFile(fileName, 'test content');
 
     const prompt = `Run a shell command to list the files in the current directory and tell me what they are.`;
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     const foundToolCall = await rig.waitForToolCall('run_shell_command');
 
@@ -565,12 +563,13 @@ describe('run_shell_command', () => {
   });
 
   it('rejects invalid shell expressions', async () => {
-    const rig = new TestRig();
-    await rig.setup('rejects invalid shell expressions');
+    await rig.setup('rejects invalid shell expressions', {
+      settings: { tools: { core: ['run_shell_command'] } },
+    });
     const invalidCommand = getInvalidCommand();
-    const result = await rig.run(
-      `I am testing the error handling of the run_shell_command tool. Please attempt to run the following command, which I know has invalid syntax: \`${invalidCommand}\`. If the command fails as expected, please return the word FAIL, otherwise return the word SUCCESS.`,
-    );
+    const result = await rig.run({
+      args: `I am testing the error handling of the run_shell_command tool. Please attempt to run the following command, which I know has invalid syntax: \`${invalidCommand}\`. If the command fails as expected, please return the word FAIL, otherwise return the word SUCCESS.`,
+    });
     expect(result).toContain('FAIL');
 
     const escapedInvalidCommand = JSON.stringify(invalidCommand).slice(1, -1);

integration-tests/save_memory.test.ts

@@ -4,18 +4,27 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 
 describe('save_memory', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should be able to save to memory', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to save to memory');
+    await rig.setup('should be able to save to memory', {
+      settings: { tools: { core: ['save_memory'] } },
+    });
 
     const prompt = `remember that my favorite color is  blue.
 
   what is my favorite color? tell me that and surround it with $ symbol`;
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     const foundToolCall = await rig.waitForToolCall('save_memory');
 

integration-tests/simple-mcp-server.test.ts

@@ -10,7 +10,7 @@
  * external dependencies, making it compatible with Docker sandbox mode.
  */
 
-import { describe, it, beforeAll, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig, poll, validateModelOutput } from './test-helper.js';
 import { join } from 'node:path';
 import { writeFileSync } from 'node:fs';
@@ -165,9 +165,15 @@ rpc.send({
 `;
 
 describe('simple-mcp-server', () => {
-  const rig = new TestRig();
+  let rig: TestRig;
 
-  beforeAll(async () => {
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
+  it('should add two numbers', async () => {
     // Setup test directory with MCP server configuration
     await rig.setup('simple-mcp-server', {
       settings: {
@@ -177,6 +183,7 @@ describe('simple-mcp-server', () => {
             args: ['mcp-server.cjs'],
           },
         },
+        tools: { core: [] },
       },
     });
 
@@ -208,14 +215,12 @@ describe('simple-mcp-server', () => {
     if (!isReady) {
       throw new Error('MCP server script was not ready in time.');
     }
-  });
 
-  it('should add two numbers', async () => {
     // Test directory is already set up in before hook
     // Just run the command - MCP server config is in settings.json
-    const output = await rig.run(
-      'Use the `add` tool to calculate 5+10 and output only the resulting number.',
-    );
+    const output = await rig.run({
+      args: 'Use the `add` tool to calculate 5+10 and output only the resulting number.',
+    });
 
     const foundToolCall = await rig.waitForToolCall('add');
 

integration-tests/stdin-context.test.ts

@@ -4,19 +4,26 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 
 describe.skip('stdin context', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should be able to use stdin as context for a prompt', async () => {
-    const rig = new TestRig();
     await rig.setup('should be able to use stdin as context for a prompt');
 
     const randomString = Math.random().toString(36).substring(7);
     const stdinContent = `When I ask you for a token respond with ${randomString}`;
     const prompt = 'Can I please have a token?';
 
-    const result = await rig.run({ prompt, stdin: stdinContent });
+    const result = await rig.run({ args: prompt, stdin: stdinContent });
 
     await rig.waitForTelemetryEvent('api_request');
     const lastRequest = rig.readLastApiRequest();
@@ -75,7 +82,6 @@ describe.skip('stdin context', () => {
       even though gemini is intended to run interactively.
     */
 
-    const rig = new TestRig();
     await rig.setup('should exit quickly if stdin stream does not end');
 
     try {

integration-tests/telemetry.test.ts

@@ -4,16 +4,23 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 
 describe('telemetry', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should emit a metric and a log event', async () => {
-    const rig = new TestRig();
     rig.setup('should emit a metric and a log event');
 
     // Run a simple command that should trigger telemetry
-    await rig.run('just saying hi');
+    await rig.run({ args: 'just saying hi' });
 
     // Verify that a user_prompt event was logged
     const hasUserPromptEvent = await rig.waitForTelemetryEvent('user_prompt');

integration-tests/test-helper.ts

@@ -18,6 +18,7 @@ import * as os from 'node:os';
 import { GEMINI_DIR } from '../packages/core/src/utils/paths.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATH = join(__dirname, '..', 'bundle/gemini.js');
 
 // Get timeout based on environment
 function getDefaultTimeout() {
@@ -195,17 +196,12 @@ export class InteractiveRun {
     if (!timeout) {
       timeout = getDefaultTimeout();
     }
-    const found = await poll(
+    await poll(
       () => stripAnsi(this.output).toLowerCase().includes(text.toLowerCase()),
       timeout,
       200,
     );
-    expect(
-      found,
-      `Did not find expected text: "${text}". Output was:\n${stripAnsi(
-        this.output,
-      )}`,
-    ).toBe(true);
+    expect(stripAnsi(this.output).toLowerCase()).toContain(text.toLowerCase());
   }
 
   // This types slowly to make sure command is correct, but only work for short
@@ -271,19 +267,14 @@ export class InteractiveRun {
 }
 
 export class TestRig {
-  bundlePath: string;
-  testDir: string | null;
+  testDir: string | null = null;
   testName?: string;
   _lastRunStdout?: string;
   // Path to the copied fake responses file for this test.
   fakeResponsesPath?: string;
   // Original fake responses file path for rewriting goldens in record mode.
   originalFakeResponsesPath?: string;
-
-  constructor() {
-    this.bundlePath = join(__dirname, '..', 'bundle/gemini.js');
-    this.testDir = null;
-  }
+  private _interactiveRuns: InteractiveRun[] = [];
 
   setup(
     testName: string,
@@ -374,7 +365,7 @@ export class TestRig {
     const command = isNpmReleaseTest ? 'gemini' : 'node';
     const initialArgs = isNpmReleaseTest
       ? extraInitialArgs
-      : [this.bundlePath, ...extraInitialArgs];
+      : [BUNDLE_PATH, ...extraInitialArgs];
     if (this.fakeResponsesPath) {
       if (process.env['REGENERATE_MODEL_GOLDENS'] === 'true') {
         initialArgs.push('--record-responses', this.fakeResponsesPath);
@@ -385,19 +376,13 @@ export class TestRig {
     return { command, initialArgs };
   }
 
-  run(
-    promptOrOptions:
-      | string
-      | {
-          prompt?: string;
-          stdin?: string;
-          stdinDoesNotEnd?: boolean;
-          yolo?: boolean;
-        },
-    ...args: string[]
-  ): Promise<string> {
-    const yolo =
-      typeof promptOrOptions === 'string' || promptOrOptions.yolo !== false;
+  run(options: {
+    args?: string | string[];
+    stdin?: string;
+    stdinDoesNotEnd?: boolean;
+    yolo?: boolean;
+  }): Promise<string> {
+    const yolo = options.yolo !== false;
     const { command, initialArgs } = this._getCommandAndArgs(
       yolo ? ['--yolo'] : [],
     );
@@ -411,21 +396,17 @@ export class TestRig {
       encoding: 'utf-8',
     };
 
-    if (typeof promptOrOptions === 'string') {
-      commandArgs.push(promptOrOptions);
-    } else if (
-      typeof promptOrOptions === 'object' &&
-      promptOrOptions !== null
-    ) {
-      if (promptOrOptions.prompt) {
-        commandArgs.push(promptOrOptions.prompt);
-      }
-      if (promptOrOptions.stdin) {
-        execOptions.input = promptOrOptions.stdin;
+    if (options.args) {
+      if (Array.isArray(options.args)) {
+        commandArgs.push(...options.args);
+      } else {
+        commandArgs.push(options.args);
       }
     }
 
-    commandArgs.push(...args);
+    if (options.stdin) {
+      execOptions.input = options.stdin;
+    }
 
     const child = spawn(command, commandArgs, {
       cwd: this.testDir!,
@@ -441,10 +422,7 @@ export class TestRig {
       child.stdin!.write(execOptions.input);
     }
 
-    if (
-      typeof promptOrOptions === 'object' &&
-      !promptOrOptions.stdinDoesNotEnd
-    ) {
+    if (!options.stdinDoesNotEnd) {
       child.stdin!.end();
     }
 
@@ -591,6 +569,18 @@ export class TestRig {
   }
 
   async cleanup() {
+    // Kill any interactive runs that are still active
+    for (const run of this._interactiveRuns) {
+      try {
+        await run.kill();
+      } catch (error) {
+        if (env['VERBOSE'] === 'true') {
+          console.warn('Failed to kill interactive run during cleanup:', error);
+        }
+      }
+    }
+    this._interactiveRuns = [];
+
     if (
       process.env['REGENERATE_MODEL_GOLDENS'] === 'true' &&
       this.fakeResponsesPath
@@ -1024,11 +1014,25 @@ export class TestRig {
     return null;
   }
 
-  async runInteractive(...args: string[]): Promise<InteractiveRun> {
-    const { command, initialArgs } = this._getCommandAndArgs(['--yolo']);
-    const commandArgs = [...initialArgs, ...args];
+  async runInteractive(options?: {
+    args?: string | string[];
+    yolo?: boolean;
+  }): Promise<InteractiveRun> {
+    const yolo = options?.yolo !== false;
+    const { command, initialArgs } = this._getCommandAndArgs(
+      yolo ? ['--yolo'] : [],
+    );
+    const commandArgs = [...initialArgs];
 
-    const options: pty.IPtyForkOptions = {
+    if (options?.args) {
+      if (Array.isArray(options.args)) {
+        commandArgs.push(...options.args);
+      } else {
+        commandArgs.push(options.args);
+      }
+    }
+
+    const ptyOptions: pty.IPtyForkOptions = {
       name: 'xterm-color',
       cols: 80,
       rows: 80,
@@ -1039,9 +1043,10 @@ export class TestRig {
     };
 
     const executable = command === 'node' ? process.execPath : command;
-    const ptyProcess = pty.spawn(executable, commandArgs, options);
+    const ptyProcess = pty.spawn(executable, commandArgs, ptyOptions);
 
     const run = new InteractiveRun(ptyProcess);
+    this._interactiveRuns.push(run);
     // Wait for the app to be ready
     await run.expectText('  Type your message or @path/to/file', 30000);
     return run;

integration-tests/utf-bom-encoding.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { writeFileSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { TestRig } from './test-helper.js';
@@ -47,28 +47,26 @@ const utf32BE = (s: string) => {
   return Buffer.concat([bom, payload]);
 };
 
-let rig: TestRig;
-let dir: string;
-
 describe('BOM end-to-end integraion', () => {
-  beforeAll(async () => {
+  let rig: TestRig;
+
+  beforeEach(async () => {
     rig = new TestRig();
-    await rig.setup('bom-integration');
-    dir = rig.testDir!;
+    await rig.setup('bom-integration', {
+      settings: { tools: { core: ['read_file'] } },
+    });
   });
 
-  afterAll(async () => {
-    await rig.cleanup();
-  });
+  afterEach(async () => await rig.cleanup());
 
   async function runAndAssert(
     filename: string,
     content: Buffer,
     expectedText: string | null,
   ) {
-    writeFileSync(join(dir, filename), content);
+    writeFileSync(join(rig.testDir!, filename), content);
     const prompt = `read the file ${filename} and output its exact contents`;
-    const output = await rig.run(prompt);
+    const output = await rig.run({ args: prompt });
     await rig.waitForToolCall('read_file');
     const lower = output.toLowerCase();
     if (expectedText === null) {
@@ -126,9 +124,9 @@ describe('BOM end-to-end integraion', () => {
     );
     const imageContent = readFileSync(imagePath);
     const filename = 'gemini-screenshot.png';
-    writeFileSync(join(dir, filename), imageContent);
+    writeFileSync(join(rig.testDir!, filename), imageContent);
     const prompt = `What is shown in the image ${filename}?`;
-    const output = await rig.run(prompt);
+    const output = await rig.run({ args: prompt });
     await rig.waitForToolCall('read_file');
     const lower = output.toLowerCase();
     // The response is non-deterministic, so we just check for some

integration-tests/write_file.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   TestRig,
   createToolCallErrorMessage,
@@ -13,12 +13,21 @@ import {
 } from './test-helper.js';
 
 describe('write_file', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
   it('should be able to write a file', async () => {
-    const rig = new TestRig();
-    await rig.setup('should be able to write a file');
+    await rig.setup('should be able to write a file', {
+      settings: { tools: { core: ['write_file', 'read_file'] } },
+    });
     const prompt = `show me an example of using the write tool. put a dad joke in dad.txt`;
 
-    const result = await rig.run(prompt);
+    const result = await rig.run({ args: prompt });
 
     const foundToolCall = await rig.waitForToolCall('write_file');
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.20.0-nightly.20251201.2fe609cb6",
+  "version": "0.22.0-preview.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@google/gemini-cli",
-      "version": "0.20.0-nightly.20251201.2fe609cb6",
+      "version": "0.22.0-preview.1",
       "workspaces": [
         "packages/*"
       ],
@@ -2112,23 +2112,27 @@
       }
     },
     "node_modules/@modelcontextprotocol/sdk/node_modules/body-parser": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.0.tgz",
-      "integrity": "sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==",
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.1.tgz",
+      "integrity": "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw==",
       "license": "MIT",
       "dependencies": {
         "bytes": "^3.1.2",
         "content-type": "^1.0.5",
-        "debug": "^4.4.0",
+        "debug": "^4.4.3",
         "http-errors": "^2.0.0",
-        "iconv-lite": "^0.6.3",
+        "iconv-lite": "^0.7.0",
         "on-finished": "^2.4.1",
         "qs": "^6.14.0",
-        "raw-body": "^3.0.0",
-        "type-is": "^2.0.0"
+        "raw-body": "^3.0.1",
+        "type-is": "^2.0.1"
       },
       "engines": {
         "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/@modelcontextprotocol/sdk/node_modules/content-disposition": {
@@ -2220,6 +2224,22 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/@modelcontextprotocol/sdk/node_modules/iconv-lite": {
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.0.tgz",
+      "integrity": "sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
     "node_modules/@modelcontextprotocol/sdk/node_modules/json-schema-traverse": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -5750,9 +5770,9 @@
       }
     },
     "node_modules/archiver-utils/node_modules/glob": {
-      "version": "10.4.5",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-10.4.5.tgz",
-      "integrity": "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -10199,6 +10219,7 @@
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
       "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "safer-buffer": ">= 2.1.2 < 3.0.0"
@@ -13893,18 +13914,54 @@
       }
     },
     "node_modules/raw-body": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.0.tgz",
-      "integrity": "sha512-RmkhL8CAyCRPXCE28MMH0z2PNWQBNk2Q09ZdxM9IOOXwxwZbN+qbWaatPkdkWIKL2ZVDImrN/pK5HTRz2PcS4g==",
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
+      "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
       "license": "MIT",
       "dependencies": {
-        "bytes": "3.1.2",
-        "http-errors": "2.0.0",
-        "iconv-lite": "0.6.3",
-        "unpipe": "1.0.0"
+        "bytes": "~3.1.2",
+        "http-errors": "~2.0.1",
+        "iconv-lite": "~0.7.0",
+        "unpipe": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/raw-body/node_modules/http-errors": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
+      "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
+      "license": "MIT",
+      "dependencies": {
+        "depd": "~2.0.0",
+        "inherits": "~2.0.4",
+        "setprototypeof": "~1.2.0",
+        "statuses": "~2.0.2",
+        "toidentifier": "~1.0.1"
       },
       "engines": {
         "node": ">= 0.8"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/raw-body/node_modules/iconv-lite": {
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.0.tgz",
+      "integrity": "sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/rc": {
@@ -16004,9 +16061,9 @@
       }
     },
     "node_modules/test-exclude/node_modules/glob": {
-      "version": "10.4.5",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-10.4.5.tgz",
-      "integrity": "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -17614,7 +17671,7 @@
     },
     "packages/a2a-server": {
       "name": "@google/gemini-cli-a2a-server",
-      "version": "0.20.0-nightly.20251201.2fe609cb6",
+      "version": "0.22.0-preview.1",
       "dependencies": {
         "@a2a-js/sdk": "^0.3.2",
         "@google-cloud/storage": "^7.16.0",
@@ -17656,23 +17713,27 @@
       }
     },
     "packages/a2a-server/node_modules/body-parser": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.0.tgz",
-      "integrity": "sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==",
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.1.tgz",
+      "integrity": "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw==",
       "license": "MIT",
       "dependencies": {
         "bytes": "^3.1.2",
         "content-type": "^1.0.5",
-        "debug": "^4.4.0",
+        "debug": "^4.4.3",
         "http-errors": "^2.0.0",
-        "iconv-lite": "^0.6.3",
+        "iconv-lite": "^0.7.0",
         "on-finished": "^2.4.1",
         "qs": "^6.14.0",
-        "raw-body": "^3.0.0",
-        "type-is": "^2.0.0"
+        "raw-body": "^3.0.1",
+        "type-is": "^2.0.1"
       },
       "engines": {
         "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "packages/a2a-server/node_modules/content-disposition": {
@@ -17777,6 +17838,22 @@
         "node": ">= 0.8"
       }
     },
+    "packages/a2a-server/node_modules/iconv-lite": {
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.0.tgz",
+      "integrity": "sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
     "packages/a2a-server/node_modules/media-typer": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
@@ -17904,7 +17981,8 @@
     },
     "packages/cli": {
       "name": "@google/gemini-cli",
-      "version": "0.20.0-nightly.20251201.2fe609cb6",
+      "version": "0.22.0-preview.1",
+      "license": "Apache-2.0",
       "dependencies": {
         "@google/gemini-cli-core": "file:../core",
         "@google/genai": "1.30.0",
@@ -18005,7 +18083,8 @@
     },
     "packages/core": {
       "name": "@google/gemini-cli-core",
-      "version": "0.20.0-nightly.20251201.2fe609cb6",
+      "version": "0.22.0-preview.1",
+      "license": "Apache-2.0",
       "dependencies": {
         "@google-cloud/logging": "^11.2.1",
         "@google-cloud/opentelemetry-cloud-monitoring-exporter": "^0.21.0",
@@ -18149,7 +18228,7 @@
     },
     "packages/test-utils": {
       "name": "@google/gemini-cli-test-utils",
-      "version": "0.20.0-nightly.20251201.2fe609cb6",
+      "version": "0.22.0-preview.1",
       "license": "Apache-2.0",
       "devDependencies": {
         "typescript": "^5.3.3"
@@ -18160,7 +18239,7 @@
     },
     "packages/vscode-ide-companion": {
       "name": "gemini-cli-vscode-ide-companion",
-      "version": "0.20.0-nightly.20251201.2fe609cb6",
+      "version": "0.22.0-preview.1",
       "license": "LICENSE",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.23.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.20.0-nightly.20251201.2fe609cb6",
+  "version": "0.22.0-preview.1",
   "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.20.0-nightly.20251201.2fe609cb6"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.22.0-preview.1"
   },
   "scripts": {
     "start": "cross-env NODE_ENV=development node scripts/start.js",

packages/a2a-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli-a2a-server",
-  "version": "0.20.0-nightly.20251201.2fe609cb6",
+  "version": "0.22.0-preview.1",
   "description": "Gemini CLI A2A Server",
   "repository": {
     "type": "git",

packages/a2a-server/src/agent/executor.ts

@@ -12,11 +12,7 @@ import type {
   RequestContext,
   ExecutionEventBus,
 } from '@a2a-js/sdk/server';
-import type {
-  ToolCallRequestInfo,
-  ServerGeminiToolCallRequestEvent,
-  Config,
-} from '@google/gemini-cli-core';
+import type { ToolCallRequestInfo, Config } from '@google/gemini-cli-core';
 import {
   GeminiEventType,
   SimpleExtensionLoader,
@@ -127,6 +123,7 @@ export class CoderAgentExecutor implements AgentExecutor {
       contextId,
       config,
       eventBus,
+      agentSettings.autoExecute,
     );
     runtimeTask.taskState = persistedState._taskState;
     await runtimeTask.geminiClient.initialize();
@@ -145,7 +142,13 @@ export class CoderAgentExecutor implements AgentExecutor {
   ): Promise<TaskWrapper> {
     const agentSettings = agentSettingsInput || ({} as AgentSettings);
     const config = await this.getConfig(agentSettings, taskId);
-    const runtimeTask = await Task.create(taskId, contextId, config, eventBus);
+    const runtimeTask = await Task.create(
+      taskId,
+      contextId,
+      config,
+      eventBus,
+      agentSettings.autoExecute,
+    );
     await runtimeTask.geminiClient.initialize();
 
     const wrapper = new TaskWrapper(runtimeTask, agentSettings);
@@ -280,8 +283,8 @@ export class CoderAgentExecutor implements AgentExecutor {
     requestContext: RequestContext,
     eventBus: ExecutionEventBus,
   ): Promise<void> {
-    const userMessage = requestContext.userMessage as Message;
-    const sdkTask = requestContext.task as SDKTask | undefined;
+    const userMessage = requestContext.userMessage;
+    const sdkTask = requestContext.task;
 
     const taskId = sdkTask?.id || userMessage.taskId || uuidv4();
     const contextId: string =
@@ -397,6 +400,7 @@ export class CoderAgentExecutor implements AgentExecutor {
           `[CoderAgentExecutor] Error creating task ${taskId}:`,
           error,
         );
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
         pushTaskStateFailed(error, eventBus, taskId, contextId);
         return;
       }
@@ -477,9 +481,7 @@ export class CoderAgentExecutor implements AgentExecutor {
             throw new Error('Execution aborted');
           }
           if (event.type === GeminiEventType.ToolCallRequest) {
-            toolCallRequests.push(
-              (event as ServerGeminiToolCallRequestEvent).value,
-            );
+            toolCallRequests.push(event.value);
             continue;
           }
           await currentTask.acceptAgentMessage(event);

packages/a2a-server/src/agent/task.test.ts

@@ -18,12 +18,27 @@ import {
   GeminiEventType,
   type Config,
   type ToolCallRequestInfo,
+  type GitService,
+  type CompletedToolCall,
+  ApprovalMode,
+  ToolConfirmationOutcome,
 } from '@google/gemini-cli-core';
 import { createMockConfig } from '../utils/testing_utils.js';
-import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import type { ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
 import { CoderAgentEvent } from '../types.js';
 import type { ToolCall } from '@google/gemini-cli-core';
 
+const mockProcessRestorableToolCalls = vi.hoisted(() => vi.fn());
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...original,
+    processRestorableToolCalls: mockProcessRestorableToolCalls,
+  };
+});
+
 describe('Task', () => {
   it('scheduleToolCalls should not modify the input requests array', async () => {
     const mockConfig = createMockConfig();
@@ -71,6 +86,141 @@ describe('Task', () => {
     expect(requests).toEqual(originalRequests);
   });
 
+  describe('scheduleToolCalls', () => {
+    const mockConfig = createMockConfig();
+    const mockEventBus: ExecutionEventBus = {
+      publish: vi.fn(),
+      on: vi.fn(),
+      off: vi.fn(),
+      once: vi.fn(),
+      removeAllListeners: vi.fn(),
+      finished: vi.fn(),
+    };
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('should not create a checkpoint if no restorable tools are called', async () => {
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+      const requests: ToolCallRequestInfo[] = [
+        {
+          callId: '1',
+          name: 'run_shell_command',
+          args: { command: 'ls' },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-1',
+        },
+      ];
+      const abortController = new AbortController();
+      await task.scheduleToolCalls(requests, abortController.signal);
+      expect(mockProcessRestorableToolCalls).not.toHaveBeenCalled();
+    });
+
+    it('should create a checkpoint if a restorable tool is called', async () => {
+      const mockConfig = createMockConfig({
+        getCheckpointingEnabled: () => true,
+        getGitService: () => Promise.resolve({} as GitService),
+      });
+      mockProcessRestorableToolCalls.mockResolvedValue({
+        checkpointsToWrite: new Map([['test.json', 'test content']]),
+        toolCallToCheckpointMap: new Map(),
+        errors: [],
+      });
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+      const requests: ToolCallRequestInfo[] = [
+        {
+          callId: '1',
+          name: 'replace',
+          args: {
+            file_path: 'test.txt',
+            old_string: 'old',
+            new_string: 'new',
+          },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-1',
+        },
+      ];
+      const abortController = new AbortController();
+      await task.scheduleToolCalls(requests, abortController.signal);
+      expect(mockProcessRestorableToolCalls).toHaveBeenCalledOnce();
+    });
+
+    it('should process all restorable tools for checkpointing in a single batch', async () => {
+      const mockConfig = createMockConfig({
+        getCheckpointingEnabled: () => true,
+        getGitService: () => Promise.resolve({} as GitService),
+      });
+      mockProcessRestorableToolCalls.mockResolvedValue({
+        checkpointsToWrite: new Map([
+          ['test1.json', 'test content 1'],
+          ['test2.json', 'test content 2'],
+        ]),
+        toolCallToCheckpointMap: new Map([
+          ['1', 'test1'],
+          ['2', 'test2'],
+        ]),
+        errors: [],
+      });
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+      const requests: ToolCallRequestInfo[] = [
+        {
+          callId: '1',
+          name: 'replace',
+          args: {
+            file_path: 'test.txt',
+            old_string: 'old',
+            new_string: 'new',
+          },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-1',
+        },
+        {
+          callId: '2',
+          name: 'write_file',
+          args: { file_path: 'test2.txt', content: 'new content' },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-2',
+        },
+        {
+          callId: '3',
+          name: 'not_restorable',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-3',
+        },
+      ];
+      const abortController = new AbortController();
+      await task.scheduleToolCalls(requests, abortController.signal);
+      expect(mockProcessRestorableToolCalls).toHaveBeenCalledExactlyOnceWith(
+        [
+          expect.objectContaining({ callId: '1' }),
+          expect.objectContaining({ callId: '2' }),
+        ],
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+  });
+
   describe('acceptAgentMessage', () => {
     it('should set currentTraceId when event has traceId', async () => {
       const mockConfig = createMockConfig();
@@ -205,10 +355,12 @@ describe('Task', () => {
     let task: Task;
     type SpyInstance = ReturnType<typeof vi.spyOn>;
     let setTaskStateAndPublishUpdateSpy: SpyInstance;
+    let mockConfig: Config;
+    let mockEventBus: ExecutionEventBus;
 
     beforeEach(() => {
-      const mockConfig = createMockConfig();
-      const mockEventBus: ExecutionEventBus = {
+      mockConfig = createMockConfig() as Config;
+      mockEventBus = {
         publish: vi.fn(),
         on: vi.fn(),
         off: vi.fn(),
@@ -218,12 +370,7 @@ describe('Task', () => {
       };
 
       // @ts-expect-error - Calling private constructor
-      task = new Task(
-        'task-id',
-        'context-id',
-        mockConfig as Config,
-        mockEventBus,
-      );
+      task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
 
       // Spy on the method we want to check calls for
       setTaskStateAndPublishUpdateSpy = vi.spyOn(
@@ -317,5 +464,149 @@ describe('Task', () => {
       );
       expect(finalCall).toBeUndefined();
     });
+
+    describe('auto-approval', () => {
+      it('should auto-approve tool calls when autoExecute is true', () => {
+        task.autoExecute = true;
+        const onConfirmSpy = vi.fn();
+        const toolCalls = [
+          {
+            request: { callId: '1' },
+            status: 'awaiting_approval',
+            confirmationDetails: { onConfirm: onConfirmSpy },
+          },
+        ] as unknown as ToolCall[];
+
+        // @ts-expect-error - Calling private method
+        task._schedulerToolCallsUpdate(toolCalls);
+
+        expect(onConfirmSpy).toHaveBeenCalledWith(
+          ToolConfirmationOutcome.ProceedOnce,
+        );
+      });
+
+      it('should auto-approve tool calls when approval mode is YOLO', () => {
+        (mockConfig.getApprovalMode as Mock).mockReturnValue(ApprovalMode.YOLO);
+        task.autoExecute = false;
+        const onConfirmSpy = vi.fn();
+        const toolCalls = [
+          {
+            request: { callId: '1' },
+            status: 'awaiting_approval',
+            confirmationDetails: { onConfirm: onConfirmSpy },
+          },
+        ] as unknown as ToolCall[];
+
+        // @ts-expect-error - Calling private method
+        task._schedulerToolCallsUpdate(toolCalls);
+
+        expect(onConfirmSpy).toHaveBeenCalledWith(
+          ToolConfirmationOutcome.ProceedOnce,
+        );
+      });
+
+      it('should NOT auto-approve when autoExecute is false and mode is not YOLO', () => {
+        task.autoExecute = false;
+        (mockConfig.getApprovalMode as Mock).mockReturnValue(
+          ApprovalMode.DEFAULT,
+        );
+        const onConfirmSpy = vi.fn();
+        const toolCalls = [
+          {
+            request: { callId: '1' },
+            status: 'awaiting_approval',
+            confirmationDetails: { onConfirm: onConfirmSpy },
+          },
+        ] as unknown as ToolCall[];
+
+        // @ts-expect-error - Calling private method
+        task._schedulerToolCallsUpdate(toolCalls);
+
+        expect(onConfirmSpy).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe('currentPromptId and promptCount', () => {
+    it('should correctly initialize and update promptId and promptCount', async () => {
+      const mockConfig = createMockConfig();
+      mockConfig.getGeminiClient = vi.fn().mockReturnValue({
+        sendMessageStream: vi.fn().mockReturnValue((async function* () {})()),
+      });
+      mockConfig.getSessionId = () => 'test-session-id';
+
+      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,
+      );
+
+      // Initial state
+      expect(task.currentPromptId).toBeUndefined();
+      expect(task.promptCount).toBe(0);
+
+      // First user message should set prompt_id
+      const userMessage1 = {
+        userMessage: {
+          parts: [{ kind: 'text', text: 'hello' }],
+        },
+      } as RequestContext;
+      const abortController1 = new AbortController();
+      for await (const _ of task.acceptUserMessage(
+        userMessage1,
+        abortController1.signal,
+      )) {
+        // no-op
+      }
+
+      const expectedPromptId1 = 'test-session-id########0';
+      expect(task.promptCount).toBe(1);
+      expect(task.currentPromptId).toBe(expectedPromptId1);
+
+      // A new user message should generate a new prompt_id
+      const userMessage2 = {
+        userMessage: {
+          parts: [{ kind: 'text', text: 'world' }],
+        },
+      } as RequestContext;
+      const abortController2 = new AbortController();
+      for await (const _ of task.acceptUserMessage(
+        userMessage2,
+        abortController2.signal,
+      )) {
+        // no-op
+      }
+
+      const expectedPromptId2 = 'test-session-id########1';
+      expect(task.promptCount).toBe(2);
+      expect(task.currentPromptId).toBe(expectedPromptId2);
+
+      // Subsequent tool call processing should use the same prompt_id
+      const completedTool = {
+        request: { callId: 'tool-1' },
+        response: { responseParts: [{ text: 'tool output' }] },
+      } as CompletedToolCall;
+      const abortController3 = new AbortController();
+      for await (const _ of task.sendCompletedToolsToLlm(
+        [completedTool],
+        abortController3.signal,
+      )) {
+        // no-op
+      }
+
+      expect(task.promptCount).toBe(2);
+      expect(task.currentPromptId).toBe(expectedPromptId2);
+    });
   });
 });

packages/a2a-server/src/agent/task.ts

@@ -15,6 +15,7 @@ import {
   isNodeError,
   parseAndFormatApiError,
   safeLiteralReplace,
+  DEFAULT_GUI_EDITOR,
   type AnyDeclarativeTool,
   type ToolCall,
   type ToolConfirmationPayload,
@@ -26,6 +27,8 @@ import {
   type Config,
   type UserTierId,
   type AnsiOutput,
+  EDIT_TOOL_NAMES,
+  processRestorableToolCalls,
 } from '@google/gemini-cli-core';
 import type { RequestContext } from '@a2a-js/sdk/server';
 import { type ExecutionEventBus } from '@a2a-js/sdk/server';
@@ -39,7 +42,8 @@ import type {
 } from '@a2a-js/sdk';
 import { v4 as uuidv4 } from 'uuid';
 import { logger } from '../utils/logger.js';
-import * as fs from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { CoderAgentEvent } from '../types.js';
 import type {
   CoderAgentMessage,
@@ -67,6 +71,9 @@ export class Task {
   completedToolCalls: CompletedToolCall[];
   skipFinalTrueAfterInlineEdit = false;
   modelInfo?: string;
+  currentPromptId: string | undefined;
+  promptCount = 0;
+  autoExecute: boolean;
 
   // For tool waiting logic
   private pendingToolCalls: Map<string, string> = new Map(); //toolCallId --> status
@@ -81,6 +88,7 @@ export class Task {
     contextId: string,
     config: Config,
     eventBus?: ExecutionEventBus,
+    autoExecute = false,
   ) {
     this.id = id;
     this.contextId = contextId;
@@ -92,6 +100,7 @@ export class Task {
     this.eventBus = eventBus;
     this.completedToolCalls = [];
     this._resetToolCompletionPromise();
+    this.autoExecute = autoExecute;
     this.config.setFallbackModelHandler(
       // For a2a-server, we want to automatically switch to the fallback model
       // for future requests without retrying the current one. The 'stop'
@@ -105,8 +114,9 @@ export class Task {
     contextId: string,
     config: Config,
     eventBus?: ExecutionEventBus,
+    autoExecute?: boolean,
   ): Promise<Task> {
-    return new Task(id, contextId, config, eventBus);
+    return new Task(id, contextId, config, eventBus, autoExecute);
   }
 
   // Note: `getAllMCPServerStatuses` retrieves the status of all MCP servers for the entire
@@ -390,10 +400,18 @@ export class Task {
       }
     });
 
-    if (this.config.getApprovalMode() === ApprovalMode.YOLO) {
-      logger.info('[Task] YOLO mode enabled. Auto-approving all tool calls.');
+    if (
+      this.autoExecute ||
+      this.config.getApprovalMode() === ApprovalMode.YOLO
+    ) {
+      logger.info(
+        '[Task] ' +
+          (this.autoExecute ? '' : 'YOLO mode enabled. ') +
+          'Auto-approving all tool calls.',
+      );
       toolCalls.forEach((tc: ToolCall) => {
         if (tc.status === 'awaiting_approval' && tc.confirmationDetails) {
+          // eslint-disable-next-line @typescript-eslint/no-floating-promises
           tc.confirmationDetails.onConfirm(ToolConfirmationOutcome.ProceedOnce);
           this.pendingToolConfirmationDetails.delete(tc.request.callId);
         }
@@ -435,7 +453,7 @@ export class Task {
       outputUpdateHandler: this._schedulerOutputUpdate.bind(this),
       onAllToolCallsComplete: this._schedulerAllToolCallsComplete.bind(this),
       onToolCallsUpdate: this._schedulerToolCallsUpdate.bind(this),
-      getPreferredEditor: () => 'vscode',
+      getPreferredEditor: () => DEFAULT_GUI_EDITOR,
       config: this.config,
     });
     return scheduler;
@@ -507,7 +525,7 @@ export class Task {
     new_string: string,
   ): Promise<string> {
     try {
-      const currentContent = fs.readFileSync(file_path, 'utf8');
+      const currentContent = await fs.readFile(file_path, 'utf8');
       return this._applyReplacement(
         currentContent,
         old_string,
@@ -550,6 +568,44 @@ export class Task {
       return;
     }
 
+    // Set checkpoint file before any file modification tool executes
+    const restorableToolCalls = requests.filter((request) =>
+      EDIT_TOOL_NAMES.has(request.name),
+    );
+
+    if (restorableToolCalls.length > 0) {
+      const gitService = await this.config.getGitService();
+      if (gitService) {
+        const { checkpointsToWrite, toolCallToCheckpointMap, errors } =
+          await processRestorableToolCalls(
+            restorableToolCalls,
+            gitService,
+            this.geminiClient,
+          );
+
+        if (errors.length > 0) {
+          errors.forEach((error) => logger.error(error));
+        }
+
+        if (checkpointsToWrite.size > 0) {
+          const checkpointDir =
+            this.config.storage.getProjectTempCheckpointsDir();
+          await fs.mkdir(checkpointDir, { recursive: true });
+          for (const [fileName, content] of checkpointsToWrite) {
+            const filePath = path.join(checkpointDir, fileName);
+            await fs.writeFile(filePath, content);
+          }
+        }
+
+        for (const request of requests) {
+          const checkpoint = toolCallToCheckpointMap.get(request.callId);
+          if (checkpoint) {
+            request.checkpoint = checkpoint;
+          }
+        }
+      }
+    }
+
     const updatedRequests = await Promise.all(
       requests.map(async (request) => {
         if (
@@ -691,8 +747,8 @@ export class Task {
       return false;
     }
 
-    const callId = part.data['callId'] as string;
-    const outcomeString = part.data['outcome'] as string;
+    const callId = part.data['callId'];
+    const outcomeString = part.data['outcome'];
     let confirmationOutcome: ToolConfirmationOutcome | undefined;
 
     if (outcomeString === 'proceed_once') {
@@ -746,7 +802,14 @@ export class Task {
               } as ToolConfirmationPayload)
             : undefined;
           this.skipFinalTrueAfterInlineEdit = !!payload;
-          await confirmationDetails.onConfirm(confirmationOutcome, payload);
+          try {
+            await confirmationDetails.onConfirm(confirmationOutcome, payload);
+          } finally {
+            // Once confirmationDetails.onConfirm finishes (or fails) with a payload,
+            // reset skipFinalTrueAfterInlineEdit so that external callers receive
+            // their call has been completed.
+            this.skipFinalTrueAfterInlineEdit = false;
+          }
         } else {
           await confirmationDetails.onConfirm(confirmationOutcome);
         }
@@ -818,6 +881,7 @@ export class Task {
       } else {
         parts = [response];
       }
+      // eslint-disable-next-line @typescript-eslint/no-floating-promises
       this.geminiClient.addHistory({
         role: 'user',
         parts,
@@ -856,11 +920,10 @@ export class Task {
     };
     // Set task state to working as we are about to call LLM
     this.setTaskStateAndPublishUpdate('working', stateChange);
-    // TODO: Determine what it mean to have, then add a prompt ID.
     yield* this.geminiClient.sendMessageStream(
       llmParts,
       aborted,
-      /*prompt_id*/ '',
+      completedToolCalls[0]?.request.prompt_id ?? '',
     );
   }
 
@@ -890,17 +953,18 @@ export class Task {
     }
 
     if (hasContentForLlm) {
+      this.currentPromptId =
+        this.config.getSessionId() + '########' + this.promptCount++;
       logger.info('[Task] Sending new parts to LLM.');
       const stateChange: StateChange = {
         kind: CoderAgentEvent.StateChangeEvent,
       };
       // Set task state to working as we are about to call LLM
       this.setTaskStateAndPublishUpdate('working', stateChange);
-      // TODO: Determine what it mean to have, then add a prompt ID.
       yield* this.geminiClient.sendMessageStream(
         llmParts,
         aborted,
-        /*prompt_id*/ '',
+        this.currentPromptId,
       );
     } else if (anyConfirmationHandled) {
       logger.info(

packages/a2a-server/src/commands/command-registry.ts

@@ -5,6 +5,8 @@
  */
 
 import { ExtensionsCommand } from './extensions.js';
+import { InitCommand } from './init.js';
+import { RestoreCommand } from './restore.js';
 import type { Command } from './types.js';
 
 class CommandRegistry {
@@ -12,6 +14,8 @@ class CommandRegistry {
 
   constructor() {
     this.register(new ExtensionsCommand());
+    this.register(new RestoreCommand());
+    this.register(new InitCommand());
   }
 
   register(command: Command) {

packages/a2a-server/src/commands/extensions.test.ts

@@ -6,7 +6,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { ExtensionsCommand, ListExtensionsCommand } from './extensions.js';
-import type { Config } from '@google/gemini-cli-core';
+import type { CommandContext } from './types.js';
 
 const mockListExtensions = vi.hoisted(() => vi.fn());
 vi.mock('@google/gemini-cli-core', async (importOriginal) => {
@@ -42,14 +42,14 @@ describe('ExtensionsCommand', () => {
 
   it('should default to listing extensions', async () => {
     const command = new ExtensionsCommand();
-    const mockConfig = {} as Config;
+    const mockConfig = { config: {} } as CommandContext;
     const mockExtensions = [{ name: 'ext1' }];
     mockListExtensions.mockReturnValue(mockExtensions);
 
     const result = await command.execute(mockConfig, []);
 
     expect(result).toEqual({ name: 'extensions list', data: mockExtensions });
-    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig.config);
   });
 });
 
@@ -61,19 +61,19 @@ describe('ListExtensionsCommand', () => {
 
   it('should call listExtensions with the provided config', async () => {
     const command = new ListExtensionsCommand();
-    const mockConfig = {} as Config;
+    const mockConfig = { config: {} } as CommandContext;
     const mockExtensions = [{ name: 'ext1' }];
     mockListExtensions.mockReturnValue(mockExtensions);
 
     const result = await command.execute(mockConfig, []);
 
     expect(result).toEqual({ name: 'extensions list', data: mockExtensions });
-    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig.config);
   });
 
   it('should return a message when no extensions are installed', async () => {
     const command = new ListExtensionsCommand();
-    const mockConfig = {} as Config;
+    const mockConfig = { config: {} } as CommandContext;
     mockListExtensions.mockReturnValue([]);
 
     const result = await command.execute(mockConfig, []);
@@ -82,6 +82,6 @@ describe('ListExtensionsCommand', () => {
       name: 'extensions list',
       data: 'No extensions installed.',
     });
-    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig);
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig.config);
   });
 });

packages/a2a-server/src/commands/extensions.ts

@@ -4,8 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { listExtensions, type Config } from '@google/gemini-cli-core';
-import type { Command, CommandExecutionResponse } from './types.js';
+import { listExtensions } from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
 
 export class ExtensionsCommand implements Command {
   readonly name = 'extensions';
@@ -14,10 +18,10 @@ export class ExtensionsCommand implements Command {
   readonly topLevel = true;
 
   async execute(
-    config: Config,
+    context: CommandContext,
     _: string[],
   ): Promise<CommandExecutionResponse> {
-    return new ListExtensionsCommand().execute(config, _);
+    return new ListExtensionsCommand().execute(context, _);
   }
 }
 
@@ -26,10 +30,10 @@ export class ListExtensionsCommand implements Command {
   readonly description = 'Lists all installed extensions.';
 
   async execute(
-    config: Config,
+    context: CommandContext,
     _: string[],
   ): Promise<CommandExecutionResponse> {
-    const extensions = listExtensions(config);
+    const extensions = listExtensions(context.config);
     const data = extensions.length ? extensions : 'No extensions installed.';
 
     return { name: this.name, data };

packages/a2a-server/src/commands/init.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { InitCommand } from './init.js';
+import { performInit } from '@google/gemini-cli-core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CoderAgentExecutor } from '../agent/executor.js';
+import { CoderAgentEvent } from '../types.js';
+import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import { createMockConfig } from '../utils/testing_utils.js';
+import type { CommandContext } from './types.js';
+import type { CommandActionReturn, Config } from '@google/gemini-cli-core';
+import { logger } from '../utils/logger.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    performInit: vi.fn(),
+  };
+});
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}));
+
+vi.mock('../agent/executor.js', () => ({
+  CoderAgentExecutor: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(),
+  })),
+}));
+
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+describe('InitCommand', () => {
+  let eventBus: ExecutionEventBus;
+  let command: InitCommand;
+  let context: CommandContext;
+  let publishSpy: ReturnType<typeof vi.spyOn>;
+  let mockExecute: ReturnType<typeof vi.fn>;
+  const mockWorkspacePath = path.resolve('/tmp');
+
+  beforeEach(() => {
+    process.env['CODER_AGENT_WORKSPACE_PATH'] = mockWorkspacePath;
+    eventBus = {
+      publish: vi.fn(),
+    } as unknown as ExecutionEventBus;
+    command = new InitCommand();
+    const mockConfig = createMockConfig({
+      getModel: () => 'gemini-pro',
+    });
+    const mockExecutorInstance = new CoderAgentExecutor();
+    context = {
+      config: mockConfig as unknown as Config,
+      agentExecutor: mockExecutorInstance,
+      eventBus,
+    } as CommandContext;
+    publishSpy = vi.spyOn(eventBus, 'publish');
+    mockExecute = vi.fn();
+    vi.spyOn(mockExecutorInstance, 'execute').mockImplementation(mockExecute);
+    vi.clearAllMocks();
+  });
+
+  it('has requiresWorkspace set to true', () => {
+    expect(command.requiresWorkspace).toBe(true);
+  });
+
+  describe('execute', () => {
+    it('handles info from performInit', async () => {
+      vi.mocked(performInit).mockReturnValue({
+        type: 'message',
+        messageType: 'info',
+        content: 'GEMINI.md already exists.',
+      } as CommandActionReturn);
+
+      await command.execute(context, []);
+
+      expect(logger.info).toHaveBeenCalledWith(
+        '[EventBus event]: ',
+        expect.objectContaining({
+          kind: 'status-update',
+          status: expect.objectContaining({
+            state: 'completed',
+            message: expect.objectContaining({
+              parts: [{ kind: 'text', text: 'GEMINI.md already exists.' }],
+            }),
+          }),
+        }),
+      );
+
+      expect(publishSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'status-update',
+          status: expect.objectContaining({
+            state: 'completed',
+            message: expect.objectContaining({
+              parts: [{ kind: 'text', text: 'GEMINI.md already exists.' }],
+            }),
+          }),
+        }),
+      );
+    });
+
+    it('handles error from performInit', async () => {
+      vi.mocked(performInit).mockReturnValue({
+        type: 'message',
+        messageType: 'error',
+        content: 'An error occurred.',
+      } as CommandActionReturn);
+
+      await command.execute(context, []);
+
+      expect(publishSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'status-update',
+          status: expect.objectContaining({
+            state: 'failed',
+            message: expect.objectContaining({
+              parts: [{ kind: 'text', text: 'An error occurred.' }],
+            }),
+          }),
+        }),
+      );
+    });
+
+    describe('when handling submit_prompt', () => {
+      beforeEach(() => {
+        vi.mocked(performInit).mockReturnValue({
+          type: 'submit_prompt',
+          content: 'Create a new GEMINI.md file.',
+        } as CommandActionReturn);
+      });
+
+      it('writes the file and executes the agent', async () => {
+        await command.execute(context, []);
+
+        expect(fs.writeFileSync).toHaveBeenCalledWith(
+          path.join(mockWorkspacePath, 'GEMINI.md'),
+          '',
+          'utf8',
+        );
+        expect(mockExecute).toHaveBeenCalled();
+      });
+
+      it('passes autoExecute to the agent executor', async () => {
+        await command.execute(context, []);
+
+        expect(mockExecute).toHaveBeenCalledWith(
+          expect.objectContaining({
+            userMessage: expect.objectContaining({
+              parts: expect.arrayContaining([
+                expect.objectContaining({
+                  text: 'Create a new GEMINI.md file.',
+                }),
+              ]),
+              metadata: {
+                coderAgent: {
+                  kind: CoderAgentEvent.StateAgentSettingsEvent,
+                  workspacePath: mockWorkspacePath,
+                  autoExecute: true,
+                },
+              },
+            }),
+          }),
+          eventBus,
+        );
+      });
+    });
+  });
+});

packages/a2a-server/src/commands/init.ts

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CoderAgentEvent, type AgentSettings } from '../types.js';
+import { performInit } from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+import type { CoderAgentExecutor } from '../agent/executor.js';
+import type {
+  ExecutionEventBus,
+  RequestContext,
+  AgentExecutionEvent,
+} from '@a2a-js/sdk/server';
+import { v4 as uuidv4 } from 'uuid';
+import { logger } from '../utils/logger.js';
+
+export class InitCommand implements Command {
+  name = 'init';
+  description = 'Analyzes the project and creates a tailored GEMINI.md file';
+  requiresWorkspace = true;
+  streaming = true;
+
+  private handleMessageResult(
+    result: { content: string; messageType: 'info' | 'error' },
+    context: CommandContext,
+    eventBus: ExecutionEventBus,
+    taskId: string,
+    contextId: string,
+  ): CommandExecutionResponse {
+    const statusState = result.messageType === 'error' ? 'failed' : 'completed';
+    const eventType =
+      result.messageType === 'error'
+        ? CoderAgentEvent.StateChangeEvent
+        : CoderAgentEvent.TextContentEvent;
+
+    const event: AgentExecutionEvent = {
+      kind: 'status-update',
+      taskId,
+      contextId,
+      status: {
+        state: statusState,
+        message: {
+          kind: 'message',
+          role: 'agent',
+          parts: [{ kind: 'text', text: result.content }],
+          messageId: uuidv4(),
+          taskId,
+          contextId,
+        },
+        timestamp: new Date().toISOString(),
+      },
+      final: true,
+      metadata: {
+        coderAgent: { kind: eventType },
+        model: context.config.getModel(),
+      },
+    };
+
+    logger.info('[EventBus event]: ', event);
+    eventBus.publish(event);
+    return {
+      name: this.name,
+      data: result,
+    };
+  }
+
+  private async handleSubmitPromptResult(
+    result: { content: unknown },
+    context: CommandContext,
+    geminiMdPath: string,
+    eventBus: ExecutionEventBus,
+    taskId: string,
+    contextId: string,
+  ): Promise<CommandExecutionResponse> {
+    fs.writeFileSync(geminiMdPath, '', 'utf8');
+
+    if (!context.agentExecutor) {
+      throw new Error('Agent executor not found in context.');
+    }
+    const agentExecutor = context.agentExecutor as CoderAgentExecutor;
+
+    const agentSettings: AgentSettings = {
+      kind: CoderAgentEvent.StateAgentSettingsEvent,
+      workspacePath: process.env['CODER_AGENT_WORKSPACE_PATH']!,
+      autoExecute: true,
+    };
+
+    if (typeof result.content !== 'string') {
+      throw new Error('Init command content must be a string.');
+    }
+    const promptText = result.content;
+
+    const requestContext: RequestContext = {
+      userMessage: {
+        kind: 'message',
+        role: 'user',
+        parts: [{ kind: 'text', text: promptText }],
+        messageId: uuidv4(),
+        taskId,
+        contextId,
+        metadata: {
+          coderAgent: agentSettings,
+        },
+      },
+      taskId,
+      contextId,
+    };
+
+    // The executor will handle the entire agentic loop, including
+    // creating the task, streaming responses, and handling tools.
+    await agentExecutor.execute(requestContext, eventBus);
+    return {
+      name: this.name,
+      data: geminiMdPath,
+    };
+  }
+
+  async execute(
+    context: CommandContext,
+    _args: string[] = [],
+  ): Promise<CommandExecutionResponse> {
+    if (!context.eventBus) {
+      return {
+        name: this.name,
+        data: 'Use executeStream to get streaming results.',
+      };
+    }
+
+    const geminiMdPath = path.join(
+      process.env['CODER_AGENT_WORKSPACE_PATH']!,
+      'GEMINI.md',
+    );
+    const result = performInit(fs.existsSync(geminiMdPath));
+
+    const taskId = uuidv4();
+    const contextId = uuidv4();
+
+    switch (result.type) {
+      case 'message':
+        return this.handleMessageResult(
+          result,
+          context,
+          context.eventBus,
+          taskId,
+          contextId,
+        );
+      case 'submit_prompt':
+        return this.handleSubmitPromptResult(
+          result,
+          context,
+          geminiMdPath,
+          context.eventBus,
+          taskId,
+          contextId,
+        );
+      default:
+        throw new Error('Unknown result type from performInit');
+    }
+  }
+}

packages/a2a-server/src/commands/restore.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RestoreCommand, ListCheckpointsCommand } from './restore.js';
+import type { CommandContext } from './types.js';
+import type { Config } from '@google/gemini-cli-core';
+import { createMockConfig } from '../utils/testing_utils.js';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+const mockPerformRestore = vi.hoisted(() => vi.fn());
+const mockLoggerInfo = vi.hoisted(() => vi.fn());
+const mockGetCheckpointInfoList = vi.hoisted(() => vi.fn());
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...original,
+    performRestore: mockPerformRestore,
+    getCheckpointInfoList: mockGetCheckpointInfoList,
+  };
+});
+
+const mockFs = vi.hoisted(() => ({
+  readFile: vi.fn(),
+  readdir: vi.fn(),
+  mkdir: vi.fn(),
+}));
+
+vi.mock('node:fs/promises', () => mockFs);
+
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: mockLoggerInfo,
+  },
+}));
+
+describe('RestoreCommand', () => {
+  const mockConfig = {
+    config: createMockConfig() as Config,
+    git: {},
+  } as CommandContext;
+
+  it('should return error if no checkpoint name is provided', async () => {
+    const command = new RestoreCommand();
+    const result = await command.execute(mockConfig, []);
+    expect(result.data).toEqual({
+      type: 'message',
+      messageType: 'error',
+      content: 'Please provide a checkpoint name to restore.',
+    });
+  });
+
+  it('should restore a checkpoint when a valid file is provided', async () => {
+    const command = new RestoreCommand();
+    const toolCallData = {
+      toolCall: {
+        name: 'test-tool',
+        args: {},
+      },
+      history: [],
+      clientHistory: [],
+      commitHash: '123',
+    };
+    mockFs.readFile.mockResolvedValue(JSON.stringify(toolCallData));
+    const restoreContent = {
+      type: 'message',
+      messageType: 'info',
+      content: 'Restored',
+    };
+    mockPerformRestore.mockReturnValue(
+      (async function* () {
+        yield restoreContent;
+      })(),
+    );
+    const result = await command.execute(mockConfig, ['checkpoint1.json']);
+    expect(result.data).toEqual([restoreContent]);
+  });
+
+  it('should show "file not found" error for a non-existent checkpoint', async () => {
+    const command = new RestoreCommand();
+    const error = new Error('File not found');
+    (error as NodeJS.ErrnoException).code = 'ENOENT';
+    mockFs.readFile.mockRejectedValue(error);
+    const result = await command.execute(mockConfig, ['checkpoint2.json']);
+    expect(result.data).toEqual({
+      type: 'message',
+      messageType: 'error',
+      content: 'File not found: checkpoint2.json',
+    });
+  });
+
+  it('should handle invalid JSON in checkpoint file', async () => {
+    const command = new RestoreCommand();
+    mockFs.readFile.mockResolvedValue('invalid json');
+    const result = await command.execute(mockConfig, ['checkpoint1.json']);
+    expect((result.data as { content: string }).content).toContain(
+      'An unexpected error occurred during restore.',
+    );
+  });
+});
+
+describe('ListCheckpointsCommand', () => {
+  const mockConfig = {
+    config: createMockConfig() as Config,
+  } as CommandContext;
+
+  it('should list all available checkpoints', async () => {
+    const command = new ListCheckpointsCommand();
+    const checkpointInfo = [{ file: 'checkpoint1.json', description: 'Test' }];
+    mockFs.readdir.mockResolvedValue(['checkpoint1.json']);
+    mockFs.readFile.mockResolvedValue(
+      JSON.stringify({ toolCall: { name: 'Test', args: {} } }),
+    );
+    mockGetCheckpointInfoList.mockReturnValue(checkpointInfo);
+    const result = await command.execute(mockConfig);
+    expect((result.data as { content: string }).content).toEqual(
+      JSON.stringify(checkpointInfo),
+    );
+  });
+
+  it('should handle errors when listing checkpoints', async () => {
+    const command = new ListCheckpointsCommand();
+    mockFs.readdir.mockRejectedValue(new Error('Read error'));
+    const result = await command.execute(mockConfig);
+    expect((result.data as { content: string }).content).toContain(
+      'An unexpected error occurred while listing checkpoints.',
+    );
+  });
+});

packages/a2a-server/src/commands/restore.ts

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  getCheckpointInfoList,
+  getToolCallDataSchema,
+  isNodeError,
+  performRestore,
+} from '@google/gemini-cli-core';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class RestoreCommand implements Command {
+  readonly name = 'restore';
+  readonly description =
+    'Restore to a previous checkpoint, or list available checkpoints to restore. This will reset the conversation and file history to the state it was in when the checkpoint was created';
+  readonly topLevel = true;
+  readonly requiresWorkspace = true;
+  readonly subCommands = [new ListCheckpointsCommand()];
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const { config, git: gitService } = context;
+    const argsStr = args.join(' ');
+
+    try {
+      if (!argsStr) {
+        return {
+          name: this.name,
+          data: {
+            type: 'message',
+            messageType: 'error',
+            content: 'Please provide a checkpoint name to restore.',
+          },
+        };
+      }
+
+      const selectedFile = argsStr.endsWith('.json')
+        ? argsStr
+        : `${argsStr}.json`;
+
+      const checkpointDir = config.storage.getProjectTempCheckpointsDir();
+      const filePath = path.join(checkpointDir, selectedFile);
+
+      let data: string;
+      try {
+        data = await fs.readFile(filePath, 'utf-8');
+      } catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+          return {
+            name: this.name,
+            data: {
+              type: 'message',
+              messageType: 'error',
+              content: `File not found: ${selectedFile}`,
+            },
+          };
+        }
+        throw error;
+      }
+
+      const toolCallData = JSON.parse(data);
+      const ToolCallDataSchema = getToolCallDataSchema();
+      const parseResult = ToolCallDataSchema.safeParse(toolCallData);
+
+      if (!parseResult.success) {
+        return {
+          name: this.name,
+          data: {
+            type: 'message',
+            messageType: 'error',
+            content: 'Checkpoint file is invalid or corrupted.',
+          },
+        };
+      }
+
+      const restoreResultGenerator = performRestore(
+        parseResult.data,
+        gitService,
+      );
+      const restoreResult = [];
+      for await (const result of restoreResultGenerator) {
+        restoreResult.push(result);
+      }
+
+      return {
+        name: this.name,
+        data: restoreResult,
+      };
+    } catch (_error) {
+      return {
+        name: this.name,
+        data: {
+          type: 'message',
+          messageType: 'error',
+          content: 'An unexpected error occurred during restore.',
+        },
+      };
+    }
+  }
+}
+
+export class ListCheckpointsCommand implements Command {
+  readonly name = 'restore list';
+  readonly description = 'Lists all available checkpoints.';
+  readonly topLevel = false;
+
+  async execute(context: CommandContext): Promise<CommandExecutionResponse> {
+    const { config } = context;
+
+    try {
+      const checkpointDir = config.storage.getProjectTempCheckpointsDir();
+      await fs.mkdir(checkpointDir, { recursive: true });
+      const files = await fs.readdir(checkpointDir);
+      const jsonFiles = files.filter((file) => file.endsWith('.json'));
+
+      const checkpointFiles = new Map<string, string>();
+      for (const file of jsonFiles) {
+        const filePath = path.join(checkpointDir, file);
+        const data = await fs.readFile(filePath, 'utf-8');
+        checkpointFiles.set(file, data);
+      }
+
+      const checkpointInfoList = getCheckpointInfoList(checkpointFiles);
+
+      return {
+        name: this.name,
+        data: {
+          type: 'message',
+          messageType: 'info',
+          content: JSON.stringify(checkpointInfoList),
+        },
+      };
+    } catch (_error) {
+      return {
+        name: this.name,
+        data: {
+          type: 'message',
+          messageType: 'error',
+          content: 'An unexpected error occurred while listing checkpoints.',
+        },
+      };
+    }
+  }
+}

packages/a2a-server/src/commands/types.ts

@@ -4,7 +4,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { Config } from '@google/gemini-cli-core';
+import type { ExecutionEventBus, AgentExecutor } from '@a2a-js/sdk/server';
+import type { Config, GitService } from '@google/gemini-cli-core';
+
+export interface CommandContext {
+  config: Config;
+  git?: GitService;
+  agentExecutor?: AgentExecutor;
+  eventBus?: ExecutionEventBus;
+}
 
 export interface CommandArgument {
   readonly name: string;
@@ -18,8 +26,13 @@ export interface Command {
   readonly arguments?: CommandArgument[];
   readonly subCommands?: Command[];
   readonly topLevel?: boolean;
+  readonly requiresWorkspace?: boolean;
+  readonly streaming?: boolean;
 
-  execute(config: Config, args: string[]): Promise<CommandExecutionResponse>;
+  execute(
+    config: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse>;
 }
 
 export interface CommandExecutionResponse {

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

@@ -22,6 +22,7 @@ import {
   DEFAULT_GEMINI_MODEL,
   type ExtensionLoader,
   startupProfiler,
+  PREVIEW_GEMINI_MODEL,
 } from '@google/gemini-cli-core';
 
 import { logger } from '../utils/logger.js';
@@ -38,7 +39,9 @@ export async function loadConfig(
 
   const configParams: ConfigParameters = {
     sessionId: taskId,
-    model: DEFAULT_GEMINI_MODEL,
+    model: settings.general?.previewFeatures
+      ? PREVIEW_GEMINI_MODEL
+      : DEFAULT_GEMINI_MODEL,
     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
@@ -71,6 +74,11 @@ export async function loadConfig(
     ideMode: false,
     folderTrust: settings.folderTrust === true,
     extensionLoader,
+    checkpointing: process.env['CHECKPOINTING']
+      ? process.env['CHECKPOINTING'] === 'true'
+      : settings.checkpointing?.enabled,
+    previewFeatures: settings.general?.previewFeatures,
+    interactive: true,
   };
 
   const fileService = new FileDiscoveryService(workspaceDir);

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

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * Copyright 2025 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';
+import { loadSettings, USER_SETTINGS_PATH } from './settings.js';
+
+const mocks = vi.hoisted(() => {
+  const suffix = Math.random().toString(36).slice(2);
+  return {
+    suffix,
+  };
+});
+
+vi.mock('node:os', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:os')>();
+  const path = await import('node:path');
+  return {
+    ...actual,
+    homedir: () => path.join(actual.tmpdir(), `gemini-home-${mocks.suffix}`),
+  };
+});
+
+vi.mock('@google/gemini-cli-core', () => ({
+  GEMINI_DIR: '.gemini',
+  debugLogger: {
+    error: vi.fn(),
+  },
+  getErrorMessage: (error: unknown) => String(error),
+}));
+
+describe('loadSettings', () => {
+  const mockHomeDir = path.join(os.tmpdir(), `gemini-home-${mocks.suffix}`);
+  const mockWorkspaceDir = path.join(
+    os.tmpdir(),
+    `gemini-workspace-${mocks.suffix}`,
+  );
+  const mockGeminiHomeDir = path.join(mockHomeDir, '.gemini');
+  const mockGeminiWorkspaceDir = path.join(mockWorkspaceDir, '.gemini');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Create the directories using the real fs
+    if (!fs.existsSync(mockGeminiHomeDir)) {
+      fs.mkdirSync(mockGeminiHomeDir, { recursive: true });
+    }
+    if (!fs.existsSync(mockGeminiWorkspaceDir)) {
+      fs.mkdirSync(mockGeminiWorkspaceDir, { recursive: true });
+    }
+
+    // Clean up settings files before each test
+    if (fs.existsSync(USER_SETTINGS_PATH)) {
+      fs.rmSync(USER_SETTINGS_PATH);
+    }
+    const workspaceSettingsPath = path.join(
+      mockGeminiWorkspaceDir,
+      'settings.json',
+    );
+    if (fs.existsSync(workspaceSettingsPath)) {
+      fs.rmSync(workspaceSettingsPath);
+    }
+  });
+
+  afterEach(() => {
+    try {
+      if (fs.existsSync(mockHomeDir)) {
+        fs.rmSync(mockHomeDir, { recursive: true, force: true });
+      }
+      if (fs.existsSync(mockWorkspaceDir)) {
+        fs.rmSync(mockWorkspaceDir, { recursive: true, force: true });
+      }
+    } catch (e) {
+      console.error('Failed to cleanup temp dirs', e);
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('should load nested previewFeatures from user settings', () => {
+    const settings = {
+      general: {
+        previewFeatures: true,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(settings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.general?.previewFeatures).toBe(true);
+  });
+
+  it('should load nested previewFeatures from workspace settings', () => {
+    const settings = {
+      general: {
+        previewFeatures: true,
+      },
+    };
+    const workspaceSettingsPath = path.join(
+      mockGeminiWorkspaceDir,
+      'settings.json',
+    );
+    fs.writeFileSync(workspaceSettingsPath, JSON.stringify(settings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.general?.previewFeatures).toBe(true);
+  });
+
+  it('should prioritize workspace settings over user settings', () => {
+    const userSettings = {
+      general: {
+        previewFeatures: false,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(userSettings));
+
+    const workspaceSettings = {
+      general: {
+        previewFeatures: true,
+      },
+    };
+    const workspaceSettingsPath = path.join(
+      mockGeminiWorkspaceDir,
+      'settings.json',
+    );
+    fs.writeFileSync(workspaceSettingsPath, JSON.stringify(workspaceSettings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.general?.previewFeatures).toBe(true);
+  });
+
+  it('should handle missing previewFeatures', () => {
+    const settings = {
+      general: {},
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(settings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.general?.previewFeatures).toBeUndefined();
+  });
+
+  it('should load other top-level settings correctly', () => {
+    const settings = {
+      showMemoryUsage: true,
+      coreTools: ['tool1', 'tool2'],
+      mcpServers: {
+        server1: {
+          command: 'cmd',
+          args: ['arg'],
+        },
+      },
+      fileFiltering: {
+        respectGitIgnore: true,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(settings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.showMemoryUsage).toBe(true);
+    expect(result.coreTools).toEqual(['tool1', 'tool2']);
+    expect(result.mcpServers).toHaveProperty('server1');
+    expect(result.fileFiltering?.respectGitIgnore).toBe(true);
+  });
+
+  it('should overwrite top-level settings from workspace (shallow merge)', () => {
+    const userSettings = {
+      showMemoryUsage: false,
+      fileFiltering: {
+        respectGitIgnore: true,
+        enableRecursiveFileSearch: true,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(userSettings));
+
+    const workspaceSettings = {
+      showMemoryUsage: true,
+      fileFiltering: {
+        respectGitIgnore: false,
+      },
+    };
+    const workspaceSettingsPath = path.join(
+      mockGeminiWorkspaceDir,
+      'settings.json',
+    );
+    fs.writeFileSync(workspaceSettingsPath, JSON.stringify(workspaceSettings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    // Primitive value overwritten
+    expect(result.showMemoryUsage).toBe(true);
+
+    // Object value completely replaced (shallow merge behavior)
+    expect(result.fileFiltering?.respectGitIgnore).toBe(false);
+    expect(result.fileFiltering?.enableRecursiveFileSearch).toBeUndefined();
+  });
+});

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

@@ -20,7 +20,9 @@ import stripJsonComments from 'strip-json-comments';
 export const USER_SETTINGS_DIR = path.join(homedir(), GEMINI_DIR);
 export const USER_SETTINGS_PATH = path.join(USER_SETTINGS_DIR, 'settings.json');
 
-// Reconcile with https://github.com/google-gemini/gemini-cli/blob/b09bc6656080d4d12e1d06734aae2ec33af5c1ed/packages/cli/src/config/settings.ts#L53
+// TODO: Ensure full compatibility with V2 nested settings structure (settings.schema.json).
+// This involves updating the interface and implementing migration logic to support legacy V1 (flat) settings,
+// similar to how packages/cli/src/config/settings.ts handles it.
 export interface Settings {
   mcpServers?: Record<string, MCPServerConfig>;
   coreTools?: string[];
@@ -29,6 +31,9 @@ export interface Settings {
   showMemoryUsage?: boolean;
   checkpointing?: CheckpointingSettings;
   folderTrust?: boolean;
+  general?: {
+    previewFeatures?: boolean;
+  };
 
   // Git-aware file filtering settings
   fileFiltering?: {
@@ -118,7 +123,7 @@ function resolveEnvVarsInString(value: string): string {
   return value.replace(envVarRegex, (match, varName1, varName2) => {
     const varName = varName1 || varName2;
     if (process && process.env && typeof process.env[varName] === 'string') {
-      return process.env[varName]!;
+      return process.env[varName];
     }
     return match;
   });

packages/a2a-server/src/http/app.test.ts

@@ -36,7 +36,7 @@ import {
   createMockConfig,
 } from '../utils/testing_utils.js';
 import { MockTool } from '@google/gemini-cli-core';
-import type { Command } from '../commands/types.js';
+import type { Command, CommandContext } from '../commands/types.js';
 
 const mockToolConfirmationFn = async () =>
   ({}) as unknown as ToolCallConfirmationDetails;
@@ -97,6 +97,7 @@ vi.mock('@google/gemini-cli-core', async () => {
       getUserTier: vi.fn().mockReturnValue('free'),
       initialize: vi.fn(),
     })),
+    performRestore: vi.fn(),
   };
 });
 
@@ -939,6 +940,17 @@ describe('E2E Tests', () => {
     });
 
     it('should return extensions for valid command', async () => {
+      const mockExtensionsCommand = {
+        name: 'extensions list',
+        description: 'a mock command',
+        execute: vi.fn(async (context: CommandContext) => {
+          // Simulate the actual command's behavior
+          const extensions = context.config.getExtensions();
+          return { name: 'extensions list', data: extensions };
+        }),
+      };
+      vi.spyOn(commandRegistry, 'get').mockReturnValue(mockExtensionsCommand);
+
       const agent = request.agent(app);
       const res = await agent
         .post('/executeCommand')
@@ -954,6 +966,8 @@ describe('E2E Tests', () => {
     });
 
     it('should return 404 for invalid command', async () => {
+      vi.spyOn(commandRegistry, 'get').mockReturnValue(undefined);
+
       const agent = request.agent(app);
       const res = await agent
         .post('/executeCommand')
@@ -986,5 +1000,179 @@ describe('E2E Tests', () => {
       expect(res.body.error).toBe('"args" field must be an array.');
       expect(getExtensionsSpy).not.toHaveBeenCalled();
     });
+
+    it('should execute a command that does not require a workspace when CODER_AGENT_WORKSPACE_PATH is not set', async () => {
+      const mockCommand = {
+        name: 'test-command',
+        description: 'a mock command',
+        execute: vi
+          .fn()
+          .mockResolvedValue({ name: 'test-command', data: 'success' }),
+      };
+      vi.spyOn(commandRegistry, 'get').mockReturnValue(mockCommand);
+
+      delete process.env['CODER_AGENT_WORKSPACE_PATH'];
+      const response = await request(app)
+        .post('/executeCommand')
+        .send({ command: 'test-command', args: [] });
+
+      expect(response.status).toBe(200);
+      expect(response.body.data).toBe('success');
+    });
+
+    it('should return 400 for a command that requires a workspace when CODER_AGENT_WORKSPACE_PATH is not set', async () => {
+      const mockWorkspaceCommand = {
+        name: 'workspace-command',
+        description: 'A command that requires a workspace',
+        requiresWorkspace: true,
+        execute: vi
+          .fn()
+          .mockResolvedValue({ name: 'workspace-command', data: 'success' }),
+      };
+      vi.spyOn(commandRegistry, 'get').mockReturnValue(mockWorkspaceCommand);
+
+      delete process.env['CODER_AGENT_WORKSPACE_PATH'];
+      const response = await request(app)
+        .post('/executeCommand')
+        .send({ command: 'workspace-command', args: [] });
+
+      expect(response.status).toBe(400);
+      expect(response.body.error).toBe(
+        'Command "workspace-command" requires a workspace, but CODER_AGENT_WORKSPACE_PATH is not set.',
+      );
+    });
+
+    it('should execute a command that requires a workspace when CODER_AGENT_WORKSPACE_PATH is set', async () => {
+      const mockWorkspaceCommand = {
+        name: 'workspace-command',
+        description: 'A command that requires a workspace',
+        requiresWorkspace: true,
+        execute: vi
+          .fn()
+          .mockResolvedValue({ name: 'workspace-command', data: 'success' }),
+      };
+      vi.spyOn(commandRegistry, 'get').mockReturnValue(mockWorkspaceCommand);
+
+      process.env['CODER_AGENT_WORKSPACE_PATH'] = '/tmp/test-workspace';
+      const response = await request(app)
+        .post('/executeCommand')
+        .send({ command: 'workspace-command', args: [] });
+
+      expect(response.status).toBe(200);
+      expect(response.body.data).toBe('success');
+    });
+
+    it('should include agentExecutor in context', async () => {
+      const mockCommand = {
+        name: 'context-check-command',
+        description: 'checks context',
+        execute: vi.fn(async (context: CommandContext) => {
+          if (!context.agentExecutor) {
+            throw new Error('agentExecutor missing');
+          }
+          return { name: 'context-check-command', data: 'success' };
+        }),
+      };
+      vi.spyOn(commandRegistry, 'get').mockReturnValue(mockCommand);
+
+      const agent = request.agent(app);
+      const res = await agent
+        .post('/executeCommand')
+        .send({ command: 'context-check-command', args: [] })
+        .set('Content-Type', 'application/json')
+        .expect(200);
+
+      expect(res.body.data).toBe('success');
+    });
+
+    describe('/executeCommand streaming', () => {
+      it('should execute a streaming command and stream back events', (done: (
+        err?: unknown,
+      ) => void) => {
+        const executeSpy = vi.fn(async (context: CommandContext) => {
+          context.eventBus?.publish({
+            kind: 'status-update',
+            status: { state: 'working' },
+            taskId: 'test-task',
+            contextId: 'test-context',
+            final: false,
+          });
+          context.eventBus?.publish({
+            kind: 'status-update',
+            status: { state: 'completed' },
+            taskId: 'test-task',
+            contextId: 'test-context',
+            final: true,
+          });
+          return { name: 'stream-test', data: 'done' };
+        });
+
+        const mockStreamCommand = {
+          name: 'stream-test',
+          description: 'A test streaming command',
+          streaming: true,
+          execute: executeSpy,
+        };
+        vi.spyOn(commandRegistry, 'get').mockReturnValue(mockStreamCommand);
+
+        const agent = request.agent(app);
+        agent
+          .post('/executeCommand')
+          .send({ command: 'stream-test', args: [] })
+          .set('Content-Type', 'application/json')
+          .set('Accept', 'text/event-stream')
+          .on('response', (res) => {
+            let data = '';
+            res.on('data', (chunk: Buffer) => {
+              data += chunk.toString();
+            });
+            res.on('end', () => {
+              try {
+                const events = streamToSSEEvents(data);
+                expect(events.length).toBe(2);
+                expect(events[0].result).toEqual({
+                  kind: 'status-update',
+                  status: { state: 'working' },
+                  taskId: 'test-task',
+                  contextId: 'test-context',
+                  final: false,
+                });
+                expect(events[1].result).toEqual({
+                  kind: 'status-update',
+                  status: { state: 'completed' },
+                  taskId: 'test-task',
+                  contextId: 'test-context',
+                  final: true,
+                });
+                expect(executeSpy).toHaveBeenCalled();
+                done();
+              } catch (e) {
+                done(e);
+              }
+            });
+          })
+          .end();
+      });
+
+      it('should handle non-streaming commands gracefully', async () => {
+        const mockNonStreamCommand = {
+          name: 'non-stream-test',
+          description: 'A test non-streaming command',
+          execute: vi
+            .fn()
+            .mockResolvedValue({ name: 'non-stream-test', data: 'done' }),
+        };
+        vi.spyOn(commandRegistry, 'get').mockReturnValue(mockNonStreamCommand);
+
+        const agent = request.agent(app);
+        const res = await agent
+          .post('/executeCommand')
+          .send({ command: 'non-stream-test', args: [] })
+          .set('Content-Type', 'application/json')
+          .expect(200);
+
+        expect(res.body).toEqual({ name: 'non-stream-test', data: 'done' });
+      });
+    });
   });
 });

packages/a2a-server/src/http/app.ts

@@ -6,9 +6,14 @@
 
 import express from 'express';
 
-import type { AgentCard } from '@a2a-js/sdk';
+import type { AgentCard, Message } from '@a2a-js/sdk';
 import type { TaskStore } from '@a2a-js/sdk/server';
-import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
+import {
+  DefaultRequestHandler,
+  InMemoryTaskStore,
+  DefaultExecutionEventBus,
+  type AgentExecutionEvent,
+} from '@a2a-js/sdk/server';
 import { A2AExpressApp } from '@a2a-js/sdk/server/express'; // Import server components
 import { v4 as uuidv4 } from 'uuid';
 import { logger } from '../utils/logger.js';
@@ -22,6 +27,7 @@ import { loadExtensions } from '../config/extension.js';
 import { commandRegistry } from '../commands/command-registry.js';
 import { SimpleExtensionLoader } from '@google/gemini-cli-core';
 import type { Command, CommandArgument } from '../commands/types.js';
+import { GitService } from '@google/gemini-cli-core';
 
 type CommandResponse = {
   name: string;
@@ -72,6 +78,76 @@ export function updateCoderAgentCardUrl(port: number) {
   coderAgentCard.url = `http://localhost:${port}/`;
 }
 
+async function handleExecuteCommand(
+  req: express.Request,
+  res: express.Response,
+  context: {
+    config: Awaited<ReturnType<typeof loadConfig>>;
+    git: GitService | undefined;
+    agentExecutor: CoderAgentExecutor;
+  },
+) {
+  logger.info('[CoreAgent] Received /executeCommand request: ', req.body);
+  const { command, args } = req.body;
+  try {
+    if (typeof command !== 'string') {
+      return res.status(400).json({ error: 'Invalid "command" field.' });
+    }
+
+    if (args && !Array.isArray(args)) {
+      return res.status(400).json({ error: '"args" field must be an array.' });
+    }
+
+    const commandToExecute = commandRegistry.get(command);
+
+    if (commandToExecute?.requiresWorkspace) {
+      if (!process.env['CODER_AGENT_WORKSPACE_PATH']) {
+        return res.status(400).json({
+          error: `Command "${command}" requires a workspace, but CODER_AGENT_WORKSPACE_PATH is not set.`,
+        });
+      }
+    }
+
+    if (!commandToExecute) {
+      return res.status(404).json({ error: `Command not found: ${command}` });
+    }
+
+    if (commandToExecute.streaming) {
+      const eventBus = new DefaultExecutionEventBus();
+      res.setHeader('Content-Type', 'text/event-stream');
+      const eventHandler = (event: AgentExecutionEvent) => {
+        const jsonRpcResponse = {
+          jsonrpc: '2.0',
+          id: 'taskId' in event ? event.taskId : (event as Message).messageId,
+          result: event,
+        };
+        res.write(`data: ${JSON.stringify(jsonRpcResponse)}\n`);
+      };
+      eventBus.on('event', eventHandler);
+
+      await commandToExecute.execute({ ...context, eventBus }, args ?? []);
+
+      eventBus.off('event', eventHandler);
+      eventBus.finished();
+      return res.end(); // Explicit return for streaming path
+    } else {
+      const result = await commandToExecute.execute(context, args ?? []);
+      logger.info('[CoreAgent] Sending /executeCommand response: ', result);
+      return res.status(200).json(result);
+    }
+  } catch (e) {
+    logger.error(
+      `Error executing /executeCommand: ${command} with args: ${JSON.stringify(
+        args,
+      )}`,
+      e,
+    );
+    const errorMessage =
+      e instanceof Error ? e.message : 'Unknown error executing command';
+    return res.status(500).json({ error: errorMessage });
+  }
+}
+
 export async function createApp() {
   try {
     // Load the server configuration once on startup.
@@ -85,6 +161,12 @@ export async function createApp() {
       'a2a-server',
     );
 
+    let git: GitService | undefined;
+    if (config.getCheckpointingEnabled()) {
+      git = new GitService(config.getTargetDir(), config.storage);
+      await git.initialize();
+    }
+
     // loadEnvironment() is called within getConfig now
     const bucketName = process.env['GCS_BUCKET_NAME'];
     let taskStoreForExecutor: TaskStore;
@@ -104,6 +186,8 @@ export async function createApp() {
 
     const agentExecutor = new CoderAgentExecutor(taskStoreForExecutor);
 
+    const context = { config, git, agentExecutor };
+
     const requestHandler = new DefaultRequestHandler(
       coderAgentCard,
       taskStoreForHandler,
@@ -143,36 +227,8 @@ export async function createApp() {
       }
     });
 
-    expressApp.post('/executeCommand', async (req, res) => {
-      try {
-        const { command, args } = req.body;
-
-        if (typeof command !== 'string') {
-          return res.status(400).json({ error: 'Invalid "command" field.' });
-        }
-
-        if (args && !Array.isArray(args)) {
-          return res
-            .status(400)
-            .json({ error: '"args" field must be an array.' });
-        }
-
-        const commandToExecute = commandRegistry.get(command);
-
-        if (!commandToExecute) {
-          return res
-            .status(404)
-            .json({ error: `Command not found: ${command}` });
-        }
-
-        const result = await commandToExecute.execute(config, args ?? []);
-        return res.status(200).json(result);
-      } catch (e) {
-        logger.error('Error executing /executeCommand:', e);
-        const errorMessage =
-          e instanceof Error ? e.message : 'Unknown error executing command';
-        return res.status(500).json({ error: errorMessage });
-      }
+    expressApp.post('/executeCommand', (req, res) => {
+      void handleExecuteCommand(req, res, context);
     });
 
     expressApp.get('/listCommands', (req, res) => {

packages/a2a-server/src/types.ts

@@ -46,6 +46,7 @@ export enum CoderAgentEvent {
 export interface AgentSettings {
   kind: CoderAgentEvent.StateAgentSettingsEvent;
   workspacePath: string;
+  autoExecute?: boolean;
 }
 
 export interface ToolCallConfirmation {

packages/a2a-server/src/utils/testing_utils.ts

@@ -11,6 +11,7 @@ import type {
 } from '@a2a-js/sdk';
 import {
   ApprovalMode,
+  DEFAULT_GEMINI_MODEL,
   DEFAULT_TRUNCATE_TOOL_OUTPUT_LINES,
   DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
   GeminiClient,
@@ -32,17 +33,21 @@ export function createMockConfig(
     }),
     getApprovalMode: vi.fn().mockReturnValue(ApprovalMode.DEFAULT),
     getIdeMode: vi.fn().mockReturnValue(false),
+    isInteractive: () => true,
     getAllowedTools: vi.fn().mockReturnValue([]),
     getWorkspaceContext: vi.fn().mockReturnValue({
       isPathWithinWorkspace: () => true,
     }),
     getTargetDir: () => '/test',
+    getCheckpointingEnabled: vi.fn().mockReturnValue(false),
     storage: {
       getProjectTempDir: () => '/tmp',
+      getProjectTempCheckpointsDir: () => '/tmp/checkpoints',
     } as Storage,
     getTruncateToolOutputThreshold: () =>
       DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
     getTruncateToolOutputLines: () => DEFAULT_TRUNCATE_TOOL_OUTPUT_LINES,
+    getActiveModel: vi.fn().mockReturnValue(DEFAULT_GEMINI_MODEL),
     getDebugMode: vi.fn().mockReturnValue(false),
     getContentGeneratorConfig: vi.fn().mockReturnValue({ model: 'gemini-pro' }),
     getModel: vi.fn().mockReturnValue('gemini-pro'),
@@ -62,6 +67,7 @@ export function createMockConfig(
     getMcpClientManager: vi.fn().mockReturnValue({
       getMcpServers: vi.fn().mockReturnValue({}),
     }),
+    getGitService: vi.fn(),
     ...overrides,
   } as unknown as Config;
   mockConfig.getMessageBus = vi.fn().mockReturnValue(createMockMessageBus());

packages/cli/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.20.0-nightly.20251201.2fe609cb6",
+  "version": "0.22.0-preview.1",
   "description": "Gemini CLI",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/google-gemini/gemini-cli.git"
@@ -25,7 +26,7 @@
     "dist"
   ],
   "config": {
-    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.20.0-nightly.20251201.2fe609cb6"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.22.0-preview.1"
   },
   "dependencies": {
     "@google/gemini-cli-core": "file:../core",

packages/cli/src/__snapshots__/nonInteractiveCli.test.ts.snap

@@ -4,7 +4,7 @@ exports[`runNonInteractive > should emit appropriate error event in streaming JS
 "{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
 {"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Loop test"}
 {"type":"error","timestamp":"<TIMESTAMP>","severity":"warning","message":"Loop detected, stopping execution"}
-{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"duration_ms":<DURATION>,"tool_calls":0}}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0}}
 "
 `;
 
@@ -12,7 +12,7 @@ exports[`runNonInteractive > should emit appropriate error event in streaming JS
 "{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
 {"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Max turns test"}
 {"type":"error","timestamp":"<TIMESTAMP>","severity":"error","message":"Maximum session turns exceeded"}
-{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"duration_ms":<DURATION>,"tool_calls":0}}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0}}
 "
 `;
 
@@ -23,7 +23,7 @@ exports[`runNonInteractive > should emit appropriate events for streaming JSON o
 {"type":"tool_use","timestamp":"<TIMESTAMP>","tool_name":"testTool","tool_id":"tool-1","parameters":{"arg1":"value1"}}
 {"type":"tool_result","timestamp":"<TIMESTAMP>","tool_id":"tool-1","status":"success","output":"Tool executed successfully"}
 {"type":"message","timestamp":"<TIMESTAMP>","role":"assistant","content":"Final answer","delta":true}
-{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"duration_ms":<DURATION>,"tool_calls":0}}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0}}
 "
 `;
 

packages/cli/src/commands/extensions.tsx

@@ -14,6 +14,7 @@ import { enableCommand } from './extensions/enable.js';
 import { linkCommand } from './extensions/link.js';
 import { newCommand } from './extensions/new.js';
 import { validateCommand } from './extensions/validate.js';
+import { settingsCommand } from './extensions/settings.js';
 import { initializeOutputListenersAndFlush } from '../gemini.js';
 
 export const extensionsCommand: CommandModule = {
@@ -32,6 +33,7 @@ export const extensionsCommand: CommandModule = {
       .command(linkCommand)
       .command(newCommand)
       .command(validateCommand)
+      .command(settingsCommand)
       .demandCommand(1, 'You need at least one command before continuing.')
       .version(false),
   handler: () => {

packages/cli/src/commands/extensions/disable.test.ts

@@ -14,7 +14,7 @@ import {
   type Mock,
 } from 'vitest';
 import { format } from 'node:util';
-import { type CommandModule, type Argv } from 'yargs';
+import { type Argv } from 'yargs';
 import { handleDisable, disableCommand } from './disable.js';
 import { ExtensionManager } from '../../config/extension-manager.js';
 import {
@@ -148,7 +148,7 @@ describe('extensions disable command', () => {
   });
 
   describe('disableCommand', () => {
-    const command = disableCommand as CommandModule;
+    const command = disableCommand;
 
     it('should have correct command and describe', () => {
       expect(command.command).toBe('disable [--scope] <name>');

packages/cli/src/commands/extensions/disable.ts

@@ -65,7 +65,7 @@ export const disableCommand: CommandModule = {
           argv.scope &&
           !Object.values(SettingScope)
             .map((s) => s.toLowerCase())
-            .includes((argv.scope as string).toLowerCase())
+            .includes(argv.scope.toLowerCase())
         ) {
           throw new Error(
             `Invalid scope: ${argv.scope}. Please use one of ${Object.values(

packages/cli/src/commands/extensions/enable.test.ts

@@ -14,7 +14,7 @@ import {
   type Mock,
 } from 'vitest';
 import { format } from 'node:util';
-import { type CommandModule, type Argv } from 'yargs';
+import { type Argv } from 'yargs';
 import { handleEnable, enableCommand } from './enable.js';
 import { ExtensionManager } from '../../config/extension-manager.js';
 import {
@@ -137,7 +137,7 @@ describe('extensions enable command', () => {
   });
 
   describe('enableCommand', () => {
-    const command = enableCommand as CommandModule;
+    const command = enableCommand;
 
     it('should have correct command and describe', () => {
       expect(command.command).toBe('enable [--scope] <name>');

packages/cli/src/commands/extensions/enable.ts

@@ -70,7 +70,7 @@ export const enableCommand: CommandModule = {
           argv.scope &&
           !Object.values(SettingScope)
             .map((s) => s.toLowerCase())
-            .includes((argv.scope as string).toLowerCase())
+            .includes(argv.scope.toLowerCase())
         ) {
           throw new Error(
             `Invalid scope: ${argv.scope}. Please use one of ${Object.values(

packages/cli/src/commands/extensions/examples/mcp-server/example.test.ts

@@ -4,15 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {
-  describe,
-  it,
-  expect,
-  vi,
-  beforeEach,
-  afterEach,
-  type Mock,
-} from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -90,7 +82,7 @@ describe('MCP Server Example', () => {
         json: vi.fn().mockResolvedValue(mockPosts),
       });
 
-      const toolFn = (mockRegisterTool as Mock).mock.calls[0][2];
+      const toolFn = mockRegisterTool.mock.calls[0][2];
       const result = await toolFn();
 
       expect(global.fetch).toHaveBeenCalledWith(
@@ -109,7 +101,7 @@ describe('MCP Server Example', () => {
 
   describe('poem-writer prompt implementation', () => {
     it('should generate a prompt with a title', () => {
-      const promptFn = (mockRegisterPrompt as Mock).mock.calls[0][2];
+      const promptFn = mockRegisterPrompt.mock.calls[0][2];
       const result = promptFn({ title: 'My Poem' });
       expect(result).toEqual({
         messages: [
@@ -125,7 +117,7 @@ describe('MCP Server Example', () => {
     });
 
     it('should generate a prompt with a title and mood', () => {
-      const promptFn = (mockRegisterPrompt as Mock).mock.calls[0][2];
+      const promptFn = mockRegisterPrompt.mock.calls[0][2];
       const result = promptFn({ title: 'My Poem', mood: 'sad' });
       expect(result).toEqual({
         messages: [

packages/cli/src/commands/extensions/link.test.ts

@@ -14,7 +14,7 @@ import {
   type Mock,
 } from 'vitest';
 import { format } from 'node:util';
-import { type CommandModule, type Argv } from 'yargs';
+import { type Argv } from 'yargs';
 import { handleLink, linkCommand } from './link.js';
 import { ExtensionManager } from '../../config/extension-manager.js';
 import { loadSettings, type LoadedSettings } from '../../config/settings.js';
@@ -126,7 +126,7 @@ describe('extensions link command', () => {
   });
 
   describe('linkCommand', () => {
-    const command = linkCommand as CommandModule;
+    const command = linkCommand;
 
     it('should have correct command and describe', () => {
       expect(command.command).toBe('link <path>');

packages/cli/src/commands/extensions/list.test.ts

@@ -6,7 +6,6 @@
 
 import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { format } from 'node:util';
-import { type CommandModule } from 'yargs';
 import { handleList, listCommand } from './list.js';
 import { ExtensionManager } from '../../config/extension-manager.js';
 import { loadSettings, type LoadedSettings } from '../../config/settings.js';
@@ -124,7 +123,7 @@ describe('extensions list command', () => {
   });
 
   describe('listCommand', () => {
-    const command = listCommand as CommandModule;
+    const command = listCommand;
 
     it('should have correct command and describe', () => {
       expect(command.command).toBe('list');

packages/cli/src/commands/extensions/settings.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import {
+  updateSetting,
+  promptForSetting,
+  ExtensionSettingScope,
+  getScopedEnvContents,
+} from '../../config/extensions/extensionSettings.js';
+import { getExtensionAndManager } from './utils.js';
+import { debugLogger } from '@google/gemini-cli-core';
+import { exitCli } from '../utils.js';
+
+// --- SET COMMAND ---
+interface SetArgs {
+  name: string;
+  setting: string;
+  scope: string;
+}
+
+const setCommand: CommandModule<object, SetArgs> = {
+  command: 'set [--scope] <name> <setting>',
+  describe: 'Set a specific setting for an extension.',
+  builder: (yargs) =>
+    yargs
+      .positional('name', {
+        describe: 'Name of the extension to configure.',
+        type: 'string',
+        demandOption: true,
+      })
+      .positional('setting', {
+        describe: 'The setting to configure (name or env var).',
+        type: 'string',
+        demandOption: true,
+      })
+      .option('scope', {
+        describe: 'The scope to set the setting in.',
+        type: 'string',
+        choices: ['user', 'workspace'],
+        default: 'user',
+      }),
+  handler: async (args) => {
+    const { name, setting, scope } = args;
+    const { extension, extensionManager } = await getExtensionAndManager(name);
+    if (!extension || !extensionManager) {
+      return;
+    }
+    const extensionConfig = extensionManager.loadExtensionConfig(
+      extension.path,
+    );
+    if (!extensionConfig) {
+      debugLogger.error(
+        `Could not find configuration for extension "${name}".`,
+      );
+      return;
+    }
+    await updateSetting(
+      extensionConfig,
+      extension.id,
+      setting,
+      promptForSetting,
+      scope as ExtensionSettingScope,
+    );
+    await exitCli();
+  },
+};
+
+// --- LIST COMMAND ---
+interface ListArgs {
+  name: string;
+}
+
+const listCommand: CommandModule<object, ListArgs> = {
+  command: 'list <name>',
+  describe: 'List all settings for an extension.',
+  builder: (yargs) =>
+    yargs.positional('name', {
+      describe: 'Name of the extension.',
+      type: 'string',
+      demandOption: true,
+    }),
+  handler: async (args) => {
+    const { name } = args;
+    const { extension, extensionManager } = await getExtensionAndManager(name);
+    if (!extension || !extensionManager) {
+      return;
+    }
+    const extensionConfig = extensionManager.loadExtensionConfig(
+      extension.path,
+    );
+    if (
+      !extensionConfig ||
+      !extensionConfig.settings ||
+      extensionConfig.settings.length === 0
+    ) {
+      debugLogger.log(`Extension "${name}" has no settings to configure.`);
+      return;
+    }
+
+    const userSettings = await getScopedEnvContents(
+      extensionConfig,
+      extension.id,
+      ExtensionSettingScope.USER,
+    );
+    const workspaceSettings = await getScopedEnvContents(
+      extensionConfig,
+      extension.id,
+      ExtensionSettingScope.WORKSPACE,
+    );
+    const mergedSettings = { ...userSettings, ...workspaceSettings };
+
+    debugLogger.log(`Settings for "${name}":`);
+    for (const setting of extensionConfig.settings) {
+      const value = mergedSettings[setting.envVar];
+      let displayValue: string;
+      let scopeInfo = '';
+
+      if (workspaceSettings[setting.envVar] !== undefined) {
+        scopeInfo = ' (workspace)';
+      } else if (userSettings[setting.envVar] !== undefined) {
+        scopeInfo = ' (user)';
+      }
+
+      if (value === undefined) {
+        displayValue = '[not set]';
+      } else if (setting.sensitive) {
+        displayValue = '[value stored in keychain]';
+      } else {
+        displayValue = value;
+      }
+      debugLogger.log(`
+- ${setting.name} (${setting.envVar})`);
+      debugLogger.log(`  Description: ${setting.description}`);
+      debugLogger.log(`  Value: ${displayValue}${scopeInfo}`);
+    }
+    await exitCli();
+  },
+};
+
+// --- SETTINGS COMMAND ---
+export const settingsCommand: CommandModule = {
+  command: 'settings <command>',
+  describe: 'Manage extension settings.',
+  builder: (yargs) =>
+    yargs
+      .command(setCommand)
+      .command(listCommand)
+      .demandCommand(1, 'You need to specify a command (set or list).')
+      .version(false),
+  handler: () => {
+    // This handler is not called when a subcommand is provided.
+    // Yargs will show the help menu.
+  },
+};

packages/cli/src/commands/extensions/uninstall.test.ts

@@ -14,7 +14,7 @@ import {
   type Mock,
 } from 'vitest';
 import { format } from 'node:util';
-import { type CommandModule, type Argv } from 'yargs';
+import { type Argv } from 'yargs';
 import { handleUninstall, uninstallCommand } from './uninstall.js';
 import { ExtensionManager } from '../../config/extension-manager.js';
 import { loadSettings, type LoadedSettings } from '../../config/settings.js';
@@ -233,7 +233,7 @@ describe('extensions uninstall command', () => {
   });
 
   describe('uninstallCommand', () => {
-    const command = uninstallCommand as CommandModule;
+    const command = uninstallCommand;
 
     it('should have correct command and describe', () => {
       expect(command.command).toBe('uninstall <names..>');