chore(release): v0.17.0-preview.4

Co-authored-by: Gaurav Sehgal <sehgalgaurav@google.com>

.gemini/commands/review-frontend.toml

@@ -0,0 +1,140 @@
+description="Reviews a pull request based on issue number."
+prompt = """
+Please provide a detailed pull request review on GitHub issue: {{args}}.
+
+Follow these steps:
+
+1. Use `gh pr view {{args}}` to pull the information of the PR.
+2. Use `gh pr diff {{args}}` to view the diff of the PR.
+3. Understand the intent of the PR using the PR description.
+4. If PR description is not detailed enough to understand the intent of the PR,
+   make sure to note it in your review.
+5. Make sure the PR title follows Conventional Commits, here are the last five
+   commits to the repo as examples: !{git log --pretty=format:"%s" -n 5}
+6. Search the codebase if required.
+7. Write a concise review of the PR, keeping in mind to encourage strong code
+   quality and best practices. Pay particular attention to the Gemini MD file
+   in the repo.
+8. Consider ways the code may not be consistent with existing code in the repo.
+   In particular it is critical that the react code uses patterns consistent
+   with existing code in the repo.
+9. Evaluate all tests on the PR and make sure that they are doing the following:
+   * Using `waitFor` from @{packages/cli/src/test-utils/async.ts} rather than
+     using `vi.waitFor` for all `waitFor` calls within `packages/cli`. Even if
+     tests pass, using the wrong `waitFor` could result in flaky tests as `act`
+     warnings could show up if timing is slightly different.
+   * Using `act` to wrap all blocks in tests that change component state.
+   * Using `toMatchSnapshot` to verify that rendering works as expected rather
+     than matching against the raw content of the output.
+   * If snapshots were changed as part of the pull request, review the snapshots
+     changes to ensure they are intentional and comment if any look at all
+     suspicious. Too many snapshot changes that indicate bugs have been approved
+     in the past.
+   * Use `render` or `renderWithProviders` from
+     @{packages/cli/src/test-utils/render.tsx} rather than using `render` from
+     `ink-testing-library` directly. This is needed to ensure that we do not get
+     warnings about spurious `act` calls. If test cases specify providers
+     directly, consider whether the existing `renderWithProviders` should be
+     modified to support that use case.
+   * Ensure the test cases are using parameterized tests where that might reduce
+     the number of duplicated lines significantly.
+   * NEVER use fixed waits (e.g. 'await delay(100)'). Always use 'waitFor' with
+     a predicate to ensure tests are stable and fast.
+   * Ensure mocks are properly managed:
+     * Critical dependencies (fs, os, child_process) should only be mocked at
+       the top of the file. Ideally avoid mocking these dependencies altogether.
+     * Check to see if there are existing mocks or fakes that can be used rather
+       than creating new ones for the new tests added.
+     * Try to avoid mocking the file system whenever possible. If using the real
+       file system is difficult consider whether the test should be an
+       integration test rather than a unit test.
+     * `vi.restoreAllMocks()` should be called in `afterEach` to prevent test
+       pollution.
+     * Use `vi.useFakeTimers()` for tests involving time-based logic to avoid
+       flakiness.
+     * Avoid using `any` in tests; prefer proper types or `unknown` with
+       narrowing.
+     * When creating parameterized tests, give the parameters types to ensure
+       that the tests are type-safe.
+10. Evaluate all react logic carefully keeping in mind that the author of the PR
+    is not likely an expert on React. Key areas to audit carefully are:
+    * Whether `setState` calls trigger side effects from within the body of the
+      `setState` callback. If so, you *must* propose an alternate design using
+      reducers or other ways the code might be modified to not have to modify
+      state from within a `setState`. Make sure to comment about absolutely
+      every case like this as these cases have introduced multiple bugs in the
+      past. Typically these cases should be resolved using a reducer although
+      occassionally other techniques such as useRef are appropriate. Consider
+      suggesting that jacob314@ be tagged on the code review if the solution is
+      not 100% obvious.
+    * Whether code might introduce an infinite rendering loop in React.
+    * Whether keyboard handling is robust. Keyboard handling must go through
+      `useKeyPress.ts` from the Gemini CLI package rather than using the
+      standard ink library used by most keyboard handling. Unlike the standard
+      ink library, the keyboard handling library in Gemini CLI may report
+      multiple keyboard events one after another in the same React frame. This
+      is needed to support slow terminals but introduces complexity in all our
+      code that handles keyboard events. Handling this correctly often means
+      that reducers must be used or other mechanisms to ensure that multiple
+      state updates one after another are handled gracefully rather than
+      overriding values from the first update with the second update. Refer to
+      text-buffer.ts as a canonical example of using a reducer for this sort of
+      case.
+    * Ensure code does not use `console.log`, `console.warn`, or `console.error`
+      as these indicate debug logging that was accidentally left in the code.
+    * Avoid synchronous file I/O in React components as it will hang the UI.
+    * Ensure state initialization is explicit (e.g., use 'undefined' rather than
+      'true' as a default if the state is truly unknown initially).
+    * Carefully manage 'useEffect' dependencies. Prefer to use a reducer
+      whenever practical to resolve the issues. If that is not practical it is
+      ok to use 'useRef' to access the latest value of a prop or state inside an
+      effect without adding it to the dependency array if re-running the effect
+      is undesirable (common in event listeners).
+    * NEVER disable 'react-hooks/exhaustive-deps'. Fix the code to correctly
+      declare dependencies. Disabling this lint rule will almost always lead to
+      hard to detect bugs.
+    * Avoid making types nullable unless strictly necessary, as it hurts
+      readability.
+    * Do not introduce excessive property drilling. There are multiple providers
+      that can be leveraged to avoid property drilling. Make sure one of them
+      cannot be used. Do suggest a provider that might make sense to be extended
+      to include the new property or propose a new provider to add if the
+      property drilling is excessive. Only use providers for properties that are
+      consistent for the entire application.
+11. General Gemini CLI design principles:
+    * Make sure that settings are only used for options that a user might
+      consider changing.
+    * Do not add new command line arguments and suggest settings instead.
+    * New settings must be added to packages/cli/src/config/settingsSchema.ts.
+    * If a setting has 'showInDialog: true', it MUST be documented in
+      docs/get-started/configuration.md.
+    * Ensure 'requiresRestart' is correctly set for new settings.
+    * Use 'debugLogger' for rethrown errors to avoid duplicate logging.
+    * All new keyboard shortcuts MUST be documented in
+      docs/cli/keyboard-shortcuts.md.
+    * Ensure new keyboard shortcuts are defined in
+      packages/cli/src/config/keyBindings.ts.
+    * If new keyboard shortcuts are added, remind the user to test them in
+      VSCode, iTerm2, Ghostty, and Windows to ensure they work for all
+      users.
+    * Be careful of keybindings that require the meta key as only certain
+      meta key shortcuts are supported on Mac.
+    * Be skeptical of function keys and keyboard shortcuts that are commonly
+      bound in VSCode as they may conflict.
+12. TypeScript Best Practices:
+    * Use 'checkExhaustive' in the 'default' clause of 'switch' statements to
+      ensure all cases are handled.
+    * Avoid using the non-null assertion operator ('!') unless absolutely
+      necessary and you are confident the value is not null.
+13. If the change might at all impact the prompts sent to Gemini CLI, flagged
+    that the change could impact Gemini CLI quality and make sure anj-s has been
+    tagged on the code review.
+14. Discuss with me before making any comments on the issue. I will clarify
+    which possible issues you identified are problems, which ones you need to
+    investigate further, and which ones I do not care about.
+15. If I request you to add comments to the issue, use
+    `gh pr comment {{args}} --body {{review}}` to post the review to the PR.
+
+Remember to use the GitHub CLI (`gh`) with the Shell tool for all
+GitHub-related tasks.
+"""

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,8 +1,8 @@
 name: 'Bug Report'
 description: 'Report a bug to help us improve Gemini CLI'
 labels:
-  - 'kind/bug'
   - 'status/need-triage'
+type: 'Bug'
 body:
   - type: 'markdown'
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,8 +1,8 @@
 name: 'Feature Request'
 description: 'Suggest an idea for this project'
 labels:
-  - 'kind/enhancement'
   - 'status/need-triage'
+type: 'Feature'
 body:
   - type: 'markdown'
     attributes:

.github/ISSUE_TEMPLATE/website_issue.yml

@@ -1,8 +1,7 @@
 name: 'Website issue'
 description: 'Report an issue with the Gemini CLI Website and Gemini CLI Extensions Gallery'
 labels:
-  - 'area/website'
-  - 'status/need-triage'
+  - 'area/extensions'
 body:
   - type: 'markdown'
     attributes:

.github/actions/publish-release/action.yml

@@ -166,6 +166,7 @@ runs:
           --dry-run="${{ inputs.dry-run }}" \
           --workspace="${{ inputs.core-package-name }}" \
           --no-tag
+        npm dist-tag rm ${{ inputs.core-package-name }} false --silent
 
     - name: '🔗 Install latest core package'
       working-directory: '${{ inputs.working-directory }}'
@@ -197,6 +198,7 @@ runs:
           --dry-run="${{ inputs.dry-run }}" \
           --workspace="${{ inputs.cli-package-name }}" \
           --no-tag
+        npm dist-tag rm ${{ inputs.cli-package-name }} false --silent
 
     - name: 'Get a2a-server Token'
       uses: './.github/actions/npm-auth-token'
@@ -218,7 +220,8 @@ runs:
         npm publish \
           --dry-run="${{ inputs.dry-run }}" \
           --workspace="${{ inputs.a2a-package-name }}" \
-          --no-TARGET_TAG
+          --no-tag
+        npm dist-tag rm ${{ inputs.a2a-package-name }} false --silent
 
     - name: '🔬 Verify NPM release by version'
       uses: './.github/actions/verify-release'
@@ -226,7 +229,7 @@ runs:
       with:
         npm-package: '${{ inputs.cli-package-name }}@${{ inputs.release-version }}'
         expected-version: '${{ inputs.release-version }}'
-        ref: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
+        working-directory: '${{ inputs.working-directory }}'
         gemini_api_key: '${{ inputs.gemini_api_key }}'
         github-token: '${{ inputs.github-token }}'
         npm-registry-url: '${{ inputs.npm-registry-url }}'
@@ -234,7 +237,6 @@ runs:
 
     - name: '🏷️ Tag release'
       uses: './.github/actions/tag-npm-release'
-      if: "${{ inputs.dry-run != 'true' }}"
       with:
         channel: '${{ inputs.npm-tag }}'
         version: '${{ inputs.release-version }}'
@@ -246,6 +248,7 @@ runs:
         cli-package-name: '${{ inputs.cli-package-name }}'
         core-package-name: '${{ inputs.core-package-name }}'
         a2a-package-name: '${{ inputs.a2a-package-name }}'
+        working-directory: '${{ inputs.working-directory }}'
 
     - name: '🎉 Create GitHub Release'
       working-directory: '${{ inputs.working-directory }}'

.github/actions/tag-npm-release/action.yml

@@ -32,11 +32,10 @@ inputs:
   a2a-package-name:
     description: 'The name of the a2a package.'
     required: true
-  ref:
-    description: 'The branch, tag, or SHA to release from.'
+  working-directory:
+    description: 'The working directory to run the commands in.'
     required: false
-    type: 'string'
-    default: 'main'
+    default: '.'
 
 runs:
   using: 'composite'
@@ -47,16 +46,10 @@ runs:
         JSON_INPUTS: '${{ toJSON(inputs) }}'
       run: 'echo "$JSON_INPUTS"'
 
-    - name: 'Checkout'
-      uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v4
-      with:
-        ref: '${{ github.event.inputs.ref }}'
-        fetch-depth: 0
-
     - name: 'Setup Node.js'
       uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020'
       with:
-        node-version-file: '.nvmrc'
+        node-version-file: '${{ inputs.working-directory }}/.nvmrc'
 
     - name: 'configure .npmrc'
       uses: './.github/actions/setup-npmrc'
@@ -79,6 +72,7 @@ runs:
       env:
         NODE_AUTH_TOKEN: '${{ steps.core-token.outputs.auth-token }}'
       shell: 'bash'
+      working-directory: '${{ inputs.working-directory }}'
       run: |
         npm dist-tag add ${{ inputs.core-package-name }}@${{ inputs.version }} ${{ inputs.channel }}
 
@@ -98,21 +92,34 @@ runs:
       env:
         NODE_AUTH_TOKEN: '${{ steps.cli-token.outputs.auth-token }}'
       shell: 'bash'
+      working-directory: '${{ inputs.working-directory }}'
       run: |
         npm dist-tag add ${{ inputs.cli-package-name }}@${{ inputs.version }} ${{ inputs.channel }}
 
-    - name: 'Change tag for @google/gemini-cli-a2a-server'
+    - name: 'Get a2a Token'
+      uses: './.github/actions/npm-auth-token'
+      id: 'a2a-token'
+      with:
+        package-name: '${{ inputs.a2a-package-name }}'
+        github-token: '${{ inputs.github-token }}'
+        wombat-token-core: '${{ inputs.wombat-token-core }}'
+        wombat-token-cli: '${{ inputs.wombat-token-cli }}'
+        wombat-token-a2a-server: '${{ inputs.wombat-token-a2a-server }}'
+
+    - name: 'Change tag for a2a'
       if: |-
         ${{ inputs.dry-run == 'false' }}
       env:
-        NODE_AUTH_TOKEN: '${{ inputs.wombat-token-a2a-server }}'
+        NODE_AUTH_TOKEN: '${{ steps.a2a-token.outputs.auth-token }}'
       shell: 'bash'
+      working-directory: '${{ inputs.working-directory }}'
       run: |
-        npm dist-tag add @google/gemini-cli-a2a-server@${{ inputs.version }} ${{ inputs.channel }}
+        npm dist-tag add ${{ inputs.a2a-package-name }}@${{ inputs.version }} ${{ inputs.channel }}
 
     - name: 'Log dry run'
       if: |-
         ${{ inputs.dry-run == 'true' }}
       shell: 'bash'
+      working-directory: '${{ inputs.working-directory }}'
       run: |
-        echo "Dry run: Would have added tag '${{ inputs.channel }}' to version '${{ inputs.version }}' for @google/gemini-cli and @google/gemini-cli-core."
+        echo "Dry run: Would have added tag '${{ inputs.channel }}' to version '${{ inputs.version }}' for ${{ inputs.cli-package-name }}, ${{ inputs.core-package-name }}, and ${{ inputs.a2a-package-name }}."

.github/actions/verify-release/action.yml

@@ -21,11 +21,10 @@ inputs:
   github-token:
     description: 'The GitHub token for running integration tests.'
     required: true
-  ref:
-    description: 'The branch, tag, or SHA to release from.'
+  working-directory:
+    description: 'The working directory to run the tests in.'
     required: false
-    type: 'string'
-    default: 'main'
+    default: '.'
 
 runs:
   using: 'composite'
@@ -36,13 +35,6 @@ runs:
         JSON_INPUTS: '${{ toJSON(inputs) }}'
       run: 'echo "$JSON_INPUTS"'
 
-    - name: 'Checkout'
-      uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v4
-      with:
-        path: 'verify'
-        ref: '${{ github.event.inputs.ref }}'
-        fetch-depth: 0
-
     - name: 'setup node'
       uses: 'actions/setup-node@v4'
       with:
@@ -64,12 +56,12 @@ runs:
         retry_wait_seconds: 30
         max_attempts: 10
         command: |-
-          cd ./verify
+          cd ${{ inputs.working-directory }}
           npm install --prefer-online --no-cache -g "${{ inputs.npm-package }}"
 
     - name: 'Smoke test - NPM Install'
       shell: 'bash'
-      working-directory: './verify'
+      working-directory: '${{ inputs.working-directory }}'
       run: |-
         gemini_version=$(gemini --version)
         if [ "$gemini_version" != "${{ inputs.expected-version }}" ]; then
@@ -83,7 +75,7 @@ runs:
 
     - name: 'Smoke test - NPX Run'
       shell: 'bash'
-      working-directory: './verify'
+      working-directory: '${{ inputs.working-directory }}'
       run: |-
         gemini_version=$(npx --prefer-online "${{ inputs.npm-package}}" --version)
         if [ "$gemini_version" != "${{ inputs.expected-version }}" ]; then
@@ -93,11 +85,11 @@ runs:
 
     - name: 'Install dependencies for integration tests'
       shell: 'bash'
-      working-directory: './verify'
+      working-directory: '${{ inputs.working-directory }}'
       run: 'npm ci'
 
     - name: '🔬 Run integration tests against NPM release'
-      working-directory: './verify'
+      working-directory: '${{ inputs.working-directory }}'
       env:
         GEMINI_API_KEY: '${{ inputs.gemini_api_key }}'
         INTEGRATION_TEST_USE_INSTALLED_GEMINI: 'true'

.github/pull_request_template.md

@@ -1,41 +1,42 @@
-## TLDR
+## Summary
 
-<!-- Add a brief description of what this pull request changes and why and any important things for reviewers to look at -->
+<!-- Concisely describe what this PR changes and why. Focus on impact and
+urgency. -->
 
-## Dive Deeper
+## Details
 
-<!-- more thoughts and in-depth discussion here -->
+<!-- Add any extra context and design decisions. Keep it brief but complete. -->
 
-## Reviewer Test Plan
+## Related Issues
 
-<!-- when a person reviews your code they should ideally be pulling and running that code. How would they validate your change works and if relevant what are some good classes of example prompts and ways they can exercise your changes -->
+<!-- Use keywords to auto-close issues (Closes #123, Fixes #456). If this PR is
+only related to an issue or is a partial fix, simply reference the issue number
+without a keyword (Related to #123). -->
 
-## Testing Matrix
+## How to Validate
 
-<!-- Before submitting please validate your changes on as many of these options as possible -->
+<!-- List exact steps for reviewers to validate the change. Include commands,
+expected results, and edge cases. -->
 
-|          | 🍏  | 🪟  | 🐧  |
-| -------- | --- | --- | --- |
-| npm run  | ❓  | ❓  | ❓  |
-| npx      | ❓  | ❓  | ❓  |
-| Docker   | ❓  | ❓  | ❓  |
-| Podman   | ❓  | -   | -   |
-| Seatbelt | ❓  | -   | -   |
+## Pre-Merge Checklist
 
-## Linked issues / bugs
+<!-- Check all that apply before requesting review or merging. -->
 
-<!--
-Link to any related issues or bugs.
-
-**If this PR fully resolves the issue, use one of the following keywords to automatically close the issue when this PR is merged:**
-
-- Closes #<issue_number>
-- Fixes #<issue_number>
-- Resolves #<issue_number>
-
-*Example: `Resolves #123`*
-
-**If this PR is only related to an issue or is a partial fix, simply reference the issue number without a keyword:**
-
-*Example: `This PR makes progress on #456` or `Related to #789`*
--->
+- [ ] Updated relevant documentation and README (if needed)
+- [ ] Added/updated tests (if needed)
+- [ ] Noted breaking changes (if any)
+- [ ] Validated on required platforms/methods:
+  - [ ] MacOS
+    - [ ] npm run
+    - [ ] npx
+    - [ ] Docker
+    - [ ] Podman
+    - [ ] Seatbelt
+  - [ ] Windows
+    - [ ] npm run
+    - [ ] npx
+    - [ ] Docker
+  - [ ] Linux
+    - [ ] npm run
+    - [ ] npx
+    - [ ] Docker

.github/workflows/ci.yml

@@ -66,6 +66,9 @@ jobs:
       - name: 'Install dependencies'
         run: 'npm ci'
 
+      - name: 'Validate NOTICES.txt'
+        run: 'git diff --exit-code packages/vscode-ide-companion/NOTICES.txt'
+
       - name: 'Check lockfile'
         run: 'npm run check:lockfile'
 
@@ -87,9 +90,26 @@ jobs:
       - name: 'Run Prettier'
         run: 'node scripts/lint.js --prettier'
 
+      - name: 'Build docs prerequisites'
+        run: 'npm run predocs:settings'
+
+      - name: 'Verify settings docs'
+        run: 'npm run docs:settings -- --check'
+
       - name: 'Run sensitive keyword linter'
         run: 'node scripts/lint.js --sensitive-keywords'
 
+  link_checker:
+    name: 'Link Checker'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
+      - name: 'Link Checker'
+        uses: 'lycheeverse/lychee-action@885c65f3dc543b57c898c8099f4e08c8afd178a2' # ratchet: lycheeverse/lychee-action@v2.6.1
+        with:
+          args: '--verbose ./**/*.md'
+          fail: true
   test_linux:
     name: 'Test (Linux)'
     runs-on: 'gemini-cli-ubuntu-16-core'
@@ -351,6 +371,7 @@ jobs:
     if: 'always()'
     needs:
       - 'lint'
+      - 'link_checker'
       - 'test_linux'
       - 'test_mac'
       - 'codeql'
@@ -360,6 +381,7 @@ jobs:
       - name: 'Check all job results'
         run: |
           if [[ (${{ needs.lint.result }} != 'success' && ${{ needs.lint.result }} != 'skipped') || \
+               (${{ needs.link_checker.result }} != 'success' && ${{ needs.link_checker.result }} != 'skipped') || \
                (${{ needs.test_linux.result }} != 'success' && ${{ needs.test_linux.result }} != 'skipped') || \
                (${{ needs.test_mac.result }} != 'success' && ${{ needs.test_mac.result }} != 'skipped') || \
                (${{ needs.codeql.result }} != 'success' && ${{ needs.codeql.result }} != 'skipped') || \

.github/workflows/deflake.yml

@@ -0,0 +1,170 @@
+name: 'Deflake E2E'
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch_ref:
+        description: 'Branch to run on'
+        required: true
+        default: 'main'
+        type: 'string'
+      test_name_pattern:
+        description: 'The test name pattern to use'
+        required: false
+        type: 'string'
+      runs:
+        description: 'The number of runs'
+        required: false
+        default: 5
+        type: 'number'
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: |-
+    ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/heads/release/') }}
+
+jobs:
+  deflake_e2e_linux:
+    name: 'E2E Test (Linux) - ${{ matrix.sandbox }}'
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    strategy:
+      fail-fast: false
+      matrix:
+        sandbox:
+          - 'sandbox:none'
+          - 'sandbox:docker'
+        node-version:
+          - '20.x'
+
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ github.event.pull_request.head.sha }}'
+          repository: '${{ github.repository }}'
+
+      - 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 }}'
+          IS_DOCKER: "${{ matrix.sandbox == 'sandbox:docker' }}"
+          KEEP_OUTPUT: 'true'
+          RUNS: '${{ github.event.inputs.runs }}'
+          TEST_NAME_PATTERN: '${{ github.event.inputs.test_name_pattern }}'
+          VERBOSE: 'true'
+        shell: 'bash'
+        run: |
+          if [[ "${{ env.IS_DOCKER }}" == "true" ]]; then
+            npm run deflake:test:integration:sandbox:docker -- --runs="${{ env.RUNS }}" -- --testNamePattern "'${{ env.TEST_NAME_PATTERN }}'"
+          else
+            npm run deflake:test:integration:sandbox:none -- --runs="${{ env.RUNS }}" -- --testNamePattern "'${{ env.TEST_NAME_PATTERN }}'"
+          fi
+
+  deflake_e2e_mac:
+    name: 'E2E Test (macOS)'
+    runs-on: 'macos-latest'
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ github.event.pull_request.head.sha }}'
+          repository: '${{ github.repository }}'
+
+      - 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'
+          RUNS: '${{ github.event.inputs.runs }}'
+          SANDBOX: 'sandbox:none'
+          TEST_NAME_PATTERN: '${{ github.event.inputs.test_name_pattern }}'
+          VERBOSE: 'true'
+        run: |
+          npm run deflake:test:integration:sandbox:none -- --runs="${{ env.RUNS }}" -- --testNamePattern "'${{ env.TEST_NAME_PATTERN }}'"
+
+  deflake_e2e_windows:
+    name: 'Slow E2E - Win'
+    runs-on: 'gemini-cli-windows-16-core'
+
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ github.event.pull_request.head.sha }}'
+          repository: '${{ github.repository }}'
+
+      - 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'
+          RUNS: '${{ github.event.inputs.runs }}'
+          TEST_NAME_PATTERN: '${{ github.event.inputs.test_name_pattern }}'
+        shell: 'pwsh'
+        run: |
+          npm run deflake:test:integration:sandbox:none -- --runs="${{ env.RUNS }}" -- --testNamePattern "'${{ env.TEST_NAME_PATTERN }}'"

.github/workflows/e2e.yml

@@ -30,6 +30,7 @@ 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:
@@ -37,12 +38,13 @@ jobs:
         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.outputs.skip == 'false' &&
+      (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' ||
@@ -104,7 +106,7 @@ jobs:
     name: 'E2E Test (macOS)'
     needs: 'merge_queue_skipper'
     if: |
-      needs.merge_queue_skipper.outputs.skip == 'false' &&
+      (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' ||
@@ -153,7 +155,7 @@ jobs:
     name: 'Slow E2E - Win'
     needs: 'merge_queue_skipper'
     if: |
-      needs.merge_queue_skipper.outputs.skip == 'false' &&
+      (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/workflows/eval.yml

@@ -33,7 +33,7 @@ jobs:
     steps:
       - name: 'Authenticate to Google Cloud'
         id: 'auth'
-        uses: 'google-github-actions/auth@v2' # ratchet:exclude
+        uses: 'google-github-actions/auth@c200f3691d83b41bf9bbd8638997a462592937ed' # ratchet:exclude pin@v2.1.7
         with:
           project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
           workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'

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

@@ -45,7 +45,9 @@ jobs:
             (github.event.comment.author_association == 'OWNER' || github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'COLLABORATOR')
           ))
         )
-      )
+      ) &&
+      !contains(github.event.issue.labels.*.name, 'area/') &&
+      !contains(github.event.issue.labels.*.name, 'priority/')
     timeout-minutes: 5
     runs-on: 'ubuntu-latest'
     steps:
@@ -67,12 +69,24 @@ jobs:
             core.setOutput('labels', issue.labels.map(label => label.name).join(','));
             return issue;
 
-      - name: 'Check for triage label on manual trigger'
+      - name: 'Manual Trigger Pre-flight Checks'
         if: |-
-          github.event_name == 'workflow_dispatch' && !contains(steps.get_issue_data.outputs.labels, 'status/need-triage')
+          github.event_name == 'workflow_dispatch'
+        env:
+          ISSUE_NUMBER_INPUT: '${{ github.event.inputs.issue_number }}'
+          LABELS: '${{ steps.get_issue_data.outputs.labels }}'
         run: |
-          echo "Issue #${{ github.event.inputs.issue_number }} does not have the 'status/need-triage' label. Stopping workflow."
-          exit 1
+          if ! echo "${LABELS}" | grep -q 'status/need-triage'; then
+            echo "Issue #${ISSUE_NUMBER_INPUT} does not have the 'status/need-triage' label. Stopping workflow."
+            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."
+            exit 1
+          fi
+
+          echo "Manual triage checks passed."
 
       - name: 'Checkout'
         uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
@@ -95,7 +109,22 @@ jobs:
               owner: context.repo.owner,
               repo: context.repo.repo,
             });
-            const labelNames = labels.map(label => label.name);
+            const allowedLabels = [
+              'priority/p0',
+              'priority/p1',
+              'priority/p2',
+              'priority/p3',
+              'priority/unknown',
+              'area/agent',
+              'area/enterprise',
+              'area/non-interactive',
+              'area/core',
+              'area/security',
+              'area/platform',
+              'area/extensions',
+              'area/unknown'
+            ];
+            const labelNames = labels.map(label => label.name).filter(name => allowedLabels.includes(name));
             core.setOutput('available_labels', labelNames.join(','));
             core.info(`Found ${labelNames.length} labels: ${labelNames.join(', ')}`);
             return labelNames;
@@ -124,9 +153,6 @@ jobs:
           settings: |-
             {
               "maxSessionTurns": 25,
-              "coreTools": [
-                "run_shell_command(echo)"
-              ],
               "telemetry": {
                 "enabled": true,
                 "target": "gcp"
@@ -135,128 +161,134 @@ jobs:
           prompt: |-
             ## Role
 
-            You are an issue triage assistant. Analyze the current GitHub issue
-            and identify the most appropriate existing labels by only using the provided data. Use the available
-            tools to gather information; do not ask for information to be
-            provided. Do not remove the following labels titled maintainer,  help wanted or good first issue.
+            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.
 
             ## Steps
-
-            1. You are only able to use the echo command. Review the available labels in the environment variable: "${AVAILABLE_LABELS}".
-            2. Review the issue title and body provided in the environment variables: "${ISSUE_TITLE}" and "${ISSUE_BODY}".
-            3. Select the most relevant labels from the existing labels, focusing on kind/*, area/*, sub-area/* and priority/*. For area/* and kind/* limit yourself to only the single most applicable label in each case.
-            4. If the issue already has area/ label, dont try to change it. Similarly, if the issue already has a kind/ label don't change it. And if the issue already has a priority/ label do not change it for example:
-               If an issue has area/core and kind/bug  you will only add a priority/ label.
-               Instead if an issue has no labels, you will could add one lable of each kind.
-            5. For each issue please check if CLI version is present, this is usually in the output of the /about command and will look like 0.1.5 for anything more than 6 versions older than the most recent should add the status/need-retesting label.
-            6. If you see that the issue doesn't look like it has sufficient information recommend the status/need-information label and leave a comment politely requesting the relevant information, eg.. if repro steps are missing request for repro steps. if version information is missing request for version information into the explanation section below.
-            7. Output the appropriate labels for this issue in JSON format with explanation, for example:
-               ```
-               {"labels_to_set": ["kind/bug", "priority/p0"], "explanation": "This is a critical bug report affecting main functionality"}
-               ```
-            8. If the issue cannot be classified using the available labels, output:
-               ```
-               {"labels_to_set": [], "explanation": "Unable to classify this issue with available labels"}
-               ```
-            9. Use Area definitions mentioned below to help you narrow down issues.
-            10. If you think an issue might be a Priority/P0 do not apply the priority/p0 label. Instead apply a status/manual-triage label and include a note in your explanation.
-            11. If you are uncertain and have not been able to apply one each of kind/, area/ and priority/ , apply the status/manual-triage label.
+            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:
+                - 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"]}
 
             ## Guidelines
+            - Your output must contain exactly one area/ label and exactly one priority/ 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.
 
-            - Only use labels that already exist in the repository
-            - Do not add comments or modify the issue content
-            - Triage only the current issue
-            - Identify only one area/ label
-            - Identify only one kind/ label
-            - Identify all applicable sub-area/* and priority/* labels based on the issue content. It's ok to have multiple of these
-            - Once you categorize the issue if it needs information bump down the priority by 1 eg.. a p0 would become a p1 a p1 would become a p2. P2 and P3 can stay as is in this scenario
-            - Reference all shell variables as "${VAR}" (with quotes and braces)
-            - Output only valid JSON format
-            - Do not include any explanation or additional text, just the JSON
+            Reference 1: Area Definitions
+            area/agent
+            - Description: Issues related to the "brain" of the CLI. This includes the core agent logic, model quality, tool/function calling, and memory.
+            - Example Issues:
+              "I am not getting a reasonable or expected response."
+              "The model is not calling the tool I expected."
+              "The web search tool is not working as expected."
+              "Feature request for a new built-in tool (e.g., read file, write file)."
+              "The generated code is poor quality or incorrect."
+              "The model seems stuck in a loop."
+              "The response from the model is malformed (e.g., broken JSON, bad formatting)."
+              "Concerns about unnecessary token consumption."
+              "Issues with how memory or chat history is managed."
+              "Issues with sub-agents."
+              "Model is switching from one to another unexpectedly."
 
-            Categorization Guidelines:
-            P0: Critical / Blocker
-            - A P0 bug is a catastrophic failure that demands immediate attention.
-            - To be a P0 it means almost all users are running into this issue and it is blocking users from being able to use the product.
-            - You would see this in the form of many comments from different developers on the bug.
-            - It represents a complete showstopper for a significant portion of users or for the development process itself.
-            Impact:
-            - Blocks development or testing for the entire team.
-            - Major security vulnerability that could compromise user data or system integrity.
-            - Causes data loss or corruption with no workaround.
-            - Crashes the application or makes a core feature completely unusable for all or most users in a production environment. Will it cause severe quality degration? Is it preventing contributors from contributing to the repository or is it a release blocker?
-            Qualifier: Is the main function of the software broken?
-            Example: The gemini auth login command fails with an unrecoverable error, preventing any user from authenticating and using the rest of the CLI.
-            P1: High
-            - A P1 bug is a serious issue that significantly degrades the user experience or impacts a core feature.
-            - While not a complete blocker, it's a major problem that needs a fast resolution. Feature requests are almost never P1.
-            - Once again this would be affecting many users.
-            - You would see this in the form of comments from different developers on the bug.
-            Impact:
-            - A core feature is broken or behaving incorrectly for a large number of users or large number of use cases.
-            - Review the bug details and comments to try figure out if this issue affects a large set of use cases or if it's a narrow set of use cases.
-            - Severe performance degradation making the application frustratingly slow.
-            - No straightforward workaround exists, or the workaround is difficult and non-obvious.
-            Qualifier: Is a key feature unusable or giving very wrong results?
-            Example: Gemini CLI enters a loop when making read-many-files tool call. I am unable to break out of the loop and gemini doesn't follow instructions subsequently.
-            P2: Medium
-            - A P2 bug is a moderately impactful issue. It's a noticeable problem but doesn't prevent the use of the software's main functionality.
-            Impact:
-            - Affects a non-critical feature or a smaller, specific subset of users.
-            - An inconvenient but functional workaround is available and easy to execute.
-            - Noticeable UI/UX problems that don't break functionality but look unprofessional (e.g., elements are misaligned or overlapping).
-            Qualifier: Is it an annoying but non-blocking problem?
-            Example: An error message is unclear or contains a typo, causing user confusion but not halting their workflow.
-            P3: Low
-            - A P3 bug is a minor, low-impact issue that is trivial or cosmetic. It has little to no effect on the overall functionality of the application.
-            Impact:
-            - Minor cosmetic issues like color inconsistencies, typos in documentation, or slight alignment problems on a non-critical page.
-            - An edge-case bug that is very difficult to reproduce and affects a tiny fraction of users.
-            Qualifier: Is it a "nice-to-fix" issue?
-            Example: Spelling mistakes etc.
-            Things you should know:
-            - If users are talking about issues where the model gets downgraded from pro to flash then i want you to categorize that as a performance issue
-            - This product is designed to use different models eg.. using pro, downgrading to flash etc. when users report that they dont expect the model to change those would be categorized as feature requests.
-            Definition of Areas
-            area/ux:
-            - Issues concerning user-facing elements like command usability, interactive features, help docs, and perceived performance.
-            - I am seeing my screen flicker when using Gemini CLI
-            - I am seeing the output malformed
-            - Theme changes aren't taking effect
-            - My keyboard inputs arent' being recognzied
-            area/platform:
-            - Issues related to installation, packaging, OS compatibility (Windows, macOS, Linux), and the underlying CLI framework.
-            area/background: Issues related to long-running background tasks, daemons, and autonomous or proactive agent features.
-            area/models:
-            - i am not getting a response that is reasonable or expected. this can include things like
-            - I am calling a tool and the tool is not performing as expected.
-            - i am expecting a tool to be called and it is not getting called ,
-            - Including experience when using
-            - built-in tools (e.g., web search, code interpreter, read file, writefile, etc..),
-            - Function calling issues should be under this area
-            - i am getting responses from the model that are malformed.
-            - Issues concerning Gemini quality of response and inference,
-            - Issues talking about unnecessary token consumption.
-            - Issues talking about Model getting stuck in a loop be watchful as this could be the root cause for issues that otherwise seem like model performance issues.
-            - Memory compression
-            - unexpected responses,
-            - poor quality of generated code
-            area/tools:
-            - These are primarily issues related to Model Context Protocol
-            - These are issues that mention MCP support
-            - feature requests asking for support for new tools.
-            area/core: Issues with fundamental components like command parsing, configuration management, session state, and the main API client logic. Introducing multi-modality
-            area/contribution: Issues related to improving the developer contribution experience, such as CI/CD pipelines, build scripts, and test automation infrastructure.
-            area/authentication: Issues related to user identity, login flows, API key handling, credential storage, and access token management, unable to sign in selecting wrong authentication path etc..
-            area/security-privacy: Issues concerning vulnerability patching, dependency security, data sanitization, privacy controls, and preventing unauthorized data access.
-            area/extensibility: Issues related to the plugin system, extension APIs, or making the CLI's functionality available in other applications, github actions, ide support etc..
-            area/performance: Issues focused on model performance
-            - Issues with running out of capacity,
-            - 429 errors etc..
-            - could also pertain to latency,
-            - other general software performance like, memory usage, CPU consumption, and algorithmic efficiency.
-            - Switching models from one to the other unexpectedly.
+            area/enterprise
+            - Description: Issues specific to enterprise-level features, including telemetry, policy, and licenses.
+            - Example Issues:
+              "Usage data is not appearing in our telemetry dashboard."
+              "A user is able to perform an action that should be blocked by an admin policy."
+              "Questions about billing, licensing tiers, or enterprise quotas."
+
+            area/non-interactive
+            - Description: Issues related to using the CLI in automated or non-interactive environments (headless mode).
+            - Example Issues:
+              "Problems using the CLI as an SDK in another surface."
+              "The CLI is behaving differently when run from a shell script vs. an interactive terminal."
+              "GitHub action is failing."
+              "I am having trouble running the CLI in headless mode"
+
+            area/core
+            - Description: Issues with the fundamental CLI app itself. This includes the user interface (UI/UX), installation, OS compatibility, and performance.
+            - Example Issues:
+              "I am seeing my screen flicker when using the CLI."
+              "The output in my terminal is malformed or unreadable."
+              "Theme changes are not taking effect."
+              "Keyboard inputs (e.g., arrow keys, Ctrl+C) are not being recognized."
+              "The CLI failed to install or update."
+              "An issue specific to running on Windows, macOS, or Linux."
+              "Problems with command parsing, flags, or argument handling."
+              "High CPU or memory usage by the CLI process."
+              "Issues related to multi-modality (e.g., handling image inputs)."
+              "Problems with the IDE integration connection or installation"
+
+            area/security
+            - Description: Issues related to user authentication, authorization, data security, and privacy.
+            - Example Issues:
+              "I am unable to sign in."
+              "The login flow is selecting the wrong authentication path"
+              "Problems with API key handling or credential storage."
+              "A report of a security vulnerability"
+              "Concerns about data sanitization or potential data leaks."
+              "Issues or requests related to privacy controls."
+              "Preventing unauthorized data access."
+
+            area/platform
+            - Description: Issues related to CI/CD, release management, testing, eval infrastructure, capacity, quota management, and sandbox environments.
+            - Example Issues:
+              "I am getting a 429 'Resource Exhausted' or 500-level server error."
+              "General slowness or high latency from the service."
+              "The build script is broken on the main branch."
+              "Tests are failing in the CI/CD pipeline."
+              "Issues with the release management or publishing process."
+              "User is running out of capacity."
+              "Problems specific to the sandbox or staging environments."
+              "Questions about quota limits or requests for increases."
+
+            area/extensions
+            - Description: Issues related to the extension ecosystem, including the marketplace and website.
+            - Example Issues:
+              "Bugs related to the extension marketplace website."
+              "Issues with a specific extension."
+              "Feature request for the extension ecosystem."
+
+            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: |-
@@ -268,52 +300,61 @@ jobs:
         uses: 'actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea'
         with:
           github-token: '${{ steps.generate_token.outputs.token }}'
-          script: |-
-            // Strip code block markers if present
-            const rawLabels = process.env.LABELS_OUTPUT;
-            core.info(`Raw labels JSON: ${rawLabels}`);
+          script: |
+            const rawOutput = process.env.LABELS_OUTPUT;
+            core.info(`Raw output from model: ${rawOutput}`);
             let parsedLabels;
             try {
-              const jsonMatch = rawLabels.match(/```json\s*([\s\S]*?)\s*```/);
-              if (!jsonMatch || !jsonMatch[1]) {
-                throw new Error("Could not find a ```json ... ``` block in the output.");
+              // First, try to parse the raw output as JSON.
+              parsedLabels = JSON.parse(rawOutput);
+            } catch (jsonError) {
+              // If that fails, check for a markdown code block.
+              core.warning(`Direct JSON parsing failed: ${jsonError.message}. Trying to extract from a markdown block.`);
+              const jsonMatch = rawOutput.match(/```json\s*([\s\S]*?)\s*```/);
+              if (jsonMatch && jsonMatch[1]) {
+                try {
+                  parsedLabels = JSON.parse(jsonMatch[1].trim());
+                } catch (markdownError) {
+                  core.setFailed(`Failed to parse JSON even after extracting from markdown block: ${markdownError.message}\nRaw output: ${rawOutput}`);
+                  return;
+                }
+              } else {
+                core.setFailed(`Output is not valid JSON and does not contain a JSON markdown block.\nRaw output: ${rawOutput}`);
+                return;
               }
-              const jsonString = jsonMatch[1].trim();
-              parsedLabels = JSON.parse(jsonString);
-              core.info(`Parsed labels JSON: ${JSON.stringify(parsedLabels)}`);
-            } catch (err) {
-              core.setFailed(`Failed to parse labels JSON from Gemini output: ${err.message}\nRaw output: ${rawLabels}`);
-              return;
             }
 
             const issueNumber = parseInt(process.env.ISSUE_NUMBER);
-            const explanation = parsedLabels.explanation || '';
-            const labelsToSet = parsedLabels.labels_to_set || [];
-            labelsToSet.push('status/bot-triaged');
+            const labelsToAdd = parsedLabels.labels_to_set || [];
 
-            // Set labels based on triage result
-            if (labelsToSet.length > 0) {
-              await github.rest.issues.setLabels({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: issueNumber,
-                labels: labelsToSet
-              });
-              const explanationInfo = explanation ? ` - ${explanation}` : '';
-              core.info(`Successfully set labels for #${issueNumber}: ${labelsToSet.join(', ')}${explanationInfo}`);
-            } else {
-              // If no labels to set, leave the issue as is
-              const explanationInfo = explanation ? ` - ${explanation}` : '';
-              core.info(`No labels to set for #${issueNumber}, leaving as is${explanationInfo}`);
+            if (labelsToAdd.length !== 2) {
+              core.setFailed(`Expected exactly 2 labels (one area/ and one priority/), but got ${labelsToAdd.length}. Labels: ${labelsToAdd.join(', ')}`);
+              return;
             }
 
-            if (explanation) {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: issueNumber,
-                body: explanation,
-              });
+            // Set labels based on triage result
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              labels: labelsToAdd
+            });
+            core.info(`Successfully added labels for #${issueNumber}: ${labelsToAdd.join(', ')}`);
+
+            // Remove the 'status/need-triage' label
+            try {
+                await github.rest.issues.removeLabel({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: issueNumber,
+                    name: 'status/need-triage'
+                });
+                core.info(`Successfully removed 'status/need-triage' label.`);
+            } catch (error) {
+                // If the label doesn't exist, the API call will throw a 404. We can ignore this.
+                if (error.status !== 404) {
+                    core.warning(`Failed to remove 'status/need-triage': ${error.message}`);
+                }
             }
 
       - name: 'Post Issue Analysis Failure Comment'

.github/workflows/links.yml

@@ -0,0 +1,23 @@
+name: 'Links'
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+  repository_dispatch:
+  workflow_dispatch:
+  schedule:
+    - cron: '00 18 * * *'
+
+jobs:
+  linkChecker:
+    runs-on: 'ubuntu-latest'
+    steps:
+      - uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
+
+      - name: 'Link Checker'
+        id: 'lychee'
+        uses: 'lycheeverse/lychee-action@885c65f3dc543b57c898c8099f4e08c8afd178a2' # ratchet: lycheeverse/lychee-action@v2.6.1
+        with:
+          args: '--verbose --no-progress ./**/*.md'

.github/workflows/release-change-tags.yml

@@ -33,7 +33,7 @@ on:
 jobs:
   change-tags:
     runs-on: 'ubuntu-latest'
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       packages: 'write'
       issues: 'write'
@@ -62,4 +62,4 @@ jobs:
           cli-package-name: '${{ vars.CLI_PACKAGE_NAME }}'
           core-package-name: '${{ vars.CORE_PACKAGE_NAME }}'
           a2a-package-name: '${{ vars.A2A_PACKAGE_NAME }}'
-          ref: '${{ github.ref }}'
+          working-directory: '.'

.github/workflows/release-manual.yml

@@ -48,7 +48,7 @@ on:
 jobs:
   release:
     runs-on: 'ubuntu-latest'
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       contents: 'write'
       packages: 'write'
@@ -75,7 +75,7 @@ jobs:
       - name: 'Setup Node.js'
         uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020'
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: './release/.nvmrc'
           cache: 'npm'
 
       - name: 'Install Dependencies'
@@ -85,8 +85,10 @@ jobs:
       - name: 'Prepare Release Info'
         id: 'release_info'
         working-directory: './release'
+        env:
+          INPUT_VERSION: '${{ github.event.inputs.version }}'
         run: |
-          RELEASE_VERSION="${{ github.event.inputs.version }}"
+          RELEASE_VERSION="${INPUT_VERSION}"
           echo "RELEASE_VERSION=${RELEASE_VERSION#v}" >> "${GITHUB_OUTPUT}"
           echo "PREVIOUS_TAG=$(git describe --tags --abbrev=0)" >> "${GITHUB_OUTPUT}"
 

.github/workflows/release-nightly.yml

@@ -31,7 +31,7 @@ on:
 
 jobs:
   release:
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     runs-on: 'ubuntu-latest'
     permissions:
       contents: 'write'
@@ -137,7 +137,7 @@ jobs:
           a2a-package-name: '${{ vars.A2A_PACKAGE_NAME }}'
 
       - name: 'Create and Merge Pull Request'
-        if: "github.event.inputs.environment == 'prod'"
+        if: "github.event.inputs.environment != 'dev'"
         uses: './.github/actions/create-pull-request'
         with:
           branch-name: 'release/${{ steps.nightly_version.outputs.RELEASE_TAG }}'
@@ -148,7 +148,7 @@ jobs:
           working-directory: './release'
 
       - name: 'Create Issue on Failure'
-        if: "${{ failure() && github.event.inputs.environment == 'prod' && (github.event_name == 'schedule' || github.event.inputs.dry_run != 'true') }}"
+        if: "${{ failure() && github.event.inputs.environment != 'dev' && (github.event_name == 'schedule' || github.event.inputs.dry_run != 'true') }}"
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
           RELEASE_TAG: '${{ steps.nightly_version.outputs.RELEASE_TAG }}'

.github/workflows/release-patch-0-from-comment.yml

@@ -89,7 +89,8 @@ jobs:
                 inputs: {
                   commit: '${{ steps.pr_status.outputs.MERGE_COMMIT_SHA }}',
                   channel: channel,
-                  original_pr: '${{ github.event.issue.number }}'
+                  original_pr: '${{ github.event.issue.number }}',
+                  environment: 'prod'
                 }
               });
 

.github/workflows/release-patch-1-create-pr.yml

@@ -1,5 +1,8 @@
 name: 'Release: Patch (1) Create PR'
 
+run-name: >-
+  Release Patch (1) Create PR | S:${{ inputs.channel }} | C:${{ inputs.commit }} ${{ inputs.original_pr && format('| PR:#{0}', inputs.original_pr) || '' }}
+
 on:
   workflow_dispatch:
     inputs:
@@ -28,10 +31,19 @@ on:
         description: 'The original PR number to comment back on.'
         required: false
         type: 'string'
+      environment:
+        description: 'Environment'
+        required: false
+        type: 'choice'
+        options:
+          - 'prod'
+          - 'dev'
+        default: 'prod'
 
 jobs:
   create-patch:
     runs-on: 'ubuntu-latest'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       contents: 'write'
       pull-requests: 'write'
@@ -49,32 +61,50 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
 
+      - name: 'configure .npmrc'
+        uses: './.github/actions/setup-npmrc'
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+
       - name: 'Install Script Dependencies'
-        run: 'npm install yargs'
+        run: 'npm ci'
 
       - name: 'Configure Git User'
+        env:
+          GH_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          REPOSITORY: '${{ github.repository }}'
         run: |-
           git config user.name "gemini-cli-robot"
           git config user.email "gemini-cli-robot@google.com"
           # Configure git to use GITHUB_TOKEN for remote operations (has actions:write for workflow files)
-          git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${REPOSITORY}.git"
 
       - name: 'Create Patch'
         id: 'create_patch'
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
           GH_TOKEN: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
+          CLI_PACKAGE_NAME: '${{ vars.CLI_PACKAGE_NAME }}'
+          PATCH_COMMIT: '${{ github.event.inputs.commit }}'
+          PATCH_CHANNEL: '${{ github.event.inputs.channel }}'
+          ORIGINAL_PR: '${{ github.event.inputs.original_pr }}'
+          DRY_RUN: '${{ github.event.inputs.dry_run }}'
         continue-on-error: true
         run: |
           # Capture output and display it in logs using tee
           {
-            node scripts/releasing/create-patch-pr.js --commit=${{ github.event.inputs.commit }} --channel=${{ github.event.inputs.channel }} --pullRequestNumber=${{ github.event.inputs.original_pr }} --dry-run=${{ github.event.inputs.dry_run }}
-            echo "EXIT_CODE=$?" >> "$GITHUB_OUTPUT"
+            node scripts/releasing/create-patch-pr.js \
+              --cli-package-name="${CLI_PACKAGE_NAME}" \
+              --commit="${PATCH_COMMIT}" \
+              --channel="${PATCH_CHANNEL}" \
+              --pullRequestNumber="${ORIGINAL_PR}" \
+              --dry-run="${DRY_RUN}"
           } 2>&1 | tee >(
             echo "LOG_CONTENT<<EOF" >> "$GITHUB_ENV"
             cat >> "$GITHUB_ENV"
             echo "EOF" >> "$GITHUB_ENV"
           )
+          echo "EXIT_CODE=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT"
 
       - name: 'Comment on Original PR'
         if: 'always() && inputs.original_pr'
@@ -87,14 +117,18 @@ jobs:
           REPOSITORY: '${{ github.repository }}'
           GITHUB_RUN_ID: '${{ github.run_id }}'
           LOG_CONTENT: '${{ env.LOG_CONTENT }}'
+          TARGET_REF: '${{ github.event.inputs.ref }}'
+          ENVIRONMENT: '${{ github.event.inputs.environment }}'
         continue-on-error: true
         run: |
-          git checkout '${{ github.event.inputs.ref }}'
+          git checkout "${TARGET_REF}"
           node scripts/releasing/patch-create-comment.js
 
       - name: 'Fail Workflow if Main Task Failed'
         if: 'always() && steps.create_patch.outputs.EXIT_CODE != 0'
+        env:
+          EXIT_CODE: '${{ steps.create_patch.outputs.EXIT_CODE }}'
         run: |
-          echo "Patch creation failed with exit code: ${{ steps.create_patch.outputs.EXIT_CODE }}"
+          echo "Patch creation failed with exit code: ${EXIT_CODE}"
           echo "Check the logs above and the comment posted to the original PR for details."
           exit 1

.github/workflows/release-patch-2-trigger.yml

@@ -1,5 +1,10 @@
 name: 'Release: Patch (2) Trigger'
 
+run-name: >-
+  Release Patch (2) Trigger |
+  ${{ github.event.pull_request.number && format('PR #{0}', github.event.pull_request.number) || 'Manual' }} |
+  ${{ github.event.pull_request.head.ref || github.event.inputs.ref }}
+
 on:
   pull_request:
     types:
@@ -18,7 +23,7 @@ on:
         type: 'string'
         default: 'main'
       workflow_id:
-        description: 'The workflow to trigger. Defaults to patch-release.yml'
+        description: 'The workflow to trigger. Defaults to release-patch-3-release.yml'
         required: false
         type: 'string'
         default: 'release-patch-3-release.yml'
@@ -37,11 +42,20 @@ on:
         required: false
         type: 'boolean'
         default: false
+      environment:
+        description: 'Environment'
+        required: false
+        type: 'choice'
+        options:
+          - 'prod'
+          - 'dev'
+        default: 'prod'
 
 jobs:
   trigger-patch-release:
     if: "(github.event_name == 'pull_request' && github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'hotfix/')) || github.event_name == 'workflow_dispatch'"
     runs-on: 'ubuntu-latest'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       actions: 'write'
       contents: 'write'
@@ -74,5 +88,7 @@ jobs:
           GITHUB_EVENT_PAYLOAD: '${{ toJSON(github.event) }}'
           FORCE_SKIP_TESTS: '${{ github.event.inputs.force_skip_tests }}'
           TEST_MODE: '${{ github.event.inputs.test_mode }}'
+          ENVIRONMENT: "${{ github.event.inputs.environment || 'prod' }}"
+          DRY_RUN: '${{ github.event.inputs.dry_run }}'
         run: |
-          node scripts/releasing/patch-trigger.js --dry-run=${{ github.event.inputs.dry_run }}
+          node scripts/releasing/patch-trigger.js --dry-run="${DRY_RUN}"

.github/workflows/release-patch-3-release.yml

@@ -1,5 +1,8 @@
 name: 'Release: Patch (3) Release'
 
+run-name: >-
+  Release Patch (3) Release | T:${{ inputs.type }} | R:${{ inputs.release_ref }} ${{ inputs.original_pr && format('| PR:#{0}', inputs.original_pr) || '' }}
+
 on:
   workflow_dispatch:
     inputs:
@@ -34,13 +37,13 @@ on:
         type: 'choice'
         options:
           - 'prod'
-          ## - 'dev' # TODO(richieforeman) - support dev
+          - 'dev'
         default: 'prod'
 
 jobs:
   release:
     runs-on: 'ubuntu-latest'
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       contents: 'write'
       packages: 'write'
@@ -66,7 +69,17 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
 
+      - name: 'configure .npmrc'
+        uses: './.github/actions/setup-npmrc'
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+
+      - name: 'Install Script Dependencies'
+        run: |-
+          npm ci
+
       - name: 'Install Dependencies'
+        working-directory: './release'
         run: |-
           npm ci
 
@@ -80,10 +93,12 @@ jobs:
         id: 'patch_version'
         env:
           GH_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          PATCH_FROM: '${{ github.event.inputs.type }}'
+          CLI_PACKAGE_NAME: '${{vars.CLI_PACKAGE_NAME}}'
         run: |
           # Use the existing get-release-version.js script to calculate patch version
           # Run from main checkout which has full git history and access to npm
-          PATCH_JSON=$(node scripts/get-release-version.js --type=patch --patch-from=${{ github.event.inputs.type }})
+          PATCH_JSON=$(node scripts/get-release-version.js --type=patch --cli-package-name="${CLI_PACKAGE_NAME}" --patch-from="${PATCH_FROM}")
           echo "Patch version calculation result: ${PATCH_JSON}"
 
           RELEASE_VERSION=$(echo "${PATCH_JSON}" | jq -r .releaseVersion)
@@ -100,14 +115,13 @@ jobs:
         env:
           GH_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
           CHANNEL: '${{ github.event.inputs.type }}'
+          ORIGINAL_RELEASE_VERSION: '${{ steps.patch_version.outputs.RELEASE_VERSION }}'
+          ORIGINAL_RELEASE_TAG: '${{ steps.patch_version.outputs.RELEASE_TAG }}'
+          ORIGINAL_PREVIOUS_TAG: '${{ steps.patch_version.outputs.PREVIOUS_TAG }}'
         run: |
           echo "🔍 Verifying no concurrent patch releases have occurred..."
 
           # Store original calculation for comparison
-          ORIGINAL_RELEASE_VERSION="${{ steps.patch_version.outputs.RELEASE_VERSION }}"
-          ORIGINAL_RELEASE_TAG="${{ steps.patch_version.outputs.RELEASE_TAG }}"
-          ORIGINAL_PREVIOUS_TAG="${{ steps.patch_version.outputs.PREVIOUS_TAG }}"
-
           echo "Original calculation:"
           echo "  Release version: ${ORIGINAL_RELEASE_VERSION}"
           echo "  Release tag: ${ORIGINAL_RELEASE_TAG}"
@@ -115,7 +129,7 @@ jobs:
 
           # Re-run the same version calculation script
           echo "Re-calculating version to check for changes..."
-          CURRENT_PATCH_JSON=$(node scripts/get-release-version.js --type=patch --patch-from="${CHANNEL}")
+          CURRENT_PATCH_JSON=$(node scripts/get-release-version.js --cli-package-name="${{vars.CLI_PACKAGE_NAME}}" --type=patch --patch-from="${CHANNEL}")
           CURRENT_RELEASE_VERSION=$(echo "${CURRENT_PATCH_JSON}" | jq -r .releaseVersion)
           CURRENT_RELEASE_TAG=$(echo "${CURRENT_PATCH_JSON}" | jq -r .releaseTag)
           CURRENT_PREVIOUS_TAG=$(echo "${CURRENT_PATCH_JSON}" | jq -r .previousReleaseTag)
@@ -172,7 +186,6 @@ jobs:
           github-token: '${{ secrets.GITHUB_TOKEN }}'
           dry-run: '${{ github.event.inputs.dry_run }}'
           previous-tag: '${{ steps.patch_version.outputs.PREVIOUS_TAG }}'
-          working-directory: './release'
           gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
           npm-registry-publish-url: '${{ vars.NPM_REGISTRY_PUBLISH_URL }}'
           npm-registry-url: '${{ vars.NPM_REGISTRY_URL }}'
@@ -180,6 +193,7 @@ jobs:
           cli-package-name: '${{ vars.CLI_PACKAGE_NAME }}'
           core-package-name: '${{ vars.CORE_PACKAGE_NAME }}'
           a2a-package-name: '${{ vars.A2A_PACKAGE_NAME }}'
+          working-directory: './release'
 
       - name: 'Create Issue on Failure'
         if: '${{ failure() && github.event.inputs.dry_run == false }}'

.github/workflows/release-promote.yml

@@ -39,7 +39,7 @@ jobs:
   calculate-versions:
     name: 'Calculate Versions and Plan'
     runs-on: 'ubuntu-latest'
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
 
     outputs:
       STABLE_VERSION: '${{ steps.versions.outputs.STABLE_VERSION }}'
@@ -77,12 +77,24 @@ jobs:
         id: 'versions'
         env:
           GH_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          STABLE_OVERRIDE: '${{ github.event.inputs.stable_version_override }}'
+          PREVIEW_OVERRIDE: '${{ github.event.inputs.preview_version_override }}'
+          REF_INPUT: '${{ github.event.inputs.ref }}'
         run: |
           set -e
-          STABLE_COMMAND="node scripts/get-release-version.js --type=stable ${{ github.event.inputs.stable_version_override && format('--stable_version_override={0}', github.event.inputs.stable_version_override) || '' }}"
-          PREVIEW_COMMAND="node scripts/get-release-version.js --type=preview ${{ github.event.inputs.preview_version_override && format('--preview_version_override={0}', github.event.inputs.preview_version_override) || '' }}"
+          STABLE_COMMAND="node scripts/get-release-version.js --type=stable"
+          if [[ -n "${STABLE_OVERRIDE}" ]]; then
+            STABLE_COMMAND+=" --stable_version_override=${STABLE_OVERRIDE}"
+          fi
+          PREVIEW_COMMAND="node scripts/get-release-version.js --type=preview"
+          if [[ -n "${PREVIEW_OVERRIDE}" ]]; then
+            PREVIEW_COMMAND+=" --preview_version_override=${PREVIEW_OVERRIDE}"
+          fi
           NIGHTLY_COMMAND="node scripts/get-release-version.js --type=promote-nightly"
           STABLE_JSON=$(${STABLE_COMMAND})
+          STABLE_VERSION=$(echo "${STABLE_JSON}" | jq -r .releaseVersion)
+          PREVIEW_COMMAND+=" --stable-base-version=${STABLE_VERSION}"
+          NIGHTLY_COMMAND+=" --stable-base-version=${STABLE_VERSION}"
           PREVIEW_JSON=$(${PREVIEW_COMMAND})
           NIGHTLY_JSON=$(${NIGHTLY_COMMAND})
           echo "STABLE_JSON_COMMAND=${STABLE_COMMAND}"
@@ -91,14 +103,14 @@ jobs:
           echo "STABLE_JSON: ${STABLE_JSON}"
           echo "PREVIEW_JSON: ${PREVIEW_JSON}"
           echo "NIGHTLY_JSON: ${NIGHTLY_JSON}"
-          echo "STABLE_VERSION=$(echo "${STABLE_JSON}" | jq -r .releaseVersion)" >> "${GITHUB_OUTPUT}"
+          echo "STABLE_VERSION=${STABLE_VERSION}" >> "${GITHUB_OUTPUT}"
           # shellcheck disable=SC1083
           echo "STABLE_SHA=$(git rev-parse "$(echo "${PREVIEW_JSON}" | jq -r .previousReleaseTag)"^{commit})" >> "${GITHUB_OUTPUT}"
           echo "PREVIOUS_STABLE_TAG=$(echo "${STABLE_JSON}" | jq -r .previousReleaseTag)" >> "${GITHUB_OUTPUT}"
           echo "PREVIEW_VERSION=$(echo "${PREVIEW_JSON}" | jq -r .releaseVersion)" >> "${GITHUB_OUTPUT}"
           # shellcheck disable=SC1083
-          REF="${{ github.event.inputs.ref }}"
-          SHA=$(git ls-remote origin "$REF" | awk '{print $1}')
+          REF="${REF_INPUT}"
+          SHA=$(git ls-remote origin "$REF" | awk -v ref="$REF" '$2 == "refs/heads/"ref || $2 == "refs/tags/"ref || $2 == ref {print $1}' | head -n 1)
           if [ -z "$SHA" ]; then
             if [[ "$REF" =~ ^[0-9a-f]{7,40}$ ]]; then
               SHA="$REF"
@@ -116,20 +128,30 @@ jobs:
           echo "NEXT_SHA=$SHA" >> "${GITHUB_OUTPUT}"
 
       - name: 'Display Pending Updates'
+        env:
+          STABLE_VERSION: '${{ steps.versions.outputs.STABLE_VERSION }}'
+          STABLE_SHA: '${{ steps.versions.outputs.STABLE_SHA }}'
+          PREVIOUS_STABLE_TAG: '${{ steps.versions.outputs.PREVIOUS_STABLE_TAG }}'
+          PREVIEW_VERSION: '${{ steps.versions.outputs.PREVIEW_VERSION }}'
+          PREVIEW_SHA: '${{ steps.versions.outputs.PREVIEW_SHA }}'
+          PREVIOUS_PREVIEW_TAG: '${{ steps.versions.outputs.PREVIOUS_PREVIEW_TAG }}'
+          NEXT_NIGHTLY_VERSION: '${{ steps.versions.outputs.NEXT_NIGHTLY_VERSION }}'
+          PREVIOUS_NIGHTLY_TAG: '${{ steps.versions.outputs.PREVIOUS_NIGHTLY_TAG }}'
+          INPUT_REF: '${{ github.event.inputs.ref }}'
         run: |
           echo "Release Plan:"
           echo "-----------"
-          echo "Stable Release: ${{ steps.versions.outputs.STABLE_VERSION }}"
-          echo "  - Commit: ${{ steps.versions.outputs.STABLE_SHA }}"
-          echo "  - Previous Tag: ${{ steps.versions.outputs.PREVIOUS_STABLE_TAG }}"
+          echo "Stable Release: ${STABLE_VERSION}"
+          echo "  - Commit: ${STABLE_SHA}"
+          echo "  - Previous Tag: ${PREVIOUS_STABLE_TAG}"
           echo ""
-          echo "Preview Release: ${{ steps.versions.outputs.PREVIEW_VERSION }}"
-          echo "  - Commit: ${{ steps.versions.outputs.PREVIEW_SHA }} (${{ github.event.inputs.ref }})"
-          echo "  - Previous Tag: ${{ steps.versions.outputs.PREVIOUS_PREVIEW_TAG }}"
+          echo "Preview Release: ${PREVIEW_VERSION}"
+          echo "  - Commit: ${PREVIEW_SHA} (${INPUT_REF})"
+          echo "  - Previous Tag: ${PREVIOUS_PREVIEW_TAG}"
           echo ""
-          echo "Preparing Next Nightly Release: ${{ steps.versions.outputs.NEXT_NIGHTLY_VERSION }}"
-          echo "  - Merging Version Update PR to Branch: ${{ github.event.inputs.ref }}"
-          echo "  - Previous Tag: ${{ steps.versions.outputs.PREVIOUS_NIGHTLY_TAG }}"
+          echo "Preparing Next Nightly Release: ${NEXT_NIGHTLY_VERSION}"
+          echo "  - Merging Version Update PR to Branch: ${INPUT_REF}"
+          echo "  - Previous Tag: ${PREVIOUS_NIGHTLY_TAG}"
 
   test:
     name: 'Test ${{ matrix.channel }}'
@@ -179,7 +201,7 @@ jobs:
     name: 'Publish preview'
     needs: ['calculate-versions', 'test']
     runs-on: 'ubuntu-latest'
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       contents: 'write'
       packages: 'write'
@@ -245,7 +267,7 @@ jobs:
     name: 'Publish stable'
     needs: ['calculate-versions', 'test', 'publish-preview']
     runs-on: 'ubuntu-latest'
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     permissions:
       contents: 'write'
       packages: 'write'

.github/workflows/release-rollback.yml

@@ -31,10 +31,18 @@ on:
         required: false
         type: 'boolean'
         default: true
+      environment:
+        description: 'Environment'
+        required: false
+        type: 'choice'
+        options:
+          - 'prod'
+          - 'dev'
+        default: 'prod'
 
 jobs:
   change-tags:
-    environment: 'prod' ## TODO(richieforeman) Support Dev mode
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     runs-on: 'ubuntu-latest'
     permissions:
       packages: 'write'
@@ -50,23 +58,29 @@ jobs:
         uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020'
         with:
           node-version-file: '.nvmrc'
-          registry-url: 'https://wombat-dressing-room.appspot.com'
-          scope: '@google'
+
+      - name: 'configure .npmrc'
+        uses: './.github/actions/setup-npmrc'
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
 
       - name: 'Get Origin Version Tag'
         id: 'origin_tag'
         shell: 'bash'
+        env:
+          ROLLBACK_ORIGIN: '${{ github.event.inputs.rollback_origin }}'
         run: |
-          TAG_VALUE="v${{ github.event.inputs.rollback_origin }}"
+          TAG_VALUE="v${ROLLBACK_ORIGIN}"
           echo "ORIGIN_TAG=$TAG_VALUE" >> "$GITHUB_OUTPUT"
 
       - name: 'Get Origin Commit Hash'
         id: 'origin_hash'
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          ORIGIN_TAG: '${{ steps.origin_tag.outputs.ORIGIN_TAG }}'
         shell: 'bash'
         run: |
-          echo "ORIGIN_HASH=$(git rev-parse ${{ steps.origin_tag.outputs.ORIGIN_TAG }})" >> "$GITHUB_OUTPUT"
+          echo "ORIGIN_HASH=$(git rev-parse "${ORIGIN_TAG}")" >> "$GITHUB_OUTPUT"
 
       - name: 'Change tag'
         if: "${{ github.event.inputs.rollback_destination != '' }}"
@@ -83,48 +97,85 @@ jobs:
           core-package-name: '${{ vars.CORE_PACKAGE_NAME }}'
           a2a-package-name: '${{ vars.A2A_PACKAGE_NAME }}'
 
+      - name: 'Get cli Token'
+        uses: './.github/actions/npm-auth-token'
+        id: 'cli-token'
+        with:
+          package-name: '${{ vars.CLI_PACKAGE_NAME }}'
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+          wombat-token-core: '${{ secrets.WOMBAT_TOKEN_CORE }}'
+          wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
+          wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
+
       - name: 'Deprecate Cli Npm Package'
-        if: "${{ github.event.inputs.dry-run == 'false' }}"
+        if: "${{ github.event.inputs.dry-run == 'false' && github.event.inputs.environment == 'prod' }}"
         env:
-          NODE_AUTH_TOKEN: '${{ secrets.WOMBAT_TOKEN_CLI }}'
+          NODE_AUTH_TOKEN: '${{ steps.cli-token.outputs.auth-token }}'
+          PACKAGE_NAME: '${{ vars.CLI_PACKAGE_NAME }}'
+          ROLLBACK_ORIGIN: '${{ github.event.inputs.rollback_origin }}'
         shell: 'bash'
         run: |
-          npm deprecate @google/gemini-cli@${{ github.event.inputs.rollback_origin }} "This version has been rolled back."
+          npm deprecate "${PACKAGE_NAME}@${ROLLBACK_ORIGIN}" "This version has been rolled back."
+
+      - name: 'Get core Token'
+        uses: './.github/actions/npm-auth-token'
+        id: 'core-token'
+        with:
+          package-name: '${{ vars.CLI_PACKAGE_NAME }}'
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+          wombat-token-core: '${{ secrets.WOMBAT_TOKEN_CORE }}'
+          wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
+          wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
 
       - name: 'Deprecate Core Npm Package'
-        if: "${{ github.event.inputs.dry-run == 'false' }}"
+        if: "${{ github.event.inputs.dry-run == 'false' && github.event.inputs.environment == 'prod' }}"
         env:
-          NODE_AUTH_TOKEN: '${{ secrets.WOMBAT_TOKEN_CORE }}'
+          NODE_AUTH_TOKEN: '${{ steps.core-token.outputs.auth-token }}'
+          PACKAGE_NAME: '${{ vars.CORE_PACKAGE_NAME }}'
+          ROLLBACK_ORIGIN: '${{ github.event.inputs.rollback_origin }}'
         shell: 'bash'
         run: |
-          npm deprecate @google/gemini-core@${{ github.event.inputs.rollback_origin }} "This version has been rolled back."
+          npm deprecate "${PACKAGE_NAME}@${ROLLBACK_ORIGIN}" "This version has been rolled back."
+
+      - name: 'Get a2a Token'
+        uses: './.github/actions/npm-auth-token'
+        id: 'a2a-token'
+        with:
+          package-name: '${{ vars.A2A_PACKAGE_NAME }}'
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+          wombat-token-core: '${{ secrets.WOMBAT_TOKEN_CORE }}'
+          wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
+          wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
 
       - name: 'Deprecate A2A Server Npm Package'
-        if: "${{ github.event.inputs.dry-run == 'false' }}"
+        if: "${{ github.event.inputs.dry-run == 'false' && github.event.inputs.environment == 'prod'  }}"
         env:
-          NODE_AUTH_TOKEN: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
+          NODE_AUTH_TOKEN: '${{ steps.a2a-token.outputs.auth-token }}'
+          PACKAGE_NAME: '${{ vars.A2A_PACKAGE_NAME }}'
+          ROLLBACK_ORIGIN: '${{ github.event.inputs.rollback_origin }}'
         shell: 'bash'
         run: |
-          npm deprecate @google/gemini-cli-a2a-server@${{ github.event.inputs.rollback_origin }} "This version has been rolled back."
+          npm deprecate "${PACKAGE_NAME}@${ROLLBACK_ORIGIN}" "This version has been rolled back."
 
       - name: 'Delete Github Release'
-        if: "${{ github.event.inputs.dry-run == 'false' }}"
+        if: "${{ github.event.inputs.dry-run == 'false' && github.event.inputs.environment == 'prod'}}"
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          ORIGIN_TAG: '${{ steps.origin_tag.outputs.ORIGIN_TAG }}'
         shell: 'bash'
         run: |
-          gh release delete '${{ steps.origin_tag.outputs.ORIGIN_TAG }}' --yes
+          gh release delete "${ORIGIN_TAG}" --yes
 
       - name: 'Verify Origin Release Deletion'
         if: "${{ github.event.inputs.dry-run == 'false' }}"
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          TARGET_TAG: '${{ steps.origin_tag.outputs.ORIGIN_TAG }}'
         shell: 'bash'
         run: |
-          TARGET_TAG="${{ steps.origin_tag.outputs.ORIGIN_TAG }}"
           RELEASE_TAG=$(gh release view "$TARGET_TAG" --json tagName --jq .tagName)
           if [ "$RELEASE_TAG" = "$TARGET_TAG" ]; then
-            echo '❌ Failed to delete release with tag ${{ steps.origin_tag.outputs.ORIGIN_TAG }}'
+            echo "❌ Failed to delete release with tag ${TARGET_TAG}"
             echo '❌ This means the release was not deleted, and the workflow should fail.'
             exit 1
           fi
@@ -134,21 +185,22 @@ jobs:
         if: "${{ github.event.inputs.dry-run == 'false' }}"
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          ROLLBACK_TAG_NAME: '${{ steps.origin_tag.outputs.ORIGIN_TAG }}-rollback'
+          ORIGIN_HASH: '${{ steps.origin_hash.outputs.ORIGIN_HASH }}'
         shell: 'bash'
         run: |
-          ROLLBACK_TAG_NAME="${{ steps.origin_tag.outputs.ORIGIN_TAG }}-rollback"
           echo "ROLLBACK_TAG=$ROLLBACK_TAG_NAME" >> "$GITHUB_OUTPUT"
-          git tag "$ROLLBACK_TAG_NAME" "${{ steps.origin_hash.outputs.ORIGIN_HASH }}"
+          git tag "$ROLLBACK_TAG_NAME" "${ORIGIN_HASH}"
           git push origin --tags
 
       - name: 'Verify Rollback Tag Added'
         if: "${{ github.event.inputs.dry-run == 'false' }}"
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          TARGET_TAG: '${{ steps.rollback_tag.outputs.ROLLBACK_TAG }}'
+          TARGET_HASH: '${{ steps.origin_hash.outputs.ORIGIN_HASH }}'
         shell: 'bash'
         run: |
-          TARGET_TAG="${{ steps.rollback_tag.outputs.ROLLBACK_TAG }}"
-          TARGET_HASH="${{ steps.origin_hash.outputs.ORIGIN_HASH }}"
           ROLLBACK_COMMIT=$(git rev-parse -q --verify "$TARGET_TAG")
           if [ "$ROLLBACK_COMMIT" != "$TARGET_HASH" ]; then
             echo '❌ Failed to add tag $TARGET_TAG to commit $TARGET_HASH'
@@ -158,21 +210,32 @@ jobs:
 
       - name: 'Log Dry run'
         if: "${{ github.event.inputs.dry-run == 'true' }}"
+        env:
+          ROLLBACK_ORIGIN: '${{ github.event.inputs.rollback_origin }}'
+          ROLLBACK_DESTINATION: '${{ github.event.inputs.rollback_destination }}'
+          CHANNEL: '${{ github.event.inputs.channel }}'
+          REF_INPUT: '${{ github.event.inputs.ref }}'
+          ORIGIN_TAG: '${{ steps.origin_tag.outputs.ORIGIN_TAG }}'
+          ORIGIN_HASH: '${{ steps.origin_hash.outputs.ORIGIN_HASH }}'
+          ROLLBACK_TAG: '${{ steps.rollback_tag.outputs.ROLLBACK_TAG }}'
+          CLI_PACKAGE_NAME: '${{ vars.CLI_PACKAGE_NAME }}'
+          CORE_PACKAGE_NAME: '${{ vars.CORE_PACKAGE_NAME }}'
+          A2A_PACKAGE_NAME: '${{ vars.A2A_PACKAGE_NAME }}'
         shell: 'bash'
         run: |
           echo "
           Inputs:
-          - rollback_origin: '${{ github.event.inputs.rollback_origin }}'
-          - rollback_destination: '${{ github.event.inputs.rollback_destination }}'
-          - channel: '${{ github.event.inputs.channel }}'
-          - ref: '${{ github.event.inputs.ref }}'
+          - rollback_origin: '${ROLLBACK_ORIGIN}'
+          - rollback_destination: '${ROLLBACK_DESTINATION}'
+          - channel: '${CHANNEL}'
+          - ref: '${REF_INPUT}'
 
           Outputs:
-          - ORIGIN_TAG: '${{ steps.origin_tag.outputs.ORIGIN_TAG }}'
-          - ORIGIN_HASH: '${{ steps.origin_hash.outputs.ORIGIN_HASH }}'
-          - ROLLBACK_TAG: '${{ steps.rollback_tag.outputs.ROLLBACK_TAG }}'
+          - ORIGIN_TAG: '${ORIGIN_TAG}'
+          - ORIGIN_HASH: '${ORIGIN_HASH}'
+          - ROLLBACK_TAG: '${ROLLBACK_TAG}'
 
-          Would have npm deprecate @google/gemini-cli@${{ github.event.inputs.rollback_origin }} and @google/gemini-core@${{ github.event.inputs.rollback_origin }}
-          Would have deleted the github release with tag ${{ steps.origin_tag.outputs.ORIGIN_TAG }}
-          Would have added tag ${{ steps.origin_tag.outputs.ORIGIN_TAG }}-rollback to ${{ steps.origin_hash.outputs.ORIGIN_HASH }}
+          Would have npm deprecate ${CLI_PACKAGE_NAME}@${ROLLBACK_ORIGIN}, ${CORE_PACKAGE_NAME}@${ROLLBACK_ORIGIN}, and ${A2A_PACKAGE_NAME}@${ROLLBACK_ORIGIN}
+          Would have deleted the github release with tag ${ORIGIN_TAG}
+          Would have added tag ${ORIGIN_TAG}-rollback to ${ORIGIN_HASH}
           "

.github/workflows/test_chained_e2e.yml

@@ -0,0 +1,304 @@
+name: 'Test Chained E2E'
+
+on:
+  push:
+    branches:
+      - 'main'
+  merge_group:
+  workflow_run:
+    workflows: ['Trigger E2E']
+    types: ['completed']
+  workflow_dispatch:
+    inputs:
+      head_sha:
+        description: 'SHA of the commit to test'
+        required: true
+      repo_name:
+        description: 'Repository name (e.g., owner/repo)'
+        required: true
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.event.workflow_run.head_branch || github.ref }}'
+  cancel-in-progress: |-
+    ${{ github.event_name != 'push' && github.event_name != 'merge_group' }}
+
+permissions:
+  contents: 'read'
+  statuses: 'write'
+
+jobs:
+  merge_queue_skipper:
+    name: 'Merge Queue Skipper'
+    permissions: 'read-all'
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    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
+
+  download_repo_name:
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    if: "github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_run'"
+    outputs:
+      repo_name: '${{ steps.output-repo-name.outputs.repo_name }}'
+    steps:
+      - name: 'Mock Repo Artifact'
+        if: "${{ github.event_name == 'workflow_dispatch' }}"
+        env:
+          REPO_NAME: '${{ github.event.inputs.repo_name }}'
+        run: |
+          mkdir -p ./pr
+          echo '${{ env.REPO_NAME }}' > ./pr/repo_name
+      - uses: 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02' # ratchet:actions/upload-artifact@v4
+        with:
+          name: 'repo_name'
+          path: 'pr/'
+      - name: 'Download the repo_name artifact'
+        uses: 'actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0' # ratchet:actions/download-artifact@v5
+        env:
+          RUN_ID: "${{ github.event_name == 'workflow_run' && github.event.workflow_run.id || github.run_id  }}"
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+          name: 'repo_name'
+          run-id: '${{ env.RUN_ID }}'
+          path: '${{ runner.temp }}/artifacts'
+      - name: 'Output Repo Name'
+        id: 'output-repo-name'
+        uses: 'actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd' # ratchet:actions/github-script@v8
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+          script: |
+            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);
+
+  parse_run_context:
+    name: 'Parse run context'
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    needs: 'download_repo_name'
+    if: 'always()'
+    outputs:
+      repository: '${{ steps.set_context.outputs.REPO }}'
+      sha: '${{ steps.set_context.outputs.SHA }}'
+    steps:
+      - id: 'set_context'
+        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 }}'
+        shell: 'bash'
+        run: |
+          echo "REPO=$REPO" >> "$GITHUB_OUTPUT"
+          echo "SHA=$SHA" >> "$GITHUB_OUTPUT"
+
+  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'
+    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 }}'
+          sha: '${{ needs.parse_run_context.outputs.sha }}'
+          token: '${{ secrets.GITHUB_TOKEN }}'
+          status: 'pending'
+
+  e2e_linux:
+    name: 'E2E Test (Linux) - ${{ matrix.sandbox }}'
+    needs:
+      - 'merge_queue_skipper'
+      - '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')
+    strategy:
+      fail-fast: false
+      matrix:
+        sandbox:
+          - 'sandbox:none'
+          - 'sandbox:docker'
+        node-version:
+          - '20.x'
+
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ needs.parse_run_context.outputs.sha }}'
+          repository: '${{ needs.parse_run_context.outputs.repository }}'
+
+      - 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'
+      - 'parse_run_context'
+    runs-on: 'macos-latest'
+    if: |
+      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ needs.parse_run_context.outputs.sha }}'
+          repository: '${{ needs.parse_run_context.outputs.repository }}'
+
+      - 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'
+      - 'parse_run_context'
+    if: |
+      always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+    runs-on: 'gemini-cli-windows-16-core'
+    continue-on-error: true
+
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ needs.parse_run_context.outputs.sha }}'
+          repository: '${{ needs.parse_run_context.outputs.repository }}'
+
+      - 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() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip == 'false')
+    needs:
+      - 'e2e_linux'
+      - 'e2e_mac'
+      - 'merge_queue_skipper'
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    steps:
+      - name: 'Check E2E test results'
+        run: |
+          if [[ ${{ needs.e2e_linux.result }} != 'success' || \
+               ${{ needs.e2e_mac.result }} != 'success' ]]; then
+            echo "One or more E2E jobs failed."
+            exit 1
+          fi
+          echo "All required E2E jobs passed!"
+
+  set_workflow_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'
+      - 'e2e'
+    steps:
+      - name: 'Set workflow 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 }}'
+          sha: '${{ needs.parse_run_context.outputs.sha }}'
+          token: '${{ secrets.GITHUB_TOKEN }}'
+          status: '${{ job.status }}'

.github/workflows/trigger_e2e.yml

@@ -0,0 +1,33 @@
+name: 'Trigger E2E'
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch_ref:
+        description: 'Branch to run on'
+        required: true
+        default: 'main'
+        type: 'string'
+
+jobs:
+  save_repo_name:
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    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 }}'
+        run: |
+          mkdir -p ./pr
+          echo '${{ env.REPO_NAME }}' > ./pr/repo_name
+      - uses: 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02' # ratchet:actions/upload-artifact@v4
+        with:
+          name: 'repo_name'
+          path: 'pr/'
+  trigger_e2e:
+    name: 'Trigger e2e'
+    runs-on: 'gemini-cli-ubuntu-16-core'
+    steps:
+      - id: 'trigger-e2e'
+        run: |
+          echo "Trigger e2e workflow"

.github/workflows/verify-release.yml

@@ -28,7 +28,7 @@ on:
 
 jobs:
   verify-release:
-    environment: '${{ github.event.inputs.environment }}'
+    environment: "${{ github.event.inputs.environment || 'prod' }}"
     runs-on: 'ubuntu-latest'
     permissions:
       contents: 'read'
@@ -44,7 +44,7 @@ jobs:
         with:
           npm-package: '${{vars.CLI_PACKAGE_NAME}}@${{github.event.inputs.npm-tag}}'
           expected-version: '${{github.event.inputs.version}}'
-          ref: '${{github.ref}}'
+          working-directory: '.'
           gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
           npm-registry-url: '${{ vars.NPM_REGISTRY_URL }}'
           github-token: '${{ secrets.GITHUB_TOKEN }}'

.gitignore

@@ -17,7 +17,6 @@
 # Dependency directory
 node_modules
 bower_components
-package-lock.json
 
 # Editors
 .idea
@@ -47,9 +46,12 @@ packages/cli/src/generated/
 packages/core/src/generated/
 .integration-tests/
 packages/vscode-ide-companion/*.vsix
+packages/cli/download-ripgrep*/
 
 # GHA credentials
 gha-creds-*.json
 
 # Log files
 patch_output.log
+
+.genkit

.lycheeignore

@@ -0,0 +1,6 @@
+http://localhost:16686/
+https://github.com/google-gemini/gemini-cli/issues/new/choose
+https://github.com/google-gemini/maintainers-gemini-cli/blob/main/npm.md
+https://github.com/settings/personal-access-tokens/new
+https://github.com/settings/tokens/new
+https://www.npmjs.com/package/@google/gemini-cli

CONTRIBUTING.md

@@ -1,6 +1,18 @@
 # How to Contribute
 
-We would love to accept your patches and contributions to this project.
+We would love to accept your patches and contributions to this project. This
+document includes:
+
+- **[Before you begin](#before-you-begin):** Essential steps to take before
+  becoming a Gemini CLI contributor.
+- **[Code contribution process](#code-contribution-process):** How to contribute
+  code to Gemini CLI.
+- **[Development setup and workflow](#development-setup-and-workflow):** How to
+  set up your development environment and workflow.
+- **[Documentation contribution process](#documentation-contribution-process):**
+  How to contribute documentation to Gemini CLI.
+
+We're looking forward to seeing your contributions!
 
 ## Before you begin
 
@@ -23,15 +35,40 @@ sign a new one.
 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
 
-## Contribution Process
+## Code contribution process
 
-### Code Reviews
+### Get started
+
+The process for contributing code is as follows:
+
+1.  **Find an issue** that you want to work on.
+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`.
+5.  **Open a pull request** with your changes.
+
+### Code reviews
 
 All submissions, including submissions by project members, require review. We
 use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
 for this purpose.
 
-### Self Assigning Issues
+If your pull request involves changes to `packages/cli` (the frontend), we
+recommend running our automated frontend review tool. **Note: This tool is
+currently experimental.** It helps detect common React anti-patterns, testing
+issues, and other frontend-specific best practices that are easy to miss.
+
+To run the review tool, enter the following command from within Gemini CLI:
+
+```text
+/review-frontend <PR_NUMBER>
+```
+
+Replace `<PR_NUMBER>` with your pull request number. Authors are encouraged to
+run this on their own PRs for self-review, and reviewers should use it to
+augment their manual review process.
+
+### Self assigning issues
 
 If you're looking for an issue to work on, check out our list of issues that are
 labeled
@@ -44,12 +81,12 @@ assign the issue to you, provided it is not already assigned.
 Please note that you can have a maximum of 3 issues assigned to you at any given
 time.
 
-### Pull Request Guidelines
+### Pull request guidelines
 
 To help us review and merge your PRs quickly, please follow these guidelines.
 PRs that do not meet these standards may be closed.
 
-#### 1. Link to an Existing Issue
+#### 1. Link to an existing issue
 
 All PRs should be linked to an existing issue in our tracker. This ensures that
 every change has been discussed and is aligned with the project's goals before
@@ -62,7 +99,7 @@ any code is written.
 If an issue for your change doesn't exist, please **open one first** and wait
 for feedback before you start coding.
 
-#### 2. Keep It Small and Focused
+#### 2. Keep it small and focused
 
 We favor small, atomic PRs that address a single issue or add a single,
 self-contained feature.
@@ -74,37 +111,40 @@ self-contained feature.
 Large changes should be broken down into a series of smaller, logical PRs that
 can be reviewed and merged independently.
 
-#### 3. Use Draft PRs for Work in Progress
+#### 3. Use draft PRs for work in progress
 
 If you'd like to get early feedback on your work, please use GitHub's **Draft
 Pull Request** feature. This signals to the maintainers that the PR is not yet
 ready for a formal review but is open for discussion and initial feedback.
 
-#### 4. Ensure All Checks Pass
+#### 4. Ensure all checks pass
 
 Before submitting your PR, ensure that all automated checks are passing by
 running `npm run preflight`. This command runs all tests, linting, and other
 style checks.
 
-#### 5. Update Documentation
+#### 5. Update documentation
 
 If your PR introduces a user-facing change (e.g., a new command, a modified
 flag, or a change in behavior), you must also update the relevant documentation
 in the `/docs` directory.
 
-#### 6. Write Clear Commit Messages and a Good PR Description
+See more about writing documentation:
+[Documentation contribution process](#documentation-contribution-process).
+
+#### 6. Write clear commit messages and a good PR description
 
 Your PR should have a clear, descriptive title and a detailed description of the
 changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/)
 standard for your commit messages.
 
-- **Good PR Title:** `feat(cli): Add --json flag to 'config get' command`
-- **Bad PR Title:** `Made some changes`
+- **Good PR title:** `feat(cli): Add --json flag to 'config get' command`
+- **Bad PR title:** `Made some changes`
 
 In the PR description, explain the "why" behind your changes and link to the
 relevant issue (e.g., `Fixes #123`).
 
-## Forking
+### Forking
 
 If you are forking the repository you will be able to run the Build, Test and
 Integration test workflows. However in order to make the integration tests run
@@ -118,12 +158,12 @@ Additionally you will need to click on the `Actions` tab and enable workflows
 for your repository, you'll find it's the large blue button in the center of the
 screen.
 
-## Development Setup and Workflow
+### Development setup and workflow
 
 This section guides contributors on how to build, modify, and understand the
 development setup of this project.
 
-### Setting Up the Development Environment
+### Setting up the development environment
 
 **Prerequisites:**
 
@@ -135,7 +175,7 @@ development setup of this project.
       version of Node.js `>=20` is acceptable.
 2.  **Git**
 
-### Build Process
+### Build process
 
 To clone the repository:
 
@@ -160,7 +200,7 @@ This command typically compiles TypeScript to JavaScript, bundles assets, and
 prepares the packages for execution. Refer to `scripts/build.js` and
 `package.json` scripts for more details on what happens during the build.
 
-### Enabling Sandboxing
+### Enabling sandboxing
 
 [Sandboxing](#sandboxing) is highly recommended and requires, at a minimum,
 setting `GEMINI_SANDBOX=true` in your `~/.env` and ensuring a sandboxing
@@ -176,7 +216,7 @@ npm run build:all
 
 To skip building the sandbox container, you can use `npm run build` instead.
 
-### Running
+### Running the CLI
 
 To start the Gemini CLI from the source code (after building), run the following
 command from the root directory:
@@ -190,11 +230,11 @@ utilize `npm link path/to/gemini-cli/packages/cli` (see:
 [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) or
 `alias gemini="node path/to/gemini-cli/packages/cli"` to run with `gemini`
 
-### Running Tests
+### Running tests
 
 This project contains two types of tests: unit tests and integration tests.
 
-#### Unit Tests
+#### Unit tests
 
 To execute the unit test suite for the project:
 
@@ -206,7 +246,7 @@ This will run tests located in the `packages/core` and `packages/cli`
 directories. Ensure tests pass before submitting any changes. For a more
 comprehensive check, it is recommended to run `npm run preflight`.
 
-#### Integration Tests
+#### Integration tests
 
 The integration tests are designed to validate the end-to-end functionality of
 the Gemini CLI. They are not run as part of the default `npm run test` command.
@@ -218,9 +258,9 @@ npm run test:e2e
 ```
 
 For more detailed information on the integration testing framework, please see
-the [Integration Tests documentation](./docs/integration-tests.md).
+the [Integration Tests documentation](/docs/integration-tests.md).
 
-### Linting and Preflight Checks
+### Linting and preflight checks
 
 To ensure code quality and formatting consistency, run the preflight check:
 
@@ -267,7 +307,7 @@ root directory:
 npm run lint
 ```
 
-### Coding Conventions
+### Coding conventions
 
 - Please adhere to the coding style, patterns, and conventions used throughout
   the existing codebase.
@@ -279,19 +319,24 @@ npm run lint
 - **Imports:** Pay special attention to import paths. The project uses ESLint to
   enforce restrictions on relative imports between packages.
 
-### Project Structure
+### Project structure
 
 - `packages/`: Contains the individual sub-packages of the project.
+  - `a2a-server`: A2A server implementation for the Gemini CLI. (Experimental)
   - `cli/`: The command-line interface.
   - `core/`: The core backend logic for the Gemini CLI.
+  - `test-utils` Utilities for creating and cleaning temporary file systems for
+    testing.
+  - `vscode-ide-companion/`: The Gemini CLI Companion extension pairs with
+    Gemini CLI.
 - `docs/`: Contains all project documentation.
 - `scripts/`: Utility scripts for building, testing, and development tasks.
 
 For more detailed architecture, see `docs/architecture.md`.
 
-## Debugging
+### Debugging
 
-### VS Code:
+#### VS Code
 
 0.  Run the CLI to interactively debug in VS Code with `F5`
 1.  Start the CLI in debug mode from the root directory:
@@ -349,9 +394,9 @@ used for the CLI's interface, is compatible with React DevTools version 4.x.
     Your running CLI application should then connect to React DevTools.
     ![](/docs/assets/connected_devtools.png)
 
-## Sandboxing
+### Sandboxing
 
-### macOS Seatbelt
+#### macOS Seatbelt
 
 On macOS, `gemini` uses Seatbelt (`sandbox-exec`) under a `permissive-open`
 profile (see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) that
@@ -367,7 +412,7 @@ Available built-in profiles are `{permissive,restrictive}-{open,closed,proxied}`
 `.gemini/sandbox-macos-<profile>.sb` under your project settings directory
 `.gemini`.
 
-### Container-based Sandboxing (All Platforms)
+#### Container-based sandboxing (all platforms)
 
 For stronger container-based sandboxing on macOS or other platforms, you can set
 `GEMINI_SANDBOX=true|docker|podman|<command>` in your environment or `.env`
@@ -390,7 +435,7 @@ for your projects by creating the files `.gemini/sandbox.Dockerfile` and/or
 running `gemini` with `BUILD_SANDBOX=1` to trigger building of your custom
 sandbox.
 
-#### Proxied Networking
+#### Proxied networking
 
 All sandboxing methods, including macOS Seatbelt using `*-proxied` profiles,
 support restricting outbound network traffic through a custom proxy server that
@@ -401,7 +446,7 @@ connections to `example.com:443` (e.g. `curl https://example.com`) and declines
 all other requests. The proxy is started and stopped automatically alongside the
 sandbox.
 
-## Manual Publish
+### Manual publish
 
 We publish an artifact for each commit to our internal registry. But if you need
 to manually cut a local build, then run the following commands:
@@ -413,3 +458,91 @@ npm run auth
 npm run prerelease:dev
 npm publish --workspaces
 ```
+
+## Documentation contribution process
+
+Our documentation must be kept up-to-date with our code contributions. We want
+our documentation to be clear, concise, and helpful to our users. We value:
+
+- **Clarity:** Use simple and direct language. Avoid jargon where possible.
+- **Accuracy:** Ensure all information is correct and up-to-date.
+- **Completeness:** Cover all aspects of a feature or topic.
+- **Examples:** Provide practical examples to help users understand how to use
+  Gemini CLI.
+
+### Getting started
+
+The process for contributing to the documentation is similar to contributing
+code.
+
+1. **Fork the repository** and create a new branch.
+2. **Make your changes** in the `/docs` directory.
+3. **Preview your changes locally** in Markdown rendering.
+4. **Lint and format your changes.** Our preflight check includes linting and
+   formatting for documentation files.
+   ```bash
+   npm run preflight
+   ```
+5. **Open a pull request** with your changes.
+
+### Documentation structure
+
+Our documentation is organized using [sidebar.json](/docs/sidebar.json) as the
+table of contents. When adding new documentation:
+
+1. Create your markdown file **in the appropriate directory** under `/docs`.
+2. Add an entry to `sidebar.json` in the relevant section.
+3. Ensure all internal links use relative paths and point to existing files.
+
+### Style guide
+
+We follow the
+[Google Developer Documentation Style Guide](https://developers.google.com/style).
+Please refer to it for guidance on writing style, tone, and formatting.
+
+#### Key style points
+
+- Use sentence case for headings.
+- Write in second person ("you") when addressing the reader.
+- Use present tense.
+- Keep paragraphs short and focused.
+- Use code blocks with appropriate language tags for syntax highlighting.
+- Include practical examples whenever possible.
+
+### Linting and formatting
+
+We use `prettier` to enforce a consistent style across our documentation. The
+`npm run preflight` command will check for any linting issues.
+
+You can also run the linter and formatter separately:
+
+- `npm run lint` - Check for linting issues
+- `npm run format` - Auto-format markdown files
+- `npm run lint:fix` - Auto-fix linting issues where possible
+
+Please make sure your contributions are free of linting errors before submitting
+a pull request.
+
+### Before you submit
+
+Before submitting your documentation pull request, please:
+
+1. Run `npm run preflight` to ensure all checks pass.
+2. Review your changes for clarity and accuracy.
+3. Check that all links work correctly.
+4. Ensure any code examples are tested and functional.
+5. Sign the
+   [Contributor License Agreement (CLA)](https://cla.developers.google.com/) if
+   you haven't already.
+
+### Need help?
+
+If you have questions about contributing documentation:
+
+- Check our [FAQ](/docs/faq.md).
+- Review existing documentation for examples.
+- Open [an issue](https://github.com/google-gemini/gemini-cli/issues) to discuss
+  your proposed changes.
+- Reach out to the maintainers.
+
+We appreciate your contributions to making Gemini CLI documentation better!

README.md

@@ -11,6 +11,8 @@ Gemini CLI is an open-source AI agent that brings the power of Gemini directly
 into your terminal. It provides lightweight access to Gemini, giving you the
 most direct path from your prompt to our model.
 
+Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/).
+
 ## 🚀 Why Gemini CLI?
 
 - **🎯 Free tier**: 60 requests/min and 1,000 requests/day with personal Google
@@ -25,6 +27,11 @@ most direct path from your prompt to our model.
 
 ## 📦 Installation
 
+### Pre-requisites before installation
+
+- Node.js version 20 or higher
+- macOS, Linux, or Windows
+
 ### Quick Install
 
 #### Run instantly with npx
@@ -46,11 +53,6 @@ npm install -g @google/gemini-cli
 brew install gemini-cli
 ```
 
-#### System Requirements
-
-- Node.js version 20 or higher
-- macOS, Linux, or Windows
-
 ## Release Cadence and Tags
 
 See [Releases](./docs/releases.md) for more details.
@@ -228,6 +230,13 @@ the `--output-format json` flag to get structured output:
 gemini -p "Explain the architecture of this codebase" --output-format json
 ```
 
+For real-time event streaming (useful for monitoring long-running operations),
+use `--output-format stream-json` to get newline-delimited JSON events:
+
+```bash
+gemini -p "Run tests and deploy" --output-format stream-json
+```
+
 ### Quick Examples
 
 #### Start a new project
@@ -297,6 +306,8 @@ gemini
   corporate environment.
 - [**Telemetry & Monitoring**](./docs/cli/telemetry.md) - Usage tracking.
 - [**Tools API Development**](./docs/core/tools-api.md) - Create custom tools.
+- [**Local development**](./docs/local-development.md) - Local development
+  tooling.
 
 ### Troubleshooting & Support
 

docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/changelogs/index.md

@@ -3,6 +3,200 @@
 Wondering what's new in Gemini CLI? This document provides key highlights and
 notable changes to Gemini CLI.
 
+## v0.15.0 - Gemini CLI weekly update - 2025-11-03
+
+- **🎉 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!
+  ([gif](https://imgur.com/a/O6qc7bx),
+  [@jacob314](https://github.com/jacob314)).
+  - **Announcement:**
+    [https://developers.googleblog.com/en/making-the-terminal-beautiful-one-pixel-at-a-time/](https://developers.googleblog.com/en/making-the-terminal-beautiful-one-pixel-at-a-time/)
+- **🎉 New partner extensions:**
+  - **Arize:** Seamlessly instrument AI applications with Arize AX and grant
+    direct access to Arize support:
+
+    `gemini extensions install https://github.com/Arize-ai/arize-tracing-assistant`
+
+  - **Chronosphere:** Retrieve logs, metrics, traces, events, and specific
+    entities:
+
+    `gemini extensions install https://github.com/chronosphereio/chronosphere-mcp`
+
+  - **Transmit:** Comprehensive context, validation, and automated fixes for
+    creating production-ready authentication and identity workflows:
+
+    `gemini extensions install https://github.com/TransmitSecurity/transmit-security-journey-builder`
+
+- **Todo planning:** Complex questions now get broken down into todo lists that
+  the model can manage and check off. ([gif](https://imgur.com/a/EGDfNlZ),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/12905) by
+  [@anj-s](https://github.com/anj-s))
+- **Disable GitHub extensions:** Users can now prevent the installation and
+  loading of extensions from GitHub.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/12838) by
+  [@kevinjwang1](https://github.com/kevinjwang1)).
+- **Extensions restart:** Users can now explicitly restart extensions using the
+  `/extensions restart` command.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/12739) by
+  [@jakemac53](https://github.com/jakemac53)).
+- **Better Angular support:** Angular workflows should now be more seamless
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/10252) by
+  [@MarkTechson](https://github.com/MarkTechson)).
+- **Validate command:** Users can now check that local extensions are formatted
+  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
+
+![Codebase investigator subagent in Gemini CLI.](https://i.imgur.com/4J1njsx.png)
+
+- **🎉 New partner extensions:**
+  - **🤗 Hugging Face extension:** Access the Hugging Face hub.
+    ([gif](https://drive.google.com/file/d/1LEzIuSH6_igFXq96_tWev11svBNyPJEB/view?usp=sharing&resourcekey=0-LtPTzR1woh-rxGtfPzjjfg))
+
+    `gemini extensions install https://github.com/huggingface/hf-mcp-server`
+
+  - **Monday.com extension**: Analyze your sprints, update your task boards,
+    etc.
+    ([gif](https://drive.google.com/file/d/1cO0g6kY1odiBIrZTaqu5ZakaGZaZgpQv/view?usp=sharing&resourcekey=0-xEr67SIjXmAXRe1PKy7Jlw))
+
+    `gemini extensions install https://github.com/mondaycom/mcp`
+
+  - **Data Commons extension:** Query public datasets or ground responses on
+    data from Data Commons
+    ([gif](https://drive.google.com/file/d/1cuj-B-vmUkeJnoBXrO_Y1CuqphYc6p-O/view?usp=sharing&resourcekey=0-0adXCXDQEd91ZZW63HbW-Q)).
+
+    `gemini extensions install https://github.com/gemini-cli-extensions/datacommons`
+
+- **Model selection:** Choose the Gemini model for your session with `/model`.
+  ([pic](https://imgur.com/a/ABFcWWw),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/8940) by
+  [@abhipatel12](https://github.com/abhipatel12)).
+- **Model routing:** Gemini CLI will now intelligently pick the best model for
+  the task. Simple queries will be sent to Flash while complex analytical or
+  creative tasks will still use the power of Pro. This ensures your quota will
+  last for a longer period of time. You can always opt-out of this via `/model`.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/9262) by
+  [@abhipatel12](https://github.com/abhipatel12)).
+  - Discussion:
+    [https://github.com/google-gemini/gemini-cli/discussions/12375](https://github.com/google-gemini/gemini-cli/discussions/12375)
+- **Codebase investigator subagent:** We now have a new built-in subagent that
+  will explore your workspace and resolve relevant information to improve
+  overall performance.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/9988) by
+  [@abhipatel12](https://github.com/abhipatel12),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/10282) by
+  [@silviojr](https://github.com/silviojr)).
+  - Enable, disable, or limit turns in `/settings`, plus advanced configs in
+    `settings.json` ([pic](https://imgur.com/a/yJiggNO),
+    [pr](https://github.com/google-gemini/gemini-cli/pull/10844) by
+    [@silviojr](https://github.com/silviojr)).
+- **Explore extensions with `/extension`:** Users can now open the extensions
+  page in their default browser directly from the CLI using the `/extension`
+  explore command. ([pr](https://github.com/google-gemini/gemini-cli/pull/11846)
+  by [@JayadityaGit](https://github.com/JayadityaGit)).
+- **Configurable compression:** Users can modify the compression threshold in
+  `/settings`. The default has been made more proactive
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/12317) by
+  [@scidomino](https://github.com/scidomino)).
+- **API key authentication:** Users can now securely enter and store their
+  Gemini API key via a new dialog, eliminating the need for environment
+  variables and repeated entry.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/11760) by
+  [@galz10](https://github.com/galz10)).
+- **Sequential approval:** Users can now approve multiple tool calls
+  sequentially during execution.
+  ([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
+
+![Gemini CLI and Jules](https://storage.googleapis.com/gweb-developer-goog-blog-assets/images/Jules_Extension_-_Blog_Header_O346JNt.original.png)
+
+- 🎉 **Gemini CLI Jules Extension:** Use Gemini CLI to orchestrate Jules. Spawn
+  remote workers, delegate tedious tasks, or check in on running jobs!
+  - Install:
+    `gemini extensions install https://github.com/gemini-cli-extensions/jules`
+  - Announcement:
+    [https://developers.googleblog.com/en/introducing-the-jules-extension-for-gemini-cli/](https://developers.googleblog.com/en/introducing-the-jules-extension-for-gemini-cli/)
+- **Stream JSON output:** Stream real-time JSONL events with
+  `--output-format stream-json` to monitor AI agent progress when run
+  headlessly. ([gif](https://imgur.com/a/0UCE81X),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/10883) by
+  [@anj-s](https://github.com/anj-s))
+- **Markdown toggle:** Users can now switch between rendered and raw markdown
+  display using `alt+m `or` ctrl+m`. ([gif](https://imgur.com/a/lDNdLqr),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/10383) by
+  [@srivatsj](https://github.com/srivatsj))
+- **Queued message editing:** Users can now quickly edit queued messages by
+  pressing the up arrow key when the input is empty.
+  ([gif](https://imgur.com/a/ioRslLd),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/10392) by
+  [@akhil29](https://github.com/akhil29))
+- **JSON web fetch**: Non-HTML content like JSON APIs or raw source code are now
+  properly shown to the model (previously only supported HTML)
+  ([gif](https://imgur.com/a/Q58U4qJ),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/11284) by
+  [@abhipatel12](https://github.com/abhipatel12))
+- **Non-interactive MCP commands:** Users can now run MCP slash commands in
+  non-interactive mode `gemini "/some-mcp-prompt"`.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/10194) by
+  [@capachino](https://github.com/capachino))
+- **Removal of deprecated flags:** We’ve finally removed a number of deprecated
+  flags to cleanup Gemini CLI’s invocation profile:
+  - `--all-files` / `-a` in favor of `@` from within Gemini CLI.
+    ([pr](https://github.com/google-gemini/gemini-cli/pull/11228) by
+    [@allenhutchison](https://github.com/allenhutchison))
+  - `--telemetry-*` flags in favor of
+    [environment variables](https://github.com/google-gemini/gemini-cli/pull/11318)
+    ([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
+
+- **Polish:** The team has been heads down bug fixing and investing heavily into
+  polishing existing flows, tools, and interactions.
+- **Interactive Shell Tool calling:** Gemini CLI can now also execute
+  interactive tools if needed
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/11225) by
+  [@galz10](https://github.com/galz10)).
+- **Alt+Key support:** Enables broader support for Alt+Key keyboard shortcuts
+  across different terminals.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/10767) by
+  [@srivatsj](https://github.com/srivatsj)).
+- **Telemetry Diff stats:** Track line changes made by the model and user during
+  file operations via OTEL.
+  ([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
+
+- 🎉 **Interactive Shell:** Run interactive commands like `vim`, `rebase -i`, or
+  even `gemini` 😎 directly in Gemini CLI:
+  - Blog:
+    [https://developers.googleblog.com/en/say-hello-to-a-new-level-of-interactivity-in-gemini-cli/](https://developers.googleblog.com/en/say-hello-to-a-new-level-of-interactivity-in-gemini-cli/)
+- **Install pre-release extensions:** Install the latest `--pre-release`
+  versions of extensions. Used for when an extension’s release hasn’t been
+  marked as "latest".
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/10752) by
+  [@jakemac53](https://github.com/jakemac53))
+- **Simplified extension creation:** Create a new, empty extension. Templates
+  are no longer required.
+  ([pr](https://github.com/google-gemini/gemini-cli/pull/10629) by
+  [@chrstnb](https://github.com/chrstnb))
+- **OpenTelemetry GenAI metrics:** Aligns telemetry with industry-standard
+  semantic conventions for improved interoperability.
+  ([spec](https://opentelemetry.io/docs/concepts/semantic-conventions/),
+  [pr](https://github.com/google-gemini/gemini-cli/pull/10343) by
+  [@jerop](https://github.com/jerop))
+- **List memory files:** Quickly find the location of your long-term memory
+  files with `/memory list`.
+  ([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
 
 - 🎉 **Announcing Gemini CLI Extensions** 🎉
@@ -246,7 +440,7 @@ notable changes to Gemini CLI.
   `"showCitations": true`
   ([pr](https://github.com/google-gemini/gemini-cli/pull/7350) by
   [@scidomino](https://github.com/scidomino))
-- **Pro Quota Ddalog:** Handle daily Pro model usage limits with an interactive
+- **Pro Quota Dialog:** Handle daily Pro model usage limits with an interactive
   dialog that lets you immediately switch auth or fallback.
   ([pr](https://github.com/google-gemini/gemini-cli/pull/7094) by
   [@JayadityaGit](https://github.com/JayadityaGit))

docs/cli/checkpointing.md

@@ -37,22 +37,12 @@ file in your project's temporary directory, typically located at
 
 ## Enabling the Feature
 
-The Checkpointing feature is disabled by default. To enable it, you can either
-use a command-line flag or edit your `settings.json` file.
+The Checkpointing feature is disabled by default. To enable it, you need to edit
+your `settings.json` file.
 
-### Using the Command-Line Flag
-
-You can enable checkpointing for the current session by using the
-`--checkpointing` flag when starting the Gemini CLI:
-
-```bash
-gemini --checkpointing
-```
-
-### Using the `settings.json` File
-
-To enable checkpointing by default for all sessions, you need to edit your
-`settings.json` file.
+> **Note:** The `--checkpointing` command-line flag was removed in version
+> 0.11.0. Checkpointing can now only be enabled through the `settings.json`
+> configuration file.
 
 Add the following key to your `settings.json`:
 

docs/cli/commands.md

@@ -30,8 +30,9 @@ Slash commands provide meta-level control over the CLI itself.
         checkpoints are:
         - Linux/macOS: `~/.gemini/tmp/<project_hash>/`
         - Windows: `C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\`
-        - When you run `/chat list`, the CLI only scans these specific
-          directories to find available checkpoints.
+        - **Behavior:** Chats are saved into a project-specific directory,
+          determined by where you run the CLI. Consequently, saved chats are
+          only accessible when working within that same project.
         - **Note:** These checkpoints are for manually saving and resuming
           conversation states. For automatic checkpoints created before file
           modifications, see the
@@ -39,8 +40,14 @@ Slash commands provide meta-level control over the CLI itself.
     - **`resume`**
       - **Description:** Resumes a conversation from a previous save.
       - **Usage:** `/chat resume <tag>`
+      - **Note:** You can only resume chats that were saved within the current
+        project. To resume a chat from a different project, you must run the
+        Gemini CLI from that project's directory.
     - **`list`**
       - **Description:** Lists available tags for chat state resumption.
+      - **Note:** This command only lists chats saved within the current
+        project. Because chat history is project-scoped, chats saved in other
+        project directories will not be displayed.
     - **`delete`**
       - **Description:** Deletes a saved conversation checkpoint.
       - **Usage:** `/chat delete <tag>`
@@ -100,18 +107,29 @@ Slash commands provide meta-level control over the CLI itself.
     available commands and their usage.
 
 - **`/mcp`**
-  - **Description:** List configured Model Context Protocol (MCP) servers, their
-    connection status, server details, and available tools.
+  - **Description:** Manage configured Model Context Protocol (MCP) servers.
   - **Sub-commands:**
-    - **`desc`** or **`descriptions`**:
-      - **Description:** Show detailed descriptions for MCP servers and tools.
-    - **`nodesc`** or **`nodescriptions`**:
-      - **Description:** Hide tool descriptions, showing only the tool names.
+    - **`list`** or **`ls`**:
+      - **Description:** List configured MCP servers and tools. This is the
+        default action if no subcommand is specified.
+    - **`desc`**
+      - **Description:** List configured MCP servers and tools with
+        descriptions.
     - **`schema`**:
-      - **Description:** Show the full JSON schema for the tool's configured
-        parameters.
-  - **Keyboard Shortcut:** Press **Ctrl+T** at any time to toggle between
-    showing and hiding tool descriptions.
+      - **Description:** List configured MCP servers and tools with descriptions
+        and schemas.
+    - **`auth`**:
+      - **Description:** Authenticate with an OAuth-enabled MCP server.
+      - **Usage:** `/mcp auth <server-name>`
+      - **Details:** If `<server-name>` is provided, it initiates the OAuth flow
+        for that server. If no server name is provided, it lists all configured
+        servers that support OAuth authentication.
+    - **`refresh`**:
+      - **Description:** Restarts all MCP servers and re-discovers their
+        available tools.
+
+- [**`/model`**](./model.md)
+  - **Description:** Opens a dialog to choose your Gemini model.
 
 - **`/memory`**
   - **Description:** Manage the AI's instructional context (hierarchical memory
@@ -143,17 +161,19 @@ Slash commands provide meta-level control over the CLI itself.
     edits made by a tool. If run without a tool call ID, it will list available
     checkpoints to restore from.
   - **Usage:** `/restore [tool_call_id]`
-  - **Note:** Only available if the CLI is invoked with the `--checkpointing`
-    option or configured via [settings](../get-started/configuration.md). See
+  - **Note:** Only available if checkpointing is configured via
+    [settings](../get-started/configuration.md). See
     [Checkpointing documentation](../cli/checkpointing.md) for more details.
 
-- **`/settings`**
+- [**`/settings`**](./settings.md)
   - **Description:** Open the settings editor to view and modify Gemini CLI
     settings.
   - **Details:** This command provides a user-friendly interface for changing
     settings that control the behavior and appearance of Gemini CLI. It is
     equivalent to manually editing the `.gemini/settings.json` file, but with
-    validation and guidance to prevent errors.
+    validation and guidance to prevent errors. See the
+    [settings documentation](./settings.md) for a full list of available
+    settings.
   - **Usage:** Simply run `/settings` and the editor will open. You can then
     browse or search for specific settings, view their current values, and
     modify them as desired. Changes to some settings are applied immediately,
@@ -292,8 +312,9 @@ Gemini CLI.
 
 - **`!<shell_command>`**
   - **Description:** Execute the given `<shell_command>` using `bash` on
-    Linux/macOS or `cmd.exe` on Windows. Any output or errors from the command
-    are displayed in the terminal.
+    Linux/macOS or `powershell.exe -NoProfile -Command` on Windows (unless you
+    override `ComSpec`). Any output or errors from the command are displayed in
+    the terminal.
   - **Examples:**
     - `!ls -la` (executes `ls -la` and returns to Gemini CLI)
     - `!git status` (executes `git status` and returns to Gemini CLI)

docs/cli/configuration.md

@@ -0,0 +1,768 @@
+# Gemini CLI Configuration
+
+Gemini CLI offers several ways to configure its behavior, including environment
+variables, command-line arguments, and settings files. This document outlines
+the different configuration methods and available settings.
+
+## Configuration layers
+
+Configuration is applied in the following order of precedence (lower numbers are
+overridden by higher numbers):
+
+1.  **Default values:** Hardcoded defaults within the application.
+2.  **User settings file:** Global settings for the current user.
+3.  **Project settings file:** Project-specific settings.
+4.  **System settings file:** System-wide settings.
+5.  **Environment variables:** System-wide or session-specific variables,
+    potentially loaded from `.env` files.
+6.  **Command-line arguments:** Values passed when launching the CLI.
+
+## Settings files
+
+Gemini CLI uses `settings.json` files for persistent configuration. There are
+three locations for these files:
+
+- **User settings file:**
+  - **Location:** `~/.gemini/settings.json` (where `~` is your home directory).
+  - **Scope:** Applies to all Gemini CLI sessions for the current user.
+- **Project settings file:**
+  - **Location:** `.gemini/settings.json` within your project's root directory.
+  - **Scope:** Applies only when running Gemini CLI from that specific project.
+    Project settings override user settings.
+- **System settings file:**
+  - **Location:** `/etc/gemini-cli/settings.json` (Linux),
+    `C:\ProgramData\gemini-cli\settings.json` (Windows) or
+    `/Library/Application Support/GeminiCli/settings.json` (macOS). The path can
+    be overridden using the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` environment
+    variable.
+  - **Scope:** Applies to all Gemini CLI sessions on the system, for all users.
+    System settings override user and project settings. May be useful for system
+    administrators at enterprises to have controls over users' Gemini CLI
+    setups.
+
+**Note on environment variables in settings:** String values within your
+`settings.json` files can reference environment variables using either
+`$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically
+resolved when the settings are loaded. For example, if you have an environment
+variable `MY_API_TOKEN`, you could use it in `settings.json` like this:
+`"apiKey": "$MY_API_TOKEN"`.
+
+### The `.gemini` directory in your project
+
+In addition to a project settings file, a project's `.gemini` directory can
+contain other project-specific files related to Gemini CLI's operation, such as:
+
+- [Custom sandbox profiles](#sandboxing) (e.g.,
+  `.gemini/sandbox-macos-custom.sb`, `.gemini/sandbox.Dockerfile`).
+
+### Available settings in `settings.json`:
+
+- **`contextFileName`** (string or array of strings):
+  - **Description:** Specifies the filename for context files (e.g.,
+    `GEMINI.md`, `AGENTS.md`). Can be a single filename or a list of accepted
+    filenames.
+  - **Default:** `GEMINI.md`
+  - **Example:** `"contextFileName": "AGENTS.md"`
+
+- **`bugCommand`** (object):
+  - **Description:** Overrides the default URL for the `/bug` command.
+  - **Default:**
+    `"urlTemplate": "https://github.com/google-gemini/gemini-cli/issues/new?template=bug_report.yml&title={title}&info={info}"`
+  - **Properties:**
+    - **`urlTemplate`** (string): A URL that can contain `{title}` and `{info}`
+      placeholders.
+  - **Example:**
+    ```json
+    "bugCommand": {
+      "urlTemplate": "https://bug.example.com/new?title={title}&info={info}"
+    }
+    ```
+
+- **`fileFiltering`** (object):
+  - **Description:** Controls git-aware file filtering behavior for @ commands
+    and file discovery tools.
+  - **Default:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true`
+  - **Properties:**
+    - **`respectGitIgnore`** (boolean): Whether to respect .gitignore patterns
+      when discovering files. When set to `true`, git-ignored files (like
+      `node_modules/`, `dist/`, `.env`) are automatically excluded from @
+      commands and file listing operations.
+    - **`enableRecursiveFileSearch`** (boolean): Whether to enable searching
+      recursively for filenames under the current tree when completing @
+      prefixes in the prompt.
+  - **Example:**
+    ```json
+    "fileFiltering": {
+      "respectGitIgnore": true,
+      "enableRecursiveFileSearch": false
+    }
+    ```
+
+- **`coreTools`** (array of strings):
+  - **Description:** Allows you to specify a list of core tool names that should
+    be made available to the model. This can be used to restrict the set of
+    built-in tools. See [Built-in Tools](../core/tools-api.md#built-in-tools)
+    for a list of core tools. You can also specify command-specific restrictions
+    for tools that support it, like the `ShellTool`. For example,
+    `"coreTools": ["ShellTool(ls -l)"]` will only allow the `ls -l` command to
+    be executed.
+  - **Default:** All tools available for use by the Gemini model.
+  - **Example:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`.
+
+- **`excludeTools`** (array of strings):
+  - **Description:** Allows you to specify a list of core tool names that should
+    be excluded from the model. A tool listed in both `excludeTools` and
+    `coreTools` is excluded. You can also specify command-specific restrictions
+    for tools that support it, like the `ShellTool`. For example,
+    `"excludeTools": ["ShellTool(rm -rf)"]` will block the `rm -rf` command.
+  - **Default**: No tools excluded.
+  - **Example:** `"excludeTools": ["run_shell_command", "findFiles"]`.
+  - **Security Note:** Command-specific restrictions in `excludeTools` for
+    `run_shell_command` are based on simple string matching and can be easily
+    bypassed. This feature is **not a security mechanism** and should not be
+    relied upon to safely execute untrusted code. It is recommended to use
+    `coreTools` to explicitly select commands that can be executed.
+
+- **`allowMCPServers`** (array of strings):
+  - **Description:** Allows you to specify a list of MCP server names that
+    should be made available to the model. This can be used to restrict the set
+    of MCP servers to connect to. Note that this will be ignored if
+    `--allowed-mcp-server-names` is set.
+  - **Default:** All MCP servers are available for use by the Gemini model.
+  - **Example:** `"allowMCPServers": ["myPythonServer"]`.
+  - **Security Note:** This uses simple string matching on MCP server names,
+    which can be modified. If you're a system administrator looking to prevent
+    users from bypassing this, consider configuring the `mcpServers` at the
+    system settings level such that the user will not be able to configure any
+    MCP servers of their own. This should not be used as an airtight security
+    mechanism.
+
+- **`excludeMCPServers`** (array of strings):
+  - **Description:** Allows you to specify a list of MCP server names that
+    should be excluded from the model. A server listed in both
+    `excludeMCPServers` and `allowMCPServers` is excluded. Note that this will
+    be ignored if `--allowed-mcp-server-names` is set.
+  - **Default**: No MCP servers excluded.
+  - **Example:** `"excludeMCPServers": ["myNodeServer"]`.
+  - **Security Note:** This uses simple string matching on MCP server names,
+    which can be modified. If you're a system administrator looking to prevent
+    users from bypassing this, consider configuring the `mcpServers` at the
+    system settings level such that the user will not be able to configure any
+    MCP servers of their own. This should not be used as an airtight security
+    mechanism.
+
+- **`autoAccept`** (boolean):
+  - **Description:** Controls whether the CLI automatically accepts and executes
+    tool calls that are considered safe (e.g., read-only operations) without
+    explicit user confirmation. If set to `true`, the CLI will bypass the
+    confirmation prompt for tools deemed safe.
+  - **Default:** `false`
+  - **Example:** `"autoAccept": true`
+
+- **`theme`** (string):
+  - **Description:** Sets the visual [theme](./themes.md) for Gemini CLI.
+  - **Default:** `"Default"`
+  - **Example:** `"theme": "GitHub"`
+
+- **`vimMode`** (boolean):
+  - **Description:** Enables or disables vim mode for input editing. When
+    enabled, the input area supports vim-style navigation and editing commands
+    with NORMAL and INSERT modes. The vim mode status is displayed in the footer
+    and persists between sessions.
+  - **Default:** `false`
+  - **Example:** `"vimMode": true`
+
+- **`sandbox`** (boolean or string):
+  - **Description:** Controls whether and how to use sandboxing for tool
+    execution. If set to `true`, Gemini CLI uses a pre-built
+    `gemini-cli-sandbox` Docker image. For more information, see
+    [Sandboxing](#sandboxing).
+  - **Default:** `false`
+  - **Example:** `"sandbox": "docker"`
+
+- **`toolDiscoveryCommand`** (string):
+  - **Description:** Defines a custom shell command for discovering tools from
+    your project. The shell command must return on `stdout` a JSON array of
+    [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations).
+    Tool wrappers are optional.
+  - **Default:** Empty
+  - **Example:** `"toolDiscoveryCommand": "bin/get_tools"`
+
+- **`toolCallCommand`** (string):
+  - **Description:** Defines a custom shell command for calling a specific tool
+    that was discovered using `toolDiscoveryCommand`. The shell command must
+    meet the following criteria:
+    - It must take function `name` (exactly as in
+      [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations))
+      as first command line argument.
+    - It must read function arguments as JSON on `stdin`, analogous to
+      [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall).
+    - It must return function output as JSON on `stdout`, analogous to
+      [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse).
+  - **Default:** Empty
+  - **Example:** `"toolCallCommand": "bin/call_tool"`
+
+- **`mcpServers`** (object):
+  - **Description:** Configures connections to one or more Model-Context
+    Protocol (MCP) servers for discovering and using custom tools. Gemini CLI
+    attempts to connect to each configured MCP server to discover available
+    tools. If multiple MCP servers expose a tool with the same name, the tool
+    names will be prefixed with the server alias you defined in the
+    configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note
+    that the system might strip certain schema properties from MCP tool
+    definitions for compatibility.
+  - **Default:** Empty
+  - **Properties:**
+    - **`<SERVER_NAME>`** (object): The server parameters for the named server.
+      - `command` (string, required): The command to execute to start the MCP
+        server.
+      - `args` (array of strings, optional): Arguments to pass to the command.
+      - `env` (object, optional): Environment variables to set for the server
+        process.
+      - `cwd` (string, optional): The working directory in which to start the
+        server.
+      - `timeout` (number, optional): Timeout in milliseconds for requests to
+        this MCP server.
+      - `trust` (boolean, optional): Trust this server and bypass all tool call
+        confirmations.
+      - `includeTools` (array of strings, optional): List of tool names to
+        include from this MCP server. When specified, only the tools listed here
+        will be available from this server (whitelist behavior). If not
+        specified, all tools from the server are enabled by default.
+      - `excludeTools` (array of strings, optional): List of tool names to
+        exclude from this MCP server. Tools listed here will not be available to
+        the model, even if they are exposed by the server. **Note:**
+        `excludeTools` takes precedence over `includeTools` - if a tool is in
+        both lists, it will be excluded.
+  - **Example:**
+    ```json
+    "mcpServers": {
+      "myPythonServer": {
+        "command": "python",
+        "args": ["mcp_server.py", "--port", "8080"],
+        "cwd": "./mcp_tools/python",
+        "timeout": 5000,
+        "includeTools": ["safe_tool", "file_reader"],
+      },
+      "myNodeServer": {
+        "command": "node",
+        "args": ["mcp_server.js"],
+        "cwd": "./mcp_tools/node",
+        "excludeTools": ["dangerous_tool", "file_deleter"]
+      },
+      "myDockerServer": {
+        "command": "docker",
+        "args": ["run", "-i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"],
+        "env": {
+          "API_KEY": "$MY_API_TOKEN"
+        }
+      }
+    }
+    ```
+
+- **`checkpointing`** (object):
+  - **Description:** Configures the checkpointing feature, which allows you to
+    save and restore conversation and file states. See the
+    [Checkpointing documentation](./checkpointing.md) for more details.
+  - **Default:** `{"enabled": false}`
+  - **Properties:**
+    - **`enabled`** (boolean): When `true`, the `/restore` command is available.
+
+- **`preferredEditor`** (string):
+  - **Description:** Specifies the preferred editor to use for viewing diffs.
+  - **Default:** `vscode`
+  - **Example:** `"preferredEditor": "vscode"`
+
+- **`telemetry`** (object)
+  - **Description:** Configures logging and metrics collection for Gemini CLI.
+    For more information, see [Telemetry](./telemetry.md).
+  - **Default:**
+    `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}`
+  - **Properties:**
+    - **`enabled`** (boolean): Whether or not telemetry is enabled.
+    - **`target`** (string): The destination for collected telemetry. Supported
+      values are `local` and `gcp`.
+    - **`otlpEndpoint`** (string): The endpoint for the OTLP Exporter.
+    - **`logPrompts`** (boolean): Whether or not to include the content of user
+      prompts in the logs.
+  - **Example:**
+    ```json
+    "telemetry": {
+      "enabled": true,
+      "target": "local",
+      "otlpEndpoint": "http://localhost:16686",
+      "logPrompts": false
+    }
+    ```
+- **`usageStatisticsEnabled`** (boolean):
+  - **Description:** Enables or disables the collection of usage statistics. See
+    [Usage Statistics](#usage-statistics) for more information.
+  - **Default:** `true`
+  - **Example:**
+    ```json
+    "usageStatisticsEnabled": false
+    ```
+
+- **`hideTips`** (boolean):
+  - **Description:** Enables or disables helpful tips in the CLI interface.
+  - **Default:** `false`
+  - **Example:**
+
+    ```json
+    "hideTips": true
+    ```
+
+- **`hideBanner`** (boolean):
+  - **Description:** Enables or disables the startup banner (ASCII art logo) in
+    the CLI interface.
+  - **Default:** `false`
+  - **Example:**
+
+    ```json
+    "hideBanner": true
+    ```
+
+- **`maxSessionTurns`** (number):
+  - **Description:** Sets the maximum number of turns for a session. If the
+    session exceeds this limit, the CLI will stop processing and start a new
+    chat.
+  - **Default:** `-1` (unlimited)
+  - **Example:**
+    ```json
+    "maxSessionTurns": 10
+    ```
+
+- **`summarizeToolOutput`** (object):
+  - **Description:** Enables or disables the summarization of tool output. You
+    can specify the token budget for the summarization using the `tokenBudget`
+    setting.
+  - Note: Currently only the `run_shell_command` tool is supported.
+  - **Default:** `{}` (Disabled by default)
+  - **Example:**
+    ```json
+    "summarizeToolOutput": {
+      "run_shell_command": {
+        "tokenBudget": 2000
+      }
+    }
+    ```
+
+- **`excludedProjectEnvVars`** (array of strings):
+  - **Description:** Specifies environment variables that should be excluded
+    from being loaded from project `.env` files. This prevents project-specific
+    environment variables (like `DEBUG=true`) from interfering with gemini-cli
+    behavior. Variables from `.gemini/.env` files are never excluded.
+  - **Default:** `["DEBUG", "DEBUG_MODE"]`
+  - **Example:**
+    ```json
+    "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
+    ```
+
+- **`includeDirectories`** (array of strings):
+  - **Description:** Specifies an array of additional absolute or relative paths
+    to include in the workspace context. This allows you to work with files
+    across multiple directories as if they were one. Paths can use `~` to refer
+    to the user's home directory. This setting can be combined with the
+    `--include-directories` command-line flag.
+  - **Default:** `[]`
+  - **Example:**
+    ```json
+    "includeDirectories": [
+      "/path/to/another/project",
+      "../shared-library",
+      "~/common-utils"
+    ]
+    ```
+
+- **`loadMemoryFromIncludeDirectories`** (boolean):
+  - **Description:** Controls the behavior of the `/memory refresh` command. If
+    set to `true`, `GEMINI.md` files should be loaded from all directories that
+    are added. If set to `false`, `GEMINI.md` should only be loaded from the
+    current directory.
+  - **Default:** `false`
+  - **Example:**
+    ```json
+    "loadMemoryFromIncludeDirectories": true
+    ```
+
+### Example `settings.json`:
+
+```json
+{
+  "theme": "GitHub",
+  "sandbox": "docker",
+  "toolDiscoveryCommand": "bin/get_tools",
+  "toolCallCommand": "bin/call_tool",
+  "mcpServers": {
+    "mainServer": {
+      "command": "bin/mcp_server.py"
+    },
+    "anotherServer": {
+      "command": "node",
+      "args": ["mcp_server.js", "--verbose"]
+    }
+  },
+  "telemetry": {
+    "enabled": true,
+    "target": "local",
+    "otlpEndpoint": "http://localhost:4317",
+    "logPrompts": true
+  },
+  "usageStatisticsEnabled": true,
+  "hideTips": false,
+  "hideBanner": false,
+  "maxSessionTurns": 10,
+  "summarizeToolOutput": {
+    "run_shell_command": {
+      "tokenBudget": 100
+    }
+  },
+  "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"],
+  "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
+  "loadMemoryFromIncludeDirectories": true
+}
+```
+
+## Shell History
+
+The CLI keeps a history of shell commands you run. To avoid conflicts between
+different projects, this history is stored in a project-specific directory
+within your user's home folder.
+
+- **Location:** `~/.gemini/tmp/<project_hash>/shell_history`
+  - `<project_hash>` is a unique identifier generated from your project's root
+    path.
+  - The history is stored in a file named `shell_history`.
+
+## Environment Variables & `.env` Files
+
+Environment variables are a common way to configure applications, especially for
+sensitive information like API keys or for settings that might change between
+environments.
+
+The CLI automatically loads environment variables from an `.env` file. The
+loading order is:
+
+1.  `.env` file in the current working directory.
+2.  If not found, it searches upwards in parent directories until it finds an
+    `.env` file or reaches the project root (identified by a `.git` folder) or
+    the home directory.
+3.  If still not found, it looks for `~/.env` (in the user's home directory).
+
+**Environment Variable Exclusion:** Some environment variables (like `DEBUG` and
+`DEBUG_MODE`) are automatically excluded from being loaded from project `.env`
+files to prevent interference with gemini-cli behavior. Variables from
+`.gemini/.env` files are never excluded. You can customize this behavior using
+the `excludedProjectEnvVars` setting in your `settings.json` file.
+
+- **`GEMINI_API_KEY`** (Required):
+  - Your API key for the Gemini API.
+  - **Crucial for operation.** The CLI will not function without it.
+  - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env`
+    file.
+- **`GEMINI_MODEL`**:
+  - Specifies the default Gemini model to use.
+  - Overrides the hardcoded default
+  - Example: `export GEMINI_MODEL="gemini-2.5-flash"`
+- **`GOOGLE_API_KEY`**:
+  - Your Google Cloud API key.
+  - Required for using Vertex AI in express mode.
+  - Ensure you have the necessary permissions.
+  - Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`.
+- **`GOOGLE_CLOUD_PROJECT`**:
+  - Your Google Cloud Project ID.
+  - Required for using Code Assist or Vertex AI.
+  - If using Vertex AI, ensure you have the necessary permissions in this
+    project.
+  - **Cloud Shell Note:** When running in a Cloud Shell environment, this
+    variable defaults to a special project allocated for Cloud Shell users. If
+    you have `GOOGLE_CLOUD_PROJECT` set in your global environment in Cloud
+    Shell, it will be overridden by this default. To use a different project in
+    Cloud Shell, you must define `GOOGLE_CLOUD_PROJECT` in a `.env` file.
+  - Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`.
+- **`GOOGLE_APPLICATION_CREDENTIALS`** (string):
+  - **Description:** The path to your Google Application Credentials JSON file.
+  - **Example:**
+    `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"`
+- **`OTLP_GOOGLE_CLOUD_PROJECT`**:
+  - Your Google Cloud Project ID for Telemetry in Google Cloud
+  - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`.
+- **`GOOGLE_CLOUD_LOCATION`**:
+  - Your Google Cloud Project Location (e.g., us-central1).
+  - Required for using Vertex AI in non express mode.
+  - Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`.
+- **`GEMINI_SANDBOX`**:
+  - Alternative to the `sandbox` setting in `settings.json`.
+  - Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
+- **`SEATBELT_PROFILE`** (macOS specific):
+  - Switches the Seatbelt (`sandbox-exec`) profile on macOS.
+  - `permissive-open`: (Default) Restricts writes to the project folder (and a
+    few other folders, see
+    `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other
+    operations.
+  - `strict`: Uses a strict profile that declines operations by default.
+  - `<profile_name>`: Uses a custom profile. To define a custom profile, create
+    a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/`
+    directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
+- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI
+  itself):
+  - Set to `true` or `1` to enable verbose debug logging, which can be helpful
+    for troubleshooting.
+  - **Note:** These variables are automatically excluded from project `.env`
+    files by default to prevent interference with gemini-cli behavior. Use
+    `.gemini/.env` files if you need to set these for gemini-cli specifically.
+- **`NO_COLOR`**:
+  - Set to any value to disable all color output in the CLI.
+- **`CLI_TITLE`**:
+  - Set to a string to customize the title of the CLI.
+- **`CODE_ASSIST_ENDPOINT`**:
+  - Specifies the endpoint for the code assist server.
+  - This is useful for development and testing.
+- **`GEMINI_SYSTEM_MD`**:
+  - Overrides the base system prompt with the contents of a Markdown file.
+  - If set to `1` or `true`, it uses the file at `.gemini/system.md`.
+  - If set to a file path, it uses that file. The path can be absolute or
+    relative. `~` is supported for the home directory.
+  - The specified file must exist.
+- **`GEMINI_WRITE_SYSTEM_MD`**:
+  - Writes the default system prompt to a file. This is useful for getting a
+    template to customize.
+  - If set to `1` or `true`, it writes to `.gemini/system.md`.
+  - If set to a file path, it writes to that path. The path can be absolute or
+    relative. `~` is supported for the home directory. **Note: This will
+    overwrite the file if it already exists.**
+
+## Command-Line Arguments
+
+Arguments passed directly when running the CLI can override other configurations
+for that specific session.
+
+- **`--model <model_name>`** (**`-m <model_name>`**):
+  - Specifies the Gemini model to use for this session.
+  - Example: `npm start -- --model gemini-1.5-pro-latest`
+- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
+  - Used to pass a prompt directly to the command. This invokes Gemini CLI in a
+    non-interactive mode.
+- **`--prompt-interactive <your_prompt>`** (**`-i <your_prompt>`**):
+  - Starts an interactive session with the provided prompt as the initial input.
+  - The prompt is processed within the interactive session, not before it.
+  - Cannot be used when piping input from stdin.
+  - Example: `gemini -i "explain this code"`
+- **`--sandbox`** (**`-s`**):
+  - Enables sandbox mode for this session.
+- **`--sandbox-image`**:
+  - Sets the sandbox image URI.
+- **`--debug`** (**`-d`**):
+  - Enables debug mode for this session, providing more verbose output.
+- **`--all-files`** (**`-a`**):
+  - If set, recursively includes all files within the current directory as
+    context for the prompt.
+- **`--help`** (or **`-h`**):
+  - Displays help information about command-line arguments.
+- **`--show-memory-usage`**:
+  - Displays the current memory usage.
+- **`--yolo`**:
+  - Enables YOLO mode, which automatically approves all tool calls.
+- **`--telemetry`**:
+  - Enables [telemetry](./telemetry.md).
+- **`--telemetry-target`**:
+  - Sets the telemetry target. See [telemetry](./telemetry.md) for more
+    information.
+- **`--telemetry-otlp-endpoint`**:
+  - Sets the OTLP endpoint for telemetry. See [telemetry](./telemetry.md) for
+    more information.
+- **`--telemetry-log-prompts`**:
+  - Enables logging of prompts for telemetry. See [telemetry](./telemetry.md)
+    for more information.
+- **`--extensions <extension_name ...>`** (**`-e <extension_name ...>`**):
+  - Specifies a list of extensions to use for the session. If not provided, all
+    available extensions are used.
+  - Use the special term `gemini -e none` to disable all extensions.
+  - Example: `gemini -e my-extension -e my-other-extension`
+- **`--list-extensions`** (**`-l`**):
+  - Lists all available extensions and exits.
+- **`--proxy`**:
+  - Sets the proxy for the CLI.
+  - Example: `--proxy http://localhost:7890`.
+- **`--include-directories <dir1,dir2,...>`**:
+  - Includes additional directories in the workspace for multi-directory
+    support.
+  - Can be specified multiple times or as comma-separated values.
+  - 5 directories can be added at maximum.
+  - Example: `--include-directories /path/to/project1,/path/to/project2` or
+    `--include-directories /path/to/project1 --include-directories /path/to/project2`
+- **`--version`**:
+  - Displays the version of the CLI.
+
+## Context Files (Hierarchical Instructional Context)
+
+While not strictly configuration for the CLI's _behavior_, context files
+(defaulting to `GEMINI.md` but configurable via the `contextFileName` setting)
+are crucial for configuring the _instructional context_ (also referred to as
+"memory") provided to the Gemini model. This powerful feature allows you to give
+project-specific instructions, coding style guides, or any relevant background
+information to the AI, making its responses more tailored and accurate to your
+needs. The CLI includes UI elements, such as an indicator in the footer showing
+the number of loaded context files, to keep you informed about the active
+context.
+
+- **Purpose:** These Markdown files contain instructions, guidelines, or context
+  that you want the Gemini model to be aware of during your interactions. The
+  system is designed to manage this instructional context hierarchically.
+
+### Example Context File Content (e.g., `GEMINI.md`)
+
+Here's a conceptual example of what a context file at the root of a TypeScript
+project might contain:
+
+```markdown
+# Project: My Awesome TypeScript Library
+
+## General Instructions:
+
+- When generating new TypeScript code, please follow the existing coding style.
+- Ensure all new functions and classes have JSDoc comments.
+- Prefer functional programming paradigms where appropriate.
+- All code should be compatible with TypeScript 5.0 and Node.js 20+.
+
+## Coding Style:
+
+- Use 2 spaces for indentation.
+- Interface names should be prefixed with `I` (e.g., `IUserService`).
+- Private class members should be prefixed with an underscore (`_`).
+- Always use strict equality (`===` and `!==`).
+
+## Specific Component: `src/api/client.ts`
+
+- This file handles all outbound API requests.
+- When adding new API call functions, ensure they include robust error handling
+  and logging.
+- Use the existing `fetchWithRetry` utility for all GET requests.
+
+## Regarding Dependencies:
+
+- Avoid introducing new external dependencies unless absolutely necessary.
+- If a new dependency is required, please state the reason.
+```
+
+This example demonstrates how you can provide general project context, specific
+coding conventions, and even notes about particular files or components. The
+more relevant and precise your context files are, the better the AI can assist
+you. Project-specific context files are highly encouraged to establish
+conventions and context.
+
+- **Hierarchical Loading and Precedence:** The CLI implements a sophisticated
+  hierarchical memory system by loading context files (e.g., `GEMINI.md`) from
+  several locations. Content from files lower in this list (more specific)
+  typically overrides or supplements content from files higher up (more
+  general). The exact concatenation order and final context can be inspected
+  using the `/memory show` command. The typical loading order is:
+  1.  **Global Context File:**
+      - Location: `~/.gemini/<contextFileName>` (e.g., `~/.gemini/GEMINI.md` in
+        your user home directory).
+      - Scope: Provides default instructions for all your projects.
+  2.  **Project Root & Ancestors Context Files:**
+      - Location: The CLI searches for the configured context file in the
+        current working directory and then in each parent directory up to either
+        the project root (identified by a `.git` folder) or your home directory.
+      - Scope: Provides context relevant to the entire project or a significant
+        portion of it.
+  3.  **Sub-directory Context Files (Contextual/Local):**
+      - Location: The CLI also scans for the configured context file in
+        subdirectories _below_ the current working directory (respecting common
+        ignore patterns like `node_modules`, `.git`, etc.). The breadth of this
+        search is limited to 200 directories by default, but can be configured
+        with a `memoryDiscoveryMaxDirs` field in your `settings.json` file.
+      - Scope: Allows for highly specific instructions relevant to a particular
+        component, module, or subsection of your project.
+- **Concatenation & UI Indication:** The contents of all found context files are
+  concatenated (with separators indicating their origin and path) and provided
+  as part of the system prompt to the Gemini model. The CLI footer displays the
+  count of loaded context files, giving you a quick visual cue about the active
+  instructional context.
+- **Importing Content:** You can modularize your context files by importing
+  other Markdown files using the `@path/to/file.md` syntax. For more details,
+  see the [Memory Import Processor documentation](../core/memport.md).
+- **Commands for Memory Management:**
+  - Use `/memory refresh` to force a re-scan and reload of all context files
+    from all configured locations. This updates the AI's instructional context.
+  - Use `/memory show` to display the combined instructional context currently
+    loaded, allowing you to verify the hierarchy and content being used by the
+    AI.
+  - See the [Commands documentation](./commands.md#memory) for full details on
+    the `/memory` command and its sub-commands (`show` and `refresh`).
+
+By understanding and utilizing these configuration layers and the hierarchical
+nature of context files, you can effectively manage the AI's memory and tailor
+the Gemini CLI's responses to your specific needs and projects.
+
+## Sandboxing
+
+The Gemini CLI can execute potentially unsafe operations (like shell commands
+and file modifications) within a sandboxed environment to protect your system.
+
+Sandboxing is disabled by default, but you can enable it in a few ways:
+
+- Using `--sandbox` or `-s` flag.
+- Setting `GEMINI_SANDBOX` environment variable.
+- Sandbox is enabled in `--yolo` mode by default.
+
+By default, it uses a pre-built `gemini-cli-sandbox` Docker image.
+
+For project-specific sandboxing needs, you can create a custom Dockerfile at
+`.gemini/sandbox.Dockerfile` in your project's root directory. This Dockerfile
+can be based on the base sandbox image:
+
+```dockerfile
+FROM gemini-cli-sandbox
+
+# Add your custom dependencies or configurations here
+# For example:
+# RUN apt-get update && apt-get install -y some-package
+# COPY ./my-config /app/my-config
+```
+
+When `.gemini/sandbox.Dockerfile` exists, you can use `BUILD_SANDBOX`
+environment variable when running Gemini CLI to automatically build the custom
+sandbox image:
+
+```bash
+BUILD_SANDBOX=1 gemini -s
+```
+
+## Usage Statistics
+
+To help us improve the Gemini CLI, we collect anonymized usage statistics. This
+data helps us understand how the CLI is used, identify common issues, and
+prioritize new features.
+
+**What we collect:**
+
+- **Tool Calls:** We log the names of the tools that are called, whether they
+  succeed or fail, and how long they take to execute. We do not collect the
+  arguments passed to the tools or any data returned by them.
+- **API Requests:** We log the Gemini model used for each request, the duration
+  of the request, and whether it was successful. We do not collect the content
+  of the prompts or responses.
+- **Session Information:** We collect information about the configuration of the
+  CLI, such as the enabled tools and the approval mode.
+
+**What we DON'T collect:**
+
+- **Personally Identifiable Information (PII):** We do not collect any personal
+  information, such as your name, email address, or API keys.
+- **Prompt and Response Content:** We do not log the content of your prompts or
+  the responses from the Gemini model.
+- **File Content:** We do not log the content of any files that are read or
+  written by the CLI.
+
+**How to opt out:**
+
+You can opt out of usage statistics collection at any time by setting the
+`usageStatisticsEnabled` property to `false` in your `settings.json` file:
+
+```json
+{
+  "usageStatisticsEnabled": false
+}
+```

docs/cli/enterprise.md

@@ -202,6 +202,26 @@ allowlisting with `coreTools`, as it relies on blocking known-bad commands, and
 clever users may find ways to bypass simple string-based blocks. **Allowlisting
 is the recommended approach.**
 
+### Disabling YOLO Mode
+
+To ensure that users cannot bypass the confirmation prompt for tool execution,
+you can disable YOLO mode at the policy level. This adds a critical layer of
+safety, as it prevents the model from executing tools without explicit user
+approval.
+
+**Example:** Force all tool executions to require user confirmation.
+
+```json
+{
+  "security": {
+    "disableYoloMode": true
+  }
+}
+```
+
+This setting is highly recommended in an enterprise environment to prevent
+unintended tool execution.
+
 ## Managing Custom Tools (MCP Servers)
 
 If your organization uses custom tools via
@@ -343,9 +363,8 @@ containerized environment.
 }
 ```
 
-You can also specify a custom, hardened Docker image for the sandbox using the
-`--sandbox-image` command-line argument or by building a custom
-`sandbox.Dockerfile` as described in the
+You can also specify a custom, hardened Docker image for the sandbox by building
+a custom `sandbox.Dockerfile` as described in the
 [Sandboxing documentation](./sandbox.md).
 
 ## Controlling Network Access via Proxy

docs/cli/gemini-ignore.md

@@ -13,8 +13,8 @@ Git).
 
 When you add a path to your `.geminiignore` file, tools that respect this file
 will exclude matching files and directories from their operations. For example,
-when you use the [`read_many_files`](../tools/multi-file.md) command, any paths
-in your `.geminiignore` file will be automatically excluded.
+when you use the `@` command to share files, any paths in your `.geminiignore`
+file will be automatically excluded.
 
 For the most part, `.geminiignore` follows the conventions of `.gitignore`
 files:

docs/cli/headless.md

@@ -15,6 +15,13 @@ scripting, automation, CI/CD pipelines, and building AI-powered tools.
     - [JSON Output](#json-output)
       - [Response Schema](#response-schema)
       - [Example Usage](#example-usage)
+    - [Streaming JSON Output](#streaming-json-output)
+      - [When to Use Streaming JSON](#when-to-use-streaming-json)
+      - [Event Types](#event-types)
+      - [Basic Usage](#basic-usage)
+      - [Example Output](#example-output)
+      - [Processing Stream Events](#processing-stream-events)
+      - [Real-World Examples](#real-world-examples)
     - [File Redirection](#file-redirection)
   - [Configuration Options](#configuration-options)
   - [Examples](#examples)
@@ -211,6 +218,62 @@ Response:
 }
 ```
 
+### Streaming JSON Output
+
+Returns real-time events as newline-delimited JSON (JSONL). Each significant
+action (initialization, messages, tool calls, results) emits immediately as it
+occurs. This format is ideal for monitoring long-running operations, building
+UIs with live progress, and creating automation pipelines that react to events.
+
+#### When to Use Streaming JSON
+
+Use `--output-format stream-json` when you need:
+
+- **Real-time progress monitoring** - See tool calls and responses as they
+  happen
+- **Event-driven automation** - React to specific events (e.g., tool failures)
+- **Live UI updates** - Build interfaces showing AI agent activity in real-time
+- **Detailed execution logs** - Capture complete interaction history with
+  timestamps
+- **Pipeline integration** - Stream events to logging/monitoring systems
+
+#### Event Types
+
+The streaming format emits 6 event types:
+
+1. **`init`** - Session starts (includes session_id, model)
+2. **`message`** - User prompts and assistant responses
+3. **`tool_use`** - Tool call requests with parameters
+4. **`tool_result`** - Tool execution results (success/error)
+5. **`error`** - Non-fatal errors and warnings
+6. **`result`** - Final session outcome with aggregated stats
+
+#### Basic Usage
+
+```bash
+# Stream events to console
+gemini --output-format stream-json --prompt "What is 2+2?"
+
+# Save event stream to file
+gemini --output-format stream-json --prompt "Analyze this code" > events.jsonl
+
+# Parse with jq
+gemini --output-format stream-json --prompt "List files" | jq -r '.type'
+```
+
+#### Example Output
+
+Each line is a complete JSON event:
+
+```jsonl
+{"type":"init","timestamp":"2025-10-10T12:00:00.000Z","session_id":"abc123","model":"gemini-2.0-flash-exp"}
+{"type":"message","role":"user","content":"List files in current directory","timestamp":"2025-10-10T12:00:01.000Z"}
+{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls -la"},"timestamp":"2025-10-10T12:00:02.000Z"}
+{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt","timestamp":"2025-10-10T12:00:03.000Z"}
+{"type":"message","role":"assistant","content":"Here are the files...","delta":true,"timestamp":"2025-10-10T12:00:04.000Z"}
+{"type":"result","status":"success","stats":{"total_tokens":250,"input_tokens":50,"output_tokens":200,"duration_ms":3000,"tool_calls":1},"timestamp":"2025-10-10T12:00:05.000Z"}
+```
+
 ### File Redirection
 
 Save output to files or pipe to other commands:
@@ -239,7 +302,6 @@ Key command-line options for headless usage:
 | `--output-format`       | Specify output format (text, json) | `gemini -p "query" --output-format json`           |
 | `--model`, `-m`         | Specify the Gemini model           | `gemini -p "query" -m gemini-2.5-flash`            |
 | `--debug`, `-d`         | Enable debug mode                  | `gemini -p "query" --debug`                        |
-| `--all-files`, `-a`     | Include all files in context       | `gemini -p "query" --all-files`                    |
 | `--include-directories` | Include additional directories     | `gemini -p "query" --include-directories src,docs` |
 | `--yolo`, `-y`          | Auto-approve all actions           | `gemini -p "query" --yolo`                         |
 | `--approval-mode`       | Set approval mode                  | `gemini -p "query" --approval-mode auto_edit`      |

docs/cli/index.md

@@ -7,11 +7,14 @@ overview of Gemini CLI, see the [main documentation page](../index.md).
 ## Basic features
 
 - **[Commands](./commands.md):** A reference for all built-in slash commands
-  (e.g., `/help`, `/chat`, `/tools`).
 - **[Custom Commands](./custom-commands.md):** Create your own commands and
   shortcuts for frequently used prompts.
 - **[Headless Mode](./headless.md):** Use Gemini CLI programmatically for
   scripting and automation.
+- **[Model Selection](./model.md):** Configure the Gemini AI model used by the
+  CLI.
+- **[Settings](./settings.md):** Configure various aspects of the CLI's behavior
+  and appearance.
 - **[Themes](./themes.md):** Customizing the CLI's appearance with different
   themes.
 - **[Keyboard Shortcuts](./keyboard-shortcuts.md):** A reference for all

docs/cli/keyboard-shortcuts.md

@@ -1,69 +1,143 @@
 # Gemini CLI Keyboard Shortcuts
 
-This document lists the available keyboard shortcuts in the Gemini CLI.
+Gemini CLI ships with a set of default keyboard shortcuts for editing input,
+navigating history, and controlling the UI. Use this reference to learn the
+available combinations.
 
-## General
+<!-- KEYBINDINGS-AUTOGEN:START -->
 
-| Shortcut | Description                                                                                                           |
-| -------- | --------------------------------------------------------------------------------------------------------------------- |
-| `Esc`    | Close dialogs and suggestions.                                                                                        |
-| `Ctrl+C` | Cancel the ongoing request and clear the input. Press twice to exit the application.                                  |
-| `Ctrl+D` | Exit the application if the input is empty. Press twice to confirm.                                                   |
-| `Ctrl+L` | Clear the screen.                                                                                                     |
-| `Ctrl+O` | Toggle the display of the debug console.                                                                              |
-| `Ctrl+S` | Allows long responses to print fully, disabling truncation. Use your terminal's scrollback to view the entire output. |
-| `Ctrl+T` | Toggle the display of tool descriptions.                                                                              |
-| `Ctrl+Y` | Toggle auto-approval (YOLO mode) for all tool calls.                                                                  |
+#### Basic Controls
 
-## Input Prompt
+| Action                                       | Keys    |
+| -------------------------------------------- | ------- |
+| Confirm the current selection or choice.     | `Enter` |
+| Dismiss dialogs or cancel the current focus. | `Esc`   |
 
-| Shortcut                                           | Description                                                                                                                         |
-| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `!`                                                | Toggle shell mode when the input is empty.                                                                                          |
-| `\` (at end of line) + `Enter`                     | Insert a newline.                                                                                                                   |
-| `Down Arrow`                                       | Navigate down through the input history.                                                                                            |
-| `Enter`                                            | Submit the current prompt.                                                                                                          |
-| `Meta+Delete` / `Ctrl+Delete`                      | Delete the word to the right of the cursor.                                                                                         |
-| `Tab`                                              | Autocomplete the current suggestion if one exists.                                                                                  |
-| `Up Arrow`                                         | Navigate up through the input history.                                                                                              |
-| `Ctrl+A` / `Home`                                  | Move the cursor to the beginning of the line.                                                                                       |
-| `Ctrl+B` / `Left Arrow`                            | Move the cursor one character to the left.                                                                                          |
-| `Ctrl+C`                                           | Clear the input prompt                                                                                                              |
-| `Esc` (double press)                               | Clear the input prompt.                                                                                                             |
-| `Ctrl+D` / `Delete`                                | Delete the character to the right of the cursor.                                                                                    |
-| `Ctrl+E` / `End`                                   | Move the cursor to the end of the line.                                                                                             |
-| `Ctrl+F` / `Right Arrow`                           | Move the cursor one character to the right.                                                                                         |
-| `Ctrl+H` / `Backspace`                             | Delete the character to the left of the cursor.                                                                                     |
-| `Ctrl+K`                                           | Delete from the cursor to the end of the line.                                                                                      |
-| `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B`   | Move the cursor one word to the left.                                                                                               |
-| `Ctrl+N`                                           | Navigate down through the input history.                                                                                            |
-| `Ctrl+P`                                           | Navigate up through the input history.                                                                                              |
-| `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | Move the cursor one word to the right.                                                                                              |
-| `Ctrl+U`                                           | Delete from the cursor to the beginning of the line.                                                                                |
-| `Ctrl+V`                                           | Paste clipboard content. If the clipboard contains an image, it will be saved and a reference to it will be inserted in the prompt. |
-| `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace`     | Delete the word to the left of the cursor.                                                                                          |
-| `Ctrl+X` / `Meta+Enter`                            | Open the current input in an external editor.                                                                                       |
+#### Cursor Movement
 
-## Suggestions
+| Action                                    | Keys                   |
+| ----------------------------------------- | ---------------------- |
+| Move the cursor to the start of the line. | `Ctrl + A`<br />`Home` |
+| Move the cursor to the end of the line.   | `Ctrl + E`<br />`End`  |
 
-| Shortcut        | Description                            |
-| --------------- | -------------------------------------- |
-| `Down Arrow`    | Navigate down through the suggestions. |
-| `Tab` / `Enter` | Accept the selected suggestion.        |
-| `Up Arrow`      | Navigate up through the suggestions.   |
+#### Editing
 
-## Radio Button Select
+| Action                                           | Keys                                      |
+| ------------------------------------------------ | ----------------------------------------- |
+| Delete from the cursor to the end of the line.   | `Ctrl + K`                                |
+| Delete from the cursor to the start of the line. | `Ctrl + U`                                |
+| Clear all text in the input field.               | `Ctrl + C`                                |
+| Delete the previous word.                        | `Ctrl + Backspace`<br />`Cmd + Backspace` |
 
-| Shortcut           | Description                                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `Down Arrow` / `j` | Move selection down.                                                                                          |
-| `Enter`            | Confirm selection.                                                                                            |
-| `Up Arrow` / `k`   | Move selection up.                                                                                            |
-| `1-9`              | Select an item by its number.                                                                                 |
-| (multi-digit)      | For items with numbers greater than 9, press the digits in quick succession to select the corresponding item. |
+#### Screen Control
 
-## IDE Integration
+| Action                                       | Keys       |
+| -------------------------------------------- | ---------- |
+| Clear the terminal screen and redraw the UI. | `Ctrl + L` |
 
-| Shortcut | Description                       |
-| -------- | --------------------------------- |
-| `Ctrl+G` | See context CLI received from IDE |
+#### Scrolling
+
+| Action                   | Keys                 |
+| ------------------------ | -------------------- |
+| Scroll content up.       | `Shift + Up Arrow`   |
+| Scroll content down.     | `Shift + Down Arrow` |
+| Scroll to the top.       | `Home`               |
+| Scroll to the bottom.    | `End`                |
+| Scroll up by one page.   | `Page Up`            |
+| Scroll down by one page. | `Page Down`          |
+
+#### History & Search
+
+| Action                                       | Keys                  |
+| -------------------------------------------- | --------------------- |
+| Show the previous entry in history.          | `Ctrl + P (no Shift)` |
+| Show the next entry in history.              | `Ctrl + N (no Shift)` |
+| Start reverse search through history.        | `Ctrl + R`            |
+| Insert the selected reverse-search match.    | `Enter (no Ctrl)`     |
+| Accept a suggestion while reverse searching. | `Tab`                 |
+
+#### Navigation
+
+| Action                           | Keys                                        |
+| -------------------------------- | ------------------------------------------- |
+| Move selection up in lists.      | `Up Arrow (no Shift)`                       |
+| Move selection down in lists.    | `Down Arrow (no Shift)`                     |
+| Move up within dialog options.   | `Up Arrow (no Shift)`<br />`K (no Shift)`   |
+| Move down within dialog options. | `Down Arrow (no Shift)`<br />`J (no Shift)` |
+
+#### Suggestions & Completions
+
+| Action                                  | Keys                                               |
+| --------------------------------------- | -------------------------------------------------- |
+| Accept the inline suggestion.           | `Tab`<br />`Enter (no Ctrl)`                       |
+| Move to the previous completion option. | `Up Arrow (no Shift)`<br />`Ctrl + P (no Shift)`   |
+| Move to the next completion option.     | `Down Arrow (no Shift)`<br />`Ctrl + N (no Shift)` |
+| Expand an inline suggestion.            | `Right Arrow`                                      |
+| Collapse an inline suggestion.          | `Left Arrow`                                       |
+
+#### Text Input
+
+| Action                               | Keys                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Submit the current prompt.           | `Enter (no Ctrl, no Shift, no Cmd, not Paste)`                                              |
+| Insert a newline without submitting. | `Ctrl + Enter`<br />`Cmd + Enter`<br />`Paste + Enter`<br />`Shift + Enter`<br />`Ctrl + J` |
+
+#### External Tools
+
+| Action                                         | Keys       |
+| ---------------------------------------------- | ---------- |
+| Open the current prompt in an external editor. | `Ctrl + X` |
+| Paste from the clipboard.                      | `Ctrl + V` |
+
+#### App Controls
+
+| Action                                                            | Keys       |
+| ----------------------------------------------------------------- | ---------- |
+| Toggle detailed error information.                                | `F12`      |
+| Toggle the full TODO list.                                        | `Ctrl + T` |
+| Toggle IDE context details.                                       | `Ctrl + G` |
+| Toggle Markdown rendering.                                        | `Cmd + M`  |
+| Toggle copy mode when the terminal is using the alternate buffer. | `Ctrl + S` |
+| Expand a height-constrained response to show additional lines.    | `Ctrl + S` |
+| Toggle focus between the shell and Gemini input.                  | `Ctrl + F` |
+
+#### Session Control
+
+| Action                                       | Keys       |
+| -------------------------------------------- | ---------- |
+| Cancel the current request or quit the CLI.  | `Ctrl + C` |
+| Exit the CLI when the input buffer is empty. | `Ctrl + D` |
+
+<!-- KEYBINDINGS-AUTOGEN:END -->
+
+## Additional Context-Specific Shortcuts
+
+- `Ctrl+Y`: Toggle YOLO (auto-approval) mode for tool calls.
+- `Shift+Tab`: Toggle Auto Edit (auto-accept edits) mode.
+- `Option+M` (macOS): Entering `µ` with Option+M also toggles Markdown
+  rendering, matching `Cmd+M`.
+- `!` on an empty prompt: Enter or exit shell mode.
+- `\` (at end of a line) + `Enter`: Insert a newline without leaving single-line
+  mode.
+- `Ctrl+Delete` / `Meta+Delete`: Delete the word to the right of the cursor.
+- `Ctrl+B` or `Left Arrow`: Move the cursor one character to the left while
+  editing text.
+- `Ctrl+F` or `Right Arrow`: Move the cursor one character to the right; with an
+  embedded shell attached, `Ctrl+F` still toggles focus.
+- `Ctrl+D` or `Delete`: Remove the character immediately to the right of the
+  cursor.
+- `Ctrl+H` or `Backspace`: Remove the character immediately to the left of the
+  cursor.
+- `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B`: Move one word to the left.
+- `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F`: Move one word to the
+  right.
+- `Ctrl+W`: Delete the word to the left of the cursor (in addition to
+  `Ctrl+Backspace` / `Cmd+Backspace`).
+- `Ctrl+Z` / `Ctrl+Shift+Z`: Undo or redo the most recent text edit.
+- `Meta+Enter`: Open the current input in an external editor (alias for
+  `Ctrl+X`).
+- `Esc` pressed twice quickly: Clear the current input buffer.
+- `Up Arrow` / `Down Arrow`: When the cursor is at the top or bottom of a
+  single-line input, navigate backward or forward through prompt history.
+- `Number keys (1-9, multi-digit)` inside selection dialogs: Jump directly to
+  the numbered radio option and confirm when the full number is entered.

docs/cli/model-routing.md

@@ -0,0 +1,56 @@
+## Model Routing
+
+Gemini CLI includes a model routing feature that automatically switches to a
+fallback model in case of a model failure. This feature is enabled by default
+and provides resilience when the primary model is unavailable.
+
+## How it Works
+
+Model routing is not based on prompt complexity, but is a fallback mechanism.
+Here's how it works:
+
+1.  **Model Failure:** If the currently selected model fails to respond (for
+    example, due to a server error or other issue), the CLI will initiate the
+    fallback process.
+
+2.  **User Consent:** The CLI will prompt you to ask if you want to switch to
+    the fallback model. This is handled by the `fallbackModelHandler`.
+
+3.  **Fallback Activation:** If you consent, the CLI will activate the fallback
+    mode by calling `config.setFallbackMode(true)`.
+
+4.  **Model Switch:** On the next request, the CLI will use the
+    `DEFAULT_GEMINI_FLASH_MODEL` as the fallback model. This is handled by the
+    `resolveModel` function in
+    `packages/cli/src/zed-integration/zedIntegration.ts` which checks if
+    `isInFallbackMode()` is true.
+
+## Configuration
+
+Model routing is controlled by the `useModelRouter` setting in your
+`settings.json` file.
+
+- **`"experimental.useModelRouter": true` (Default):** Enables the model
+  routing/fallback feature.
+
+- **`"experimental.useModelRouter": false`:** Disables the model
+  routing/fallback feature. If a model fails, the CLI will not attempt to switch
+  to a fallback model.
+
+### Model Selection Precedence
+
+The model used by Gemini CLI is determined by the following order of precedence:
+
+1.  **`--model` command-line flag:** A model specified with the `--model` flag
+    when launching the CLI will always be used.
+2.  **`GEMINI_MODEL` environment variable:** If the `--model` flag is not used,
+    the CLI will use the model specified in the `GEMINI_MODEL` environment
+    variable.
+3.  **`model.name` in `settings.json`:** If neither of the above are set, the
+    model specified in the `model.name` property of your `settings.json` file
+    will be used.
+4.  **Default Model:** If none of the above are set, the default model will be
+    used. The default model is determined by the `useModelRouter` setting:
+    - If `useModelRouter` is `true`, the default model is `"auto"`.
+    - If `useModelRouter` is `false`, the default model is the standard Gemini
+      model.

docs/cli/model.md

@@ -0,0 +1,58 @@
+# 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.
+
+## How to use the `/model` command
+
+Use the following command in Gemini CLI:
+
+```
+/model
+```
+
+Running this command will open a dialog with your model 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                                                                      |
+
+### Gemini 3 Pro and Preview Features
+
+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).
+
+To enable Gemini 3 Pro (if available), enable
+[**Preview features** by using the `settings` command](../cli/settings). 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.
+
+You can also use the `--model` flag to specify a particular Gemini model on
+startup. For more details, refer to the
+[configuration documentation](./configuration.md).
+
+Changes to these settings will be applied to all subsequent interactions with
+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).
+
+- **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.
+
+- **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:
+  Converting a JSON object to a YAML string.

docs/cli/settings.md

@@ -0,0 +1,113 @@
+# Gemini CLI Settings (`/settings` Command)
+
+Control your Gemini CLI experience with the `/settings` command. The `/settings`
+command opens a dialog to view and edit all your Gemini CLI settings, including
+your UI experience, keybindings, and accessibility features.
+
+Your Gemini CLI settings are stored in a `settings.json` file. In addition to
+using the `/settings` command, you can also edit them in one of the following
+locations:
+
+- **User settings**: `~/.gemini/settings.json`
+- **Workspace settings**: `your-project/.gemini/settings.json`
+
+Note: Workspace settings override user settings.
+
+## Settings reference
+
+Here is a list of all the available settings, grouped by category and ordered as
+they appear in the UI.
+
+### General
+
+| UI Label                        | Setting                            | Description                                                                  | Default     |
+| ------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | ----------- |
+| Preview Features (e.g., models) | `general.previewFeatures`          | Enable preview features (e.g., preview models).                              | `false`     |
+| Vim Mode                        | `general.vimMode`                  | Enable Vim keybindings.                                                      | `false`     |
+| Disable Auto Update             | `general.disableAutoUpdate`        | Disable automatic updates.                                                   | `false`     |
+| Enable Prompt Completion        | `general.enablePromptCompletion`   | Enable AI-powered prompt completion suggestions while typing.                | `false`     |
+| Debug Keystroke Logging         | `general.debugKeystrokeLogging`    | Enable debug logging of keystrokes to the console.                           | `false`     |
+| Session Retention               | `general.sessionRetention`         | Settings for automatic session cleanup. This feature is disabled by default. | `undefined` |
+| Enable Session Cleanup          | `general.sessionRetention.enabled` | Enable automatic session cleanup.                                            | `false`     |
+
+### Output
+
+| UI Label      | Setting         | Description                                            | Default |
+| ------------- | --------------- | ------------------------------------------------------ | ------- |
+| Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `text`  |
+
+### UI
+
+| UI Label                       | Setting                                  | Description                                                          | Default |
+| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------------- | ------- |
+| Hide Window Title              | `ui.hideWindowTitle`                     | Hide the window title bar.                                           | `false` |
+| Show Status in Title           | `ui.showStatusInTitle`                   | Show Gemini CLI status and thoughts in the terminal window title.    | `false` |
+| Hide Tips                      | `ui.hideTips`                            | Hide helpful tips in the UI.                                         | `false` |
+| Hide Banner                    | `ui.hideBanner`                          | Hide the application banner.                                         | `false` |
+| Hide Context Summary           | `ui.hideContextSummary`                  | Hide the context summary (GEMINI.md, MCP servers) above the input.   | `false` |
+| Hide CWD                       | `ui.footer.hideCWD`                      | Hide the current working directory path in the footer.               | `false` |
+| Hide Sandbox Status            | `ui.footer.hideSandboxStatus`            | Hide the sandbox status indicator in the footer.                     | `false` |
+| Hide Model Info                | `ui.footer.hideModelInfo`                | Hide the model name and context usage in the footer.                 | `false` |
+| Hide Context Window Percentage | `ui.footer.hideContextPercentage`        | Hides the context window remaining percentage.                       | `true`  |
+| Hide Footer                    | `ui.hideFooter`                          | Hide the footer from the UI.                                         | `false` |
+| Show Memory Usage              | `ui.showMemoryUsage`                     | Display memory usage information in the UI.                          | `false` |
+| Show Line Numbers              | `ui.showLineNumbers`                     | Show line numbers in the chat.                                       | `false` |
+| Show Citations                 | `ui.showCitations`                       | Show citations for generated text in the chat.                       | `false` |
+| Use Full Width                 | `ui.useFullWidth`                        | Use the entire width of the terminal for output.                     | `true`  |
+| Use Alternate Screen Buffer    | `ui.useAlternateBuffer`                  | Use an alternate screen buffer for the UI, preserving shell history. | `true`  |
+| Disable Loading Phrases        | `ui.accessibility.disableLoadingPhrases` | Disable loading phrases for accessibility.                           | `false` |
+| Screen Reader Mode             | `ui.accessibility.screenReader`          | Render output in plain-text to be more screen reader accessible.     | `false` |
+
+### IDE
+
+| UI Label | Setting       | Description                  | Default |
+| -------- | ------------- | ---------------------------- | ------- |
+| IDE Mode | `ide.enabled` | Enable IDE integration mode. | `false` |
+
+### Model
+
+| UI Label                | Setting                      | Description                                                                            | Default |
+| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ------- |
+| Max Session Turns       | `model.maxSessionTurns`      | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.      | `-1`    |
+| Compression Threshold   | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.2`   |
+| Skip Next Speaker Check | `model.skipNextSpeakerCheck` | Skip the next speaker check.                                                           | `true`  |
+
+### Context
+
+| UI Label                             | Setting                                           | Description                                                                                                                                     | Default |
+| ------------------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Memory Discovery Max Dirs            | `context.discoveryMaxDirs`                        | Maximum number of directories to search for memory.                                                                                             | `200`   |
+| Load Memory From Include Directories | `context.loadMemoryFromIncludeDirectories`        | Controls how /memory refresh loads GEMINI.md files. When true, include directories are scanned; when false, only the current directory is used. | `false` |
+| Respect .gitignore                   | `context.fileFiltering.respectGitIgnore`          | Respect .gitignore files when searching.                                                                                                        | `true`  |
+| Respect .geminiignore                | `context.fileFiltering.respectGeminiIgnore`       | Respect .geminiignore files when searching.                                                                                                     | `true`  |
+| Enable Recursive File Search         | `context.fileFiltering.enableRecursiveFileSearch` | Enable recursive file search functionality when completing @ references in the prompt.                                                          | `true`  |
+| Disable Fuzzy Search                 | `context.fileFiltering.disableFuzzySearch`        | Disable fuzzy search when searching for files.                                                                                                  | `false` |
+
+### Tools
+
+| UI Label                         | Setting                              | Description                                                                                                     | Default |
+| -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------- |
+| Enable Interactive Shell         | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies.                      | `true`  |
+| Show Color                       | `tools.shell.showColor`              | Show color in shell output.                                                                                     | `false` |
+| Auto Accept                      | `tools.autoAccept`                   | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations).              | `false` |
+| Use Ripgrep                      | `tools.useRipgrep`                   | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true`  |
+| 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` |
+
+### Security
+
+| UI Label                   | Setting                        | Description                                        | Default |
+| -------------------------- | ------------------------------ | -------------------------------------------------- | ------- |
+| Disable YOLO Mode          | `security.disableYoloMode`     | Disable YOLO mode, even if enabled by a flag.      | `false` |
+| Blocks extensions from Git | `security.blockGitExtensions`  | Blocks installing and loading extensions from Git. | `false` |
+| Folder Trust               | `security.folderTrust.enabled` | Setting to track whether Folder trust is enabled.  | `false` |
+
+### Experimental
+
+| UI Label                            | Setting                                                 | Description                                                                   | Default |
+| ----------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------- | ------- |
+| Use Model Router                    | `experimental.useModelRouter`                           | Enable model routing to route requests to the best model based on complexity. | `true`  |
+| Enable Codebase Investigator        | `experimental.codebaseInvestigatorSettings.enabled`     | Enable the Codebase Investigator agent.                                       | `true`  |
+| Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent.                  | `10`    |

docs/cli/telemetry.md

@@ -15,8 +15,29 @@ Learn how to enable and setup OpenTelemetry for Gemini CLI.
     - [Collector-Based Export (Advanced)](#collector-based-export-advanced-1)
   - [Logs and Metrics](#logs-and-metrics)
     - [Logs](#logs)
+      - [Sessions](#sessions)
+      - [Tools](#tools)
+      - [Files](#files)
+      - [API](#api)
+      - [Model Routing](#model-routing)
+      - [Chat and Streaming](#chat-and-streaming)
+      - [Resilience](#resilience)
+      - [Extensions](#extensions)
+      - [Agent Runs](#agent-runs)
+      - [IDE](#ide)
+      - [UI](#ui)
     - [Metrics](#metrics)
       - [Custom](#custom)
+        - [Sessions](#sessions-1)
+        - [Tools](#tools-1)
+        - [API](#api-1)
+        - [Token Usage](#token-usage)
+        - [Files](#files-1)
+        - [Chat and Streaming](#chat-and-streaming-1)
+        - [Model Routing](#model-routing-1)
+        - [Agent Runs](#agent-runs-1)
+        - [UI](#ui-1)
+        - [Performance](#performance)
       - [GenAI Semantic Convention](#genai-semantic-convention)
 
 ## Key Benefits
@@ -51,17 +72,17 @@ observability framework — Gemini CLI's observability system provides:
 ## Configuration
 
 All telemetry behavior is controlled through your `.gemini/settings.json` file.
-These settings can be overridden by environment variables or CLI flags.
+Environment variables can be used to override the settings in the file.
 
-| Setting        | Environment Variable             | CLI Flag                                                 | Description                                       | Values            | Default                 |
-| -------------- | -------------------------------- | -------------------------------------------------------- | ------------------------------------------------- | ----------------- | ----------------------- |
-| `enabled`      | `GEMINI_TELEMETRY_ENABLED`       | `--telemetry` / `--no-telemetry`                         | Enable or disable telemetry                       | `true`/`false`    | `false`                 |
-| `target`       | `GEMINI_TELEMETRY_TARGET`        | `--telemetry-target <local\|gcp>`                        | Where to send telemetry data                      | `"gcp"`/`"local"` | `"local"`               |
-| `otlpEndpoint` | `GEMINI_TELEMETRY_OTLP_ENDPOINT` | `--telemetry-otlp-endpoint <URL>`                        | OTLP collector endpoint                           | URL string        | `http://localhost:4317` |
-| `otlpProtocol` | `GEMINI_TELEMETRY_OTLP_PROTOCOL` | `--telemetry-otlp-protocol <grpc\|http>`                 | OTLP transport protocol                           | `"grpc"`/`"http"` | `"grpc"`                |
-| `outfile`      | `GEMINI_TELEMETRY_OUTFILE`       | `--telemetry-outfile <path>`                             | Save telemetry to file (overrides `otlpEndpoint`) | file path         | -                       |
-| `logPrompts`   | `GEMINI_TELEMETRY_LOG_PROMPTS`   | `--telemetry-log-prompts` / `--no-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`                 |
 
 **Note on boolean environment variables:** For the boolean settings (`enabled`,
 `logPrompts`, `useCollector`), setting the corresponding environment variable to
@@ -204,16 +225,20 @@ For local development and debugging, you can capture telemetry data locally:
 The following section describes the structure of logs and metrics generated for
 Gemini CLI.
 
-The `session.id`, `installation.id`, and `user.email` are included as common
-attributes on all logs and metrics.
+The `session.id`, `installation.id`, and `user.email` (available only when
+authenticated with a Google account) are included as common attributes on all
+logs and metrics.
 
 ### Logs
 
 Logs are timestamped records of specific events. The following events are logged
-for Gemini CLI:
+for Gemini CLI, grouped by category.
 
-- `gemini_cli.config`: This event occurs once at startup with the CLI's
-  configuration.
+#### Sessions
+
+Captures startup configuration and user prompt submissions.
+
+- `gemini_cli.config`: Emitted once at startup with the CLI configuration.
   - **Attributes**:
     - `model` (string)
     - `embedding_model` (string)
@@ -222,81 +247,47 @@ for Gemini CLI:
     - `approval_mode` (string)
     - `api_key_enabled` (boolean)
     - `vertex_ai_enabled` (boolean)
-    - `code_assist_enabled` (boolean)
-    - `log_prompts_enabled` (boolean)
+    - `log_user_prompts_enabled` (boolean)
     - `file_filtering_respect_git_ignore` (boolean)
     - `debug_mode` (boolean)
     - `mcp_servers` (string)
-    - `output_format` (string: "text" or "json")
+    - `mcp_servers_count` (int)
+    - `extensions` (string)
+    - `extension_ids` (string)
+    - `extension_count` (int)
+    - `mcp_tools` (string, if applicable)
+    - `mcp_tools_count` (int, if applicable)
+    - `output_format` ("text", "json", or "stream-json")
 
-- `gemini_cli.user_prompt`: This event occurs when a user submits a prompt.
+- `gemini_cli.user_prompt`: Emitted when a user submits a prompt.
   - **Attributes**:
     - `prompt_length` (int)
     - `prompt_id` (string)
-    - `prompt` (string, this attribute is excluded if `log_prompts_enabled` is
-      configured to be `false`)
+    - `prompt` (string; excluded if `telemetry.logPrompts` is `false`)
     - `auth_type` (string)
 
-- `gemini_cli.tool_call`: This event occurs for each function call.
+#### Tools
+
+Captures tool executions, output truncation, and Smart Edit behavior.
+
+- `gemini_cli.tool_call`: Emitted for each tool (function) call.
   - **Attributes**:
     - `function_name`
     - `function_args`
     - `duration_ms`
     - `success` (boolean)
-    - `decision` (string: "accept", "reject", "auto_accept", or "modify", if
-      applicable)
+    - `decision` ("accept", "reject", "auto_accept", or "modify", if applicable)
     - `error` (if applicable)
     - `error_type` (if applicable)
+    - `prompt_id` (string)
+    - `tool_type` ("native" or "mcp")
+    - `mcp_server_name` (string, if applicable)
+    - `extension_name` (string, if applicable)
+    - `extension_id` (string, if applicable)
     - `content_length` (int, if applicable)
-    - `metadata` (if applicable, dictionary of string -> any)
+    - `metadata` (if applicable)
 
-- `gemini_cli.file_operation`: This event occurs for each file operation.
-  - **Attributes**:
-    - `tool_name` (string)
-    - `operation` (string: "create", "read", "update")
-    - `lines` (int, if applicable)
-    - `mimetype` (string, if applicable)
-    - `extension` (string, if applicable)
-    - `programming_language` (string, if applicable)
-    - `diff_stat` (json string, if applicable): A JSON string with the following
-      members:
-      - `ai_added_lines` (int)
-      - `ai_removed_lines` (int)
-      - `user_added_lines` (int)
-      - `user_removed_lines` (int)
-
-- `gemini_cli.api_request`: This event occurs when making a request to Gemini
-  API.
-  - **Attributes**:
-    - `model`
-    - `request_text` (if applicable)
-
-- `gemini_cli.api_error`: This event occurs if the API request fails.
-  - **Attributes**:
-    - `model`
-    - `error`
-    - `error_type`
-    - `status_code`
-    - `duration_ms`
-    - `auth_type`
-
-- `gemini_cli.api_response`: This event occurs upon receiving a response from
-  Gemini API.
-  - **Attributes**:
-    - `model`
-    - `status_code`
-    - `duration_ms`
-    - `error` (optional)
-    - `input_token_count`
-    - `output_token_count`
-    - `cached_content_token_count`
-    - `thoughts_token_count`
-    - `tool_token_count`
-    - `response_text` (if applicable)
-    - `auth_type`
-
-- `gemini_cli.tool_output_truncated`: This event occurs when the output of a
-  tool call is too large and gets truncated.
+- `gemini_cli.tool_output_truncated`: Output of a tool call was truncated.
   - **Attributes**:
     - `tool_name` (string)
     - `original_content_length` (int)
@@ -305,32 +296,231 @@ for Gemini CLI:
     - `lines` (int)
     - `prompt_id` (string)
 
-- `gemini_cli.malformed_json_response`: This event occurs when a `generateJson`
-  response from Gemini API cannot be parsed as a json.
+- `gemini_cli.smart_edit_strategy`: Smart Edit strategy chosen.
   - **Attributes**:
-    - `model`
+    - `strategy` (string)
 
-- `gemini_cli.flash_fallback`: This event occurs when Gemini CLI switches to
-  flash as fallback.
+- `gemini_cli.smart_edit_correction`: Smart Edit correction result.
   - **Attributes**:
-    - `auth_type`
+    - `correction` ("success" | "failure")
 
-- `gemini_cli.slash_command`: This event occurs when a user executes a slash
-  command.
+- `gen_ai.client.inference.operation.details`: This event provides detailed
+  information about the GenAI operation, aligned with [OpenTelemetry GenAI
+  semantic conventions for events].
+  - **Attributes**:
+    - `gen_ai.request.model` (string)
+    - `gen_ai.provider.name` (string)
+    - `gen_ai.operation.name` (string)
+    - `gen_ai.input.messages` (json string)
+    - `gen_ai.output.messages` (json string)
+    - `gen_ai.response.finish_reasons` (array of strings)
+    - `gen_ai.usage.input_tokens` (int)
+    - `gen_ai.usage.output_tokens` (int)
+    - `gen_ai.request.temperature` (float)
+    - `gen_ai.request.top_p` (float)
+    - `gen_ai.request.top_k` (int)
+    - `gen_ai.request.max_tokens` (int)
+    - `gen_ai.system_instructions` (json string)
+    - `server.address` (string)
+    - `server.port` (int)
+
+#### Files
+
+Tracks file operations performed by tools.
+
+- `gemini_cli.file_operation`: Emitted for each file operation.
+  - **Attributes**:
+    - `tool_name` (string)
+    - `operation` ("create" | "read" | "update")
+    - `lines` (int, optional)
+    - `mimetype` (string, optional)
+    - `extension` (string, optional)
+    - `programming_language` (string, optional)
+
+#### API
+
+Captures Gemini API requests, responses, and errors.
+
+- `gemini_cli.api_request`: Request sent to Gemini API.
+  - **Attributes**:
+    - `model` (string)
+    - `prompt_id` (string)
+    - `request_text` (string, optional)
+
+- `gemini_cli.api_response`: Response received from Gemini API.
+  - **Attributes**:
+    - `model` (string)
+    - `status_code` (int|string)
+    - `duration_ms` (int)
+    - `input_token_count` (int)
+    - `output_token_count` (int)
+    - `cached_content_token_count` (int)
+    - `thoughts_token_count` (int)
+    - `tool_token_count` (int)
+    - `total_token_count` (int)
+    - `response_text` (string, optional)
+    - `prompt_id` (string)
+    - `auth_type` (string)
+
+- `gemini_cli.api_error`: API request failed.
+  - **Attributes**:
+    - `model` (string)
+    - `error` (string)
+    - `error_type` (string)
+    - `status_code` (int|string)
+    - `duration_ms` (int)
+    - `prompt_id` (string)
+    - `auth_type` (string)
+
+- `gemini_cli.malformed_json_response`: `generateJson` response could not be
+  parsed.
+  - **Attributes**:
+    - `model` (string)
+
+#### Model Routing
+
+Tracks model selections via slash commands and router decisions.
+
+- `gemini_cli.slash_command`: A slash command was executed.
   - **Attributes**:
     - `command` (string)
-    - `subcommand` (string, if applicable)
+    - `subcommand` (string, optional)
+    - `status` ("success" | "error")
 
-- `gemini_cli.extension_enable`: This event occurs when an extension is enabled
-- `gemini_cli.extension_install`: This event occurs when an extension is
-  installed
+- `gemini_cli.slash_command.model`: Model was selected via slash command.
+  - **Attributes**:
+    - `model_name` (string)
+
+- `gemini_cli.model_routing`: Model router made a decision.
+  - **Attributes**:
+    - `decision_model` (string)
+    - `decision_source` (string)
+    - `routing_latency_ms` (int)
+    - `reasoning` (string, optional)
+    - `failed` (boolean)
+    - `error_message` (string, optional)
+
+#### Chat and Streaming
+
+Observes streaming integrity, compression, and retry behavior.
+
+- `gemini_cli.chat_compression`: Chat context was compressed.
+  - **Attributes**:
+    - `tokens_before` (int)
+    - `tokens_after` (int)
+
+- `gemini_cli.chat.invalid_chunk`: Invalid chunk received from a stream.
+  - **Attributes**:
+    - `error.message` (string, optional)
+
+- `gemini_cli.chat.content_retry`: Retry triggered due to a content error.
+  - **Attributes**:
+    - `attempt_number` (int)
+    - `error_type` (string)
+    - `retry_delay_ms` (int)
+    - `model` (string)
+
+- `gemini_cli.chat.content_retry_failure`: All content retries failed.
+  - **Attributes**:
+    - `total_attempts` (int)
+    - `final_error_type` (string)
+    - `total_duration_ms` (int, optional)
+    - `model` (string)
+
+- `gemini_cli.conversation_finished`: Conversation session ended.
+  - **Attributes**:
+    - `approvalMode` (string)
+    - `turnCount` (int)
+
+- `gemini_cli.next_speaker_check`: Next speaker determination.
+  - **Attributes**:
+    - `prompt_id` (string)
+    - `finish_reason` (string)
+    - `result` (string)
+
+#### Resilience
+
+Records fallback mechanisms for models and network operations.
+
+- `gemini_cli.flash_fallback`: Switched to a flash model as fallback.
+  - **Attributes**:
+    - `auth_type` (string)
+
+- `gemini_cli.ripgrep_fallback`: Switched to grep as fallback for file search.
+  - **Attributes**:
+    - `error` (string, optional)
+
+- `gemini_cli.web_fetch_fallback_attempt`: Attempted web-fetch fallback.
+  - **Attributes**:
+    - `reason` ("private_ip" | "primary_failed")
+
+#### Extensions
+
+Tracks extension lifecycle and settings changes.
+
+- `gemini_cli.extension_install`: An extension was installed.
   - **Attributes**:
     - `extension_name` (string)
     - `extension_version` (string)
     - `extension_source` (string)
     - `status` (string)
-- `gemini_cli.extension_uninstall`: This event occurs when an extension is
-  uninstalled
+
+- `gemini_cli.extension_uninstall`: An extension was uninstalled.
+  - **Attributes**:
+    - `extension_name` (string)
+    - `status` (string)
+
+- `gemini_cli.extension_enable`: An extension was enabled.
+  - **Attributes**:
+    - `extension_name` (string)
+    - `setting_scope` (string)
+
+- `gemini_cli.extension_disable`: An extension was disabled.
+  - **Attributes**:
+    - `extension_name` (string)
+    - `setting_scope` (string)
+
+- `gemini_cli.extension_update`: An extension was updated.
+  - **Attributes**:
+    - `extension_name` (string)
+    - `extension_version` (string)
+    - `extension_previous_version` (string)
+    - `extension_source` (string)
+    - `status` (string)
+
+#### Agent Runs
+
+Tracks agent lifecycle and outcomes.
+
+- `gemini_cli.agent.start`: Agent run started.
+  - **Attributes**:
+    - `agent_id` (string)
+    - `agent_name` (string)
+
+- `gemini_cli.agent.finish`: Agent run finished.
+  - **Attributes**:
+    - `agent_id` (string)
+    - `agent_name` (string)
+    - `duration_ms` (int)
+    - `turn_count` (int)
+    - `terminate_reason` (string)
+
+#### IDE
+
+Captures IDE connectivity and conversation lifecycle events.
+
+- `gemini_cli.ide_connection`: IDE companion connection.
+  - **Attributes**:
+    - `connection_type` (string)
+
+#### UI
+
+Tracks terminal rendering issues and related signals.
+
+- `kitty_sequence_overflow`: Terminal kitty control sequence overflow.
+  - **Attributes**:
+    - `sequence_length` (int)
+    - `truncated_sequence` (string)
 
 ### Metrics
 
@@ -338,27 +528,31 @@ Metrics are numerical measurements of behavior over time.
 
 #### Custom
 
+##### Sessions
+
+Counts CLI sessions at startup.
+
 - `gemini_cli.session.count` (Counter, Int): Incremented once per CLI startup.
 
+##### Tools
+
+Measures tool usage and latency.
+
 - `gemini_cli.tool.call.count` (Counter, Int): Counts tool calls.
   - **Attributes**:
     - `function_name`
     - `success` (boolean)
-    - `decision` (string: "accept", "reject", or "modify", if applicable)
-    - `tool_type` (string: "mcp", or "native", if applicable)
-    - `model_added_lines` (Int, optional): Lines added by model in the proposed
-      changes, if applicable
-    - `model_removed_lines` (Int, optional): Lines removed by model in the
-      proposed changes, if applicable
-    - `user_added_lines` (Int, optional): Lines added by user edits after model
-      proposal, if applicable
-    - `user_removed_lines` (Int, optional): Lines removed by user edits after
-      model proposal, if applicable
+    - `decision` (string: "accept", "reject", "modify", or "auto_accept", if
+      applicable)
+    - `tool_type` (string: "mcp" or "native", if applicable)
 
 - `gemini_cli.tool.call.latency` (Histogram, ms): Measures tool call latency.
   - **Attributes**:
     - `function_name`
-    - `decision` (string: "accept", "reject", or "modify", if applicable)
+
+##### API
+
+Tracks API request volume and latency.
 
 - `gemini_cli.api.request.count` (Counter, Int): Counts all API requests.
   - **Attributes**:
@@ -370,32 +564,167 @@ Metrics are numerical measurements of behavior over time.
   latency.
   - **Attributes**:
     - `model`
-  - **Note**: This metric overlaps with `gen_ai.client.operation.duration` below
-    that's compliant with GenAI Semantic Conventions.
+  - Note: Overlaps with `gen_ai.client.operation.duration` (GenAI conventions).
 
-- `gemini_cli.token.usage` (Counter, Int): Counts the number of tokens used.
+##### Token Usage
+
+Tracks tokens used by model and type.
+
+- `gemini_cli.token.usage` (Counter, Int): Counts tokens used.
   - **Attributes**:
     - `model`
-    - `type` (string: "input", "output", "thought", "cache", or "tool")
-  - **Note**: This metric overlaps with `gen_ai.client.token.usage` below for
-    `input`/`output` token types that's compliant with GenAI Semantic
-    Conventions.
+    - `type` ("input", "output", "thought", "cache", or "tool")
+  - Note: Overlaps with `gen_ai.client.token.usage` for `input`/`output`.
+
+##### Files
+
+Counts file operations with basic context.
 
 - `gemini_cli.file.operation.count` (Counter, Int): Counts file operations.
   - **Attributes**:
-    - `operation` (string: "create", "read", "update"): The type of file
-      operation.
-    - `lines` (Int, if applicable): Number of lines in the file.
-    - `mimetype` (string, if applicable): Mimetype of the file.
-    - `extension` (string, if applicable): File extension of the file.
-    - `programming_language` (string, if applicable): The programming language
-      of the file.
+    - `operation` ("create", "read", "update")
+    - `lines` (Int, optional)
+    - `mimetype` (string, optional)
+    - `extension` (string, optional)
+    - `programming_language` (string, optional)
+
+- `gemini_cli.lines.changed` (Counter, Int): Number of lines changed (from file
+  diffs).
+  - **Attributes**:
+    - `function_name`
+    - `type` ("added" or "removed")
+
+##### Chat and Streaming
+
+Resilience counters for compression, invalid chunks, and retries.
 
 - `gemini_cli.chat_compression` (Counter, Int): Counts chat compression
-  operations
+  operations.
   - **Attributes**:
-    - `tokens_before`: (Int): Number of tokens in context prior to compression
-    - `tokens_after`: (Int): Number of tokens in context after compression
+    - `tokens_before` (Int)
+    - `tokens_after` (Int)
+
+- `gemini_cli.chat.invalid_chunk.count` (Counter, Int): Counts invalid chunks
+  from streams.
+
+- `gemini_cli.chat.content_retry.count` (Counter, Int): Counts retries due to
+  content errors.
+
+- `gemini_cli.chat.content_retry_failure.count` (Counter, Int): Counts requests
+  where all content retries failed.
+
+##### Model Routing
+
+Routing latency/failures and slash-command selections.
+
+- `gemini_cli.slash_command.model.call_count` (Counter, Int): Counts model
+  selections via slash command.
+  - **Attributes**:
+    - `slash_command.model.model_name` (string)
+
+- `gemini_cli.model_routing.latency` (Histogram, ms): Model routing decision
+  latency.
+  - **Attributes**:
+    - `routing.decision_model` (string)
+    - `routing.decision_source` (string)
+
+- `gemini_cli.model_routing.failure.count` (Counter, Int): Counts model routing
+  failures.
+  - **Attributes**:
+    - `routing.decision_source` (string)
+    - `routing.error_message` (string)
+
+##### Agent Runs
+
+Agent lifecycle metrics: runs, durations, and turns.
+
+- `gemini_cli.agent.run.count` (Counter, Int): Counts agent runs.
+  - **Attributes**:
+    - `agent_name` (string)
+    - `terminate_reason` (string)
+
+- `gemini_cli.agent.duration` (Histogram, ms): Agent run durations.
+  - **Attributes**:
+    - `agent_name` (string)
+
+- `gemini_cli.agent.turns` (Histogram, turns): Turns taken per agent run.
+  - **Attributes**:
+    - `agent_name` (string)
+
+##### UI
+
+UI stability signals such as flicker count.
+
+- `gemini_cli.ui.flicker.count` (Counter, Int): Counts UI frames that flicker
+  (render taller than terminal).
+
+##### Performance
+
+Optional performance monitoring for startup, CPU/memory, and phase timing.
+
+- `gemini_cli.startup.duration` (Histogram, ms): CLI startup time by phase.
+  - **Attributes**:
+    - `phase` (string)
+    - `details` (map, optional)
+
+- `gemini_cli.memory.usage` (Histogram, bytes): Memory usage.
+  - **Attributes**:
+    - `memory_type` ("heap_used", "heap_total", "external", "rss")
+    - `component` (string, optional)
+
+- `gemini_cli.cpu.usage` (Histogram, percent): CPU usage percentage.
+  - **Attributes**:
+    - `component` (string, optional)
+
+- `gemini_cli.tool.queue.depth` (Histogram, count): Number of tools in the
+  execution queue.
+
+- `gemini_cli.tool.execution.breakdown` (Histogram, ms): Tool time by phase.
+  - **Attributes**:
+    - `function_name` (string)
+    - `phase` ("validation", "preparation", "execution", "result_processing")
+
+- `gemini_cli.api.request.breakdown` (Histogram, ms): API request time by phase.
+  - **Attributes**:
+    - `model` (string)
+    - `phase` ("request_preparation", "network_latency", "response_processing",
+      "token_processing")
+
+- `gemini_cli.token.efficiency` (Histogram, ratio): Token efficiency metrics.
+  - **Attributes**:
+    - `model` (string)
+    - `metric` (string)
+    - `context` (string, optional)
+
+- `gemini_cli.performance.score` (Histogram, score): Composite performance
+  score.
+  - **Attributes**:
+    - `category` (string)
+    - `baseline` (number, optional)
+
+- `gemini_cli.performance.regression` (Counter, Int): Regression detection
+  events.
+  - **Attributes**:
+    - `metric` (string)
+    - `severity` ("low", "medium", "high")
+    - `current_value` (number)
+    - `baseline_value` (number)
+
+- `gemini_cli.performance.regression.percentage_change` (Histogram, percent):
+  Percent change from baseline when regression detected.
+  - **Attributes**:
+    - `metric` (string)
+    - `severity` ("low", "medium", "high")
+    - `current_value` (number)
+    - `baseline_value` (number)
+
+- `gemini_cli.performance.baseline.comparison` (Histogram, percent): Comparison
+  to baseline.
+  - **Attributes**:
+    - `metric` (string)
+    - `category` (string)
+    - `current_value` (number)
+    - `baseline_value` (number)
 
 #### GenAI Semantic Convention
 
@@ -434,3 +763,5 @@ standardized observability across GenAI applications:
 
 [OpenTelemetry GenAI semantic conventions]:
   https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-metrics.md
+[OpenTelemetry GenAI semantic conventions for events]:
+  https://github.com/open-telemetry/semantic-conventions/blob/8b4f210f43136e57c1f6f47292eb6d38e3bf30bb/docs/gen-ai/gen-ai-events.md

docs/cli/themes.md

@@ -88,6 +88,11 @@ color keys. For example:
 - `DiffRemoved` (optional, for removed lines in diffs)
 - `DiffModified` (optional, for modified lines in diffs)
 
+You can also override individual UI text roles by adding a nested `text` object.
+This object supports the keys `primary`, `secondary`, `link`, `accent`, and
+`response`. When `text.response` is provided it takes precedence over
+`text.primary` for rendering model responses in chat.
+
 **Required Properties:**
 
 - `name` (must match the key in the `customThemes` object and be a string)
@@ -183,50 +188,50 @@ untrusted sources.
 
 ### ANSI
 
-<img src="../assets/theme-ansi.png" alt="ANSI theme" width="600" />
+<img src="/assets/theme-ansi.png" alt="ANSI theme" width="600" />
 
 ### Atom OneDark
 
-<img src="../assets/theme-atom-one.png" alt="Atom One theme" width="600">
+<img src="/assets/theme-atom-one.png" alt="Atom One theme" width="600">
 
 ### Ayu
 
-<img src="../assets/theme-ayu.png" alt="Ayu theme" width="600">
+<img src="/assets/theme-ayu.png" alt="Ayu theme" width="600">
 
 ### Default
 
-<img src="../assets/theme-default.png" alt="Default theme" width="600">
+<img src="/assets/theme-default.png" alt="Default theme" width="600">
 
 ### Dracula
 
-<img src="../assets/theme-dracula.png" alt="Dracula theme" width="600">
+<img src="/assets/theme-dracula.png" alt="Dracula theme" width="600">
 
 ### GitHub
 
-<img src="../assets/theme-github.png" alt="GitHub theme" width="600">
+<img src="/assets/theme-github.png" alt="GitHub theme" width="600">
 
 ## Light Themes
 
 ### ANSI Light
 
-<img src="../assets/theme-ansi-light.png" alt="ANSI Light theme" width="600">
+<img src="/assets/theme-ansi-light.png" alt="ANSI Light theme" width="600">
 
 ### Ayu Light
 
-<img src="../assets/theme-ayu-light.png" alt="Ayu Light theme" width="600">
+<img src="/assets/theme-ayu-light.png" alt="Ayu Light theme" width="600">
 
 ### Default Light
 
-<img src="../assets/theme-default-light.png" alt="Default Light theme" width="600">
+<img src="/assets/theme-default-light.png" alt="Default Light theme" width="600">
 
 ### GitHub Light
 
-<img src="../assets/theme-github-light.png" alt="GitHub Light theme" width="600">
+<img src="/assets/theme-github-light.png" alt="GitHub Light theme" width="600">
 
 ### Google Code
 
-<img src="../assets/theme-google-light.png" alt="Google Code theme" width="600">
+<img src="/assets/theme-google-light.png" alt="Google Code theme" width="600">
 
 ### Xcode
 
-<img src="../assets/theme-xcode-light.png" alt="Xcode Light theme" width="600">
+<img src="/assets/theme-xcode-light.png" alt="Xcode Light theme" width="600">

docs/cli/trusted-folders.md

@@ -59,6 +59,13 @@ to protect you. In this mode, the following features are disabled:
 5.  **Automatic Memory Loading is Disabled**: The CLI will not automatically
     load files into context from directories specified in local settings.
 
+6.  **MCP Servers Do Not Connect**: The CLI will not attempt to connect to any
+    [Model Context Protocol (MCP)](../tools/mcp-server.md) servers.
+
+7.  **Custom Commands are Not Loaded**: The CLI will not load any custom
+    commands from .toml files, including both project-specific and global user
+    commands.
+
 Granting trust to a folder unlocks the full functionality of the Gemini CLI for
 that workspace.
 

docs/core/index.md

@@ -11,6 +11,8 @@ requests sent from `packages/cli`. For a general overview of Gemini CLI, see the
   registered, and used by the core.
 - **[Memory Import Processor](./memport.md):** Documentation for the modular
   GEMINI.md import feature using @file.md syntax.
+- **[Policy Engine](./policy-engine.md):** Use the Policy Engine for
+  fine-grained control over tool execution.
 
 ## Role of the core
 

docs/core/policy-engine.md

@@ -0,0 +1,246 @@
+# 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.
+
+## Core concepts
+
+The policy engine operates on a set of rules. Each rule is a combination of
+conditions and a resulting decision. When a large language model wants to
+execute a tool, the policy engine evaluates all rules to find the
+highest-priority rule that matches the tool call.
+
+A rule consists of the following main components:
+
+- **Conditions**: Criteria that a tool call must meet for the rule to apply.
+  This can include the tool's name, the arguments provided to it, or the current
+  approval mode.
+- **Decision**: The action to take if the rule matches (`allow`, `deny`, or
+  `ask_user`).
+- **Priority**: A number that determines the rule's precedence. Higher numbers
+  win.
+
+For example, this rule will ask for user confirmation before executing any `git`
+command.
+
+```toml
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = "git "
+decision = "ask_user"
+priority = 100
+```
+
+### Conditions
+
+Conditions are the criteria that a tool call must meet for a rule to apply. The
+primary conditions are the tool's name and its arguments.
+
+#### Tool Name
+
+The `toolName` in the rule must match the name of the tool being called.
+
+- **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
+  wildcard. A `toolName` of `my-server__*` will match any tool from the
+  `my-server` MCP.
+
+#### Arguments Pattern
+
+If `argsPattern` is specified, the tool's arguments are converted to a stable
+JSON string, which is then tested against the provided regular expression. If
+the arguments don't match the pattern, the rule does not apply.
+
+### Decisions
+
+There are three possible decisions a rule can enforce:
+
+- `allow`: The tool call is executed automatically without user interaction.
+- `deny`: The tool call is blocked and is not executed.
+- `ask_user`: The user is prompted to approve or deny the tool call. (In
+  non-interactive mode, this is treated as `deny`.)
+
+### Priority system & tiers
+
+The policy engine uses a sophisticated priority system to resolve conflicts when
+multiple rules match a single tool call. The core principle is simple: **the
+rule with the highest priority wins**.
+
+To provide a clear hierarchy, policies are organized into three tiers. Each tier
+has a designated number that forms the base of the final priority calculation.
+
+| Tier    | Base | Description                                                                |
+| :------ | :--- | :------------------------------------------------------------------------- |
+| Default | 1    | Built-in policies that ship with the Gemini CLI.                           |
+| User    | 2    | Custom policies defined by the user.                                       |
+| Admin   | 3    | Policies managed by an administrator (e.g., in an enterprise environment). |
+
+Within a TOML policy file, you assign a priority value from **0 to 999**. The
+engine transforms this into a final priority using the following formula:
+
+`final_priority = tier_base + (toml_priority / 1000)`
+
+This system guarantees that:
+
+- Admin policies always override User and Default policies.
+- User policies always override Default policies.
+- You can still order rules within a single tier with fine-grained control.
+
+For example:
+
+- A `priority: 50` rule in a Default policy file becomes `1.050`.
+- A `priority: 100` rule in a User policy file becomes `2.100`.
+- A `priority: 20` rule in an Admin policy file becomes `3.020`.
+
+### Approval modes
+
+Approval modes allow the policy engine to apply different sets of rules based on
+the CLI's operational mode. A rule can be associated with one or more modes
+(e.g., `yolo`, `autoEdit`). The rule will only be active if the CLI is running
+in one of its specified modes. If a rule has no modes specified, it is always
+active.
+
+## Rule matching
+
+When a tool call is made, the engine checks it against all active rules,
+starting from the highest priority. The first rule that matches determines the
+outcome.
+
+A rule matches a tool call if all of its conditions are met:
+
+1.  **Tool Name**: The `toolName` in the rule must match the name of the tool
+    being called.
+    - **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
+      wildcard. A `toolName` of `my-server__*` will match any tool from the
+      `my-server` MCP.
+2.  **Arguments Pattern**: If `argsPattern` is specified, the tool's arguments
+    are converted to a stable JSON string, which is then tested against the
+    provided regular expression. If the arguments don't match the pattern, the
+    rule does not apply.
+
+## Configuration
+
+Policies are defined in `.toml` files. The CLI loads these files from Default,
+User, and (if configured) Admin directories.
+
+### TOML rule schema
+
+Here is a breakdown of the fields available in a TOML policy rule:
+
+```toml
+[[rule]]
+# A unique name for the tool, or an array of names.
+toolName = "run_shell_command"
+
+# (Optional) The name of an MCP server. Can be combined with toolName
+# to form a composite name like "mcpName__toolName".
+mcpName = "my-custom-server"
+
+# (Optional) A regex to match against the tool's arguments.
+argsPattern = '"command":"(git|npm)'
+
+# (Optional) A string or array of strings that a shell command must start with.
+# This is syntactic sugar for `toolName = "run_shell_command"` and an `argsPattern`.
+commandPrefix = "git "
+
+# (Optional) A regex to match against the entire shell command.
+# This is also syntactic sugar for `toolName = "run_shell_command"`.
+# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`), so anchors like `^` or `$` will apply to the full JSON string, not just the command text.
+# You cannot use commandPrefix and commandRegex in the same rule.
+commandRegex = "^git (commit|push)"
+
+# The decision to take. Must be "allow", "deny", or "ask_user".
+decision = "ask_user"
+
+# The priority of the rule, from 0 to 999.
+priority = 10
+
+# (Optional) An array of approval modes where this rule is active.
+modes = ["autoEdit"]
+```
+
+### Using arrays (lists)
+
+To apply the same rule to multiple tools or command prefixes, you can provide an
+array of strings for the `toolName` and `commandPrefix` fields.
+
+**Example:**
+
+This single rule will apply to both the `write_file` and `replace` tools.
+
+```toml
+[[rule]]
+toolName = ["write_file", "replace"]
+decision = "ask_user"
+priority = 10
+```
+
+### Special syntax for `run_shell_command`
+
+To simplify writing policies for `run_shell_command`, you can use
+`commandPrefix` or `commandRegex` instead of the more complex `argsPattern`.
+
+- `commandPrefix`: Matches if the `command` argument starts with the given
+  string.
+- `commandRegex`: Matches if the `command` argument matches the given regular
+  expression.
+
+**Example:**
+
+This rule will ask for user confirmation before executing any `git` command.
+
+```toml
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = "git "
+decision = "ask_user"
+priority = 100
+```
+
+### Special syntax for MCP tools
+
+You can create rules that target tools from Model-hosting-protocol (MCP) servers
+using the `mcpName` field or a wildcard pattern.
+
+**1. Using `mcpName`**
+
+To target a specific tool from a specific server, combine `mcpName` and
+`toolName`.
+
+```toml
+# Allows the `search` tool on the `my-jira-server` MCP
+[[rule]]
+mcpName = "my-jira-server"
+toolName = "search"
+decision = "allow"
+priority = 200
+```
+
+**2. Using a Wildcard**
+
+To create a rule that applies to _all_ tools on a specific MCP server, specify
+only the `mcpName`.
+
+```toml
+# Denies all tools from the `untrusted-server` MCP
+[[rule]]
+mcpName = "untrusted-server"
+decision = "deny"
+priority = 500
+```
+
+## Default policies
+
+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**.
+- **Write tools** (like `write_file`, `run_shell_command`) default to
+  **`ask_user`**.
+- In **`yolo`** mode, a high-priority rule allows all tools.
+- In **`autoEdit`** mode, rules allow certain write operations to happen without
+  prompting.

docs/core/tools-api.md

@@ -62,8 +62,7 @@ The core comes with a suite of pre-defined tools, typically found in
 
 - **File System Tools:**
   - `LSTool` (`ls.ts`): Lists directory contents.
-  - `ReadFileTool` (`read-file.ts`): Reads the content of a single file. It
-    takes an `absolute_path` parameter, which must be an absolute path.
+  - `ReadFileTool` (`read-file.ts`): Reads the content of a single file.
   - `WriteFileTool` (`write-file.ts`): Writes content to a file.
   - `GrepTool` (`grep.ts`): Searches for patterns in files.
   - `GlobTool` (`glob.ts`): Finds files matching glob patterns.

docs/extensions/extension-releasing.md

@@ -15,11 +15,9 @@ if you need to ship platform specific binary files.
 
 This is the most flexible and simple option. All you need to do is create a
 publicly accessible git repo (such as a public github repository) and then users
-can install your extension using `gemini extensions install <your-repo-uri>`, or
-for a GitHub repository they can use the simplified
-`gemini extensions install <org>/<repo>` format. They can optionally depend on a
-specific ref (branch/tag/commit) using the `--ref=<some-ref>` argument, this
-defaults to the default branch.
+can install your extension using `gemini extensions install <your-repo-uri>`.
+They can optionally depend on a specific ref (branch/tag/commit) using the
+`--ref=<some-ref>` argument, this defaults to the default branch.
 
 Whenever commits are pushed to the ref that a user depends on, they will be
 prompted to update the extension. Note that this also allows for easy rollbacks,

docs/extensions/index.md

@@ -42,16 +42,19 @@ installed on your machine. See
 for help.
 
 ```
-gemini extensions install https://github.com/gemini-cli-extensions/security
+gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent]
 ```
 
-This will install the Gemini CLI Security extension, which offers support for a
-`/security:analyze` command.
+- `<source>`: The github URL or local path of the extension to install.
+- `--ref`: The git ref to install from.
+- `--auto-update`: Enable auto-update for this extension.
+- `--pre-release`: Enable pre-release versions for this extension.
+- `--consent`: Acknowledge the security risks of installing an extension and
+  skip the confirmation prompt.
 
 ### Uninstalling an extension
 
-To uninstall, run `gemini extensions uninstall extension-name`, so, in the case
-of the install example:
+To uninstall, run `gemini extensions uninstall <name>`:
 
 ```
 gemini extensions uninstall gemini-cli-security
@@ -62,27 +65,31 @@ gemini extensions uninstall gemini-cli-security
 Extensions are, by default, enabled across all workspaces. You can disable an
 extension entirely or for specific workspace.
 
-For example, `gemini extensions disable extension-name` will disable the
-extension at the user level, so it will be disabled everywhere.
-`gemini extensions disable extension-name --scope=workspace` will only disable
-the extension in the current workspace.
+```
+gemini extensions disable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to disable.
+- `--scope`: The scope to disable the extension in (`user` or `workspace`).
 
 ### Enabling an extension
 
-You can enable extensions using `gemini extensions enable extension-name`. You
-can also enable an extension for a specific workspace using
-`gemini extensions enable extension-name --scope=workspace` from within that
-workspace.
+You can enable extensions using `gemini extensions enable <name>`. You can also
+enable an extension for a specific workspace using
+`gemini extensions enable <name> --scope=workspace` from within that workspace.
 
-This is useful if you have an extension disabled at the top-level and only
-enabled in specific places.
+```
+gemini extensions enable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to enable.
+- `--scope`: The scope to enable the extension in (`user` or `workspace`).
 
 ### Updating an extension
 
 For extensions installed from a local path or a git repository, you can
 explicitly update to the latest version (as reflected in the
-`gemini-extension.json` `version` field) with
-`gemini extensions update extension-name`.
+`gemini-extension.json` `version` field) with `gemini extensions update <name>`.
 
 You can update all extensions with:
 
@@ -90,10 +97,6 @@ You can update all extensions with:
 gemini extensions update --all
 ```
 
-## Extension creation
-
-We offer commands to make extension development easier.
-
 ### Create a boilerplate extension
 
 We offer several example extensions `context`, `custom-commands`,
@@ -104,9 +107,12 @@ To copy one of these examples into a development directory using the type of
 your choosing, run:
 
 ```
-gemini extensions new path/to/directory custom-commands
+gemini extensions new <path> [template]
 ```
 
+- `<path>`: The path to create the extension in.
+- `[template]`: The boilerplate template to use.
+
 ### Link a local extension
 
 The `gemini extensions link` command will create a symbolic link from the
@@ -116,9 +122,11 @@ This is useful so you don't have to run `gemini extensions update` every time
 you make changes you'd like to test.
 
 ```
-gemini extensions link path/to/directory
+gemini extensions link <path>
 ```
 
+- `<path>`: The path of the extension to link.
+
 ## How it works
 
 On startup, Gemini CLI looks for extensions in `<home>/.gemini/extensions`
@@ -177,6 +185,43 @@ When Gemini CLI starts, it loads all the extensions and merges their
 configurations. If there are any conflicts, the workspace configuration takes
 precedence.
 
+### Settings
+
+_Note: This is an experimental feature. We do not yet recommend extension
+authors introduce settings as part of their core flows._
+
+Extensions can define settings that the user will be prompted to provide upon
+installation. This is useful for things like API keys, URLs, or other
+configuration that the extension needs to function.
+
+To define settings, add a `settings` array to your `gemini-extension.json` file.
+Each object in the array should have the following properties:
+
+- `name`: A user-friendly name for the setting.
+- `description`: A description of the setting and what it's used for.
+- `envVar`: The name of the environment variable that the setting will be stored
+  as.
+- `sensitive`: Optional boolean. If true, obfuscates the input the user provides
+  and stores the secret in keychain storage. **Example**
+
+```json
+{
+  "name": "my-api-extension",
+  "version": "1.0.0",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service.",
+      "envVar": "MY_API_KEY"
+    }
+  ]
+}
+```
+
+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`).
+
 ### Custom commands
 
 Extensions can provide [custom commands](../cli/custom-commands.md) by placing

docs/get-started/authentication.md

@@ -8,13 +8,23 @@ CLI, configure **one** of the following authentication methods:
   - Use Gemini API key
   - Use Vertex AI
 - Headless (non-interactive) mode
-- Google Cloud Shell
+- Google Cloud Environments (Cloud Shell, Compute Engine, etc.)
 
 ## Quick Check: Running in Google Cloud Shell?
 
 If you are running the Gemini CLI within a Google Cloud Shell environment,
 authentication is typically automatic using your Cloud Shell credentials.
 
+### Other Google Cloud Environments (e.g., Compute Engine)
+
+Some other Google Cloud environments, such as Compute Engine VMs, might also
+support automatic authentication. In these environments, Gemini CLI can
+automatically use Application Default Credentials (ADC) sourced from the
+environment's metadata server.
+
+If automatic authentication does not occur in your environment, you will need to
+use one of the interactive methods described below.
+
 ## Authenticate in Interactive mode
 
 When you run Gemini CLI through the command-line, Gemini CLI will provide the

docs/get-started/configuration-v1.md

@@ -473,21 +473,6 @@ a few things you can try in order of recommendation:
     "loadMemoryFromIncludeDirectories": true
     ```
 
-- **`chatCompression`** (object):
-  - **Description:** Controls the settings for chat history compression, both
-    automatic and when manually invoked through the /compress command.
-  - **Properties:**
-    - **`contextPercentageThreshold`** (number): A value between 0 and 1 that
-      specifies the token threshold for compression as a percentage of the
-      model's total token limit. For example, a value of `0.6` will trigger
-      compression when the chat history exceeds 60% of the token limit.
-  - **Example:**
-    ```json
-    "chatCompression": {
-      "contextPercentageThreshold": 0.6
-    }
-    ```
-
 - **`showLineNumbers`** (boolean):
   - **Description:** Controls whether line numbers are displayed in code blocks
     in the CLI output.
@@ -673,9 +658,7 @@ for that specific session.
   - Sets the sandbox image URI.
 - **`--debug`** (**`-d`**):
   - Enables debug mode for this session, providing more verbose output.
-- **`--all-files`** (**`-a`**):
-  - If set, recursively includes all files within the current directory as
-    context for the prompt.
+
 - **`--help`** (or **`-h`**):
   - Displays help information about command-line arguments.
 - **`--show-memory-usage`**:
@@ -709,8 +692,6 @@ for that specific session.
 - **`--telemetry-log-prompts`**:
   - Enables logging of prompts for telemetry. See
     [telemetry](../cli/telemetry.md) for more information.
-- **`--checkpointing`**:
-  - Enables [checkpointing](../cli/checkpointing.md).
 - **`--extensions <extension_name ...>`** (**`-e <extension_name ...>`**):
   - Specifies a list of extensions to use for the session. If not provided, all
     available extensions are used.

docs/get-started/configuration.md

@@ -36,6 +36,11 @@ overridden by higher numbers):
 Gemini CLI uses JSON settings files for persistent configuration. There are four
 locations for these files:
 
+> **Tip:** JSON-aware editors can use autocomplete and validation by pointing to
+> the generated schema at `schemas/settings.schema.json` in this repository.
+> When working outside the repo, reference the hosted schema at
+> `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json`.
+
 - **System defaults file:**
   - **Location:** `/etc/gemini-cli/system-defaults.json` (Linux),
     `C:\ProgramData\gemini-cli\system-defaults.json` (Windows) or
@@ -65,11 +70,12 @@ locations for these files:
     controls over users' Gemini CLI setups.
 
 **Note on environment variables in settings:** String values within your
-`settings.json` files can reference environment variables using either
-`$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically
-resolved when the settings are loaded. For example, if you have an environment
-variable `MY_API_TOKEN`, you could use it in `settings.json` like this:
-`"apiKey": "$MY_API_TOKEN"`.
+`settings.json` and `gemini-extension.json` files can reference environment
+variables using either `$VAR_NAME` or `${VAR_NAME}` syntax. These variables will
+be automatically resolved when the settings are loaded. For example, if you have
+an environment variable `MY_API_TOKEN`, you could use it in `settings.json` like
+this: `"apiKey": "$MY_API_TOKEN"`. Additionally, each extension can have its own
+`.env` file in its directory, which will be loaded automatically.
 
 > **Note for Enterprise Users:** For guidance on deploying and managing Gemini
 > CLI in a corporate environment, please see the
@@ -88,18 +94,25 @@ contain other project-specific files related to Gemini CLI's operation, such as:
 Settings are organized into categories. All settings should be placed within
 their corresponding top-level category object in your `settings.json` file.
 
+<!-- SETTINGS-AUTOGEN:START -->
+
 #### `general`
 
+- **`general.previewFeatures`** (boolean):
+  - **Description:** Enable preview features (e.g., preview models).
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 - **`general.preferredEditor`** (string):
   - **Description:** The preferred editor to open files in.
   - **Default:** `undefined`
 
 - **`general.vimMode`** (boolean):
-  - **Description:** Enable Vim keybindings.
+  - **Description:** Enable Vim keybindings
   - **Default:** `false`
 
 - **`general.disableAutoUpdate`** (boolean):
-  - **Description:** Disable automatic updates.
+  - **Description:** Disable automatic updates
   - **Default:** `false`
 
 - **`general.disableUpdateNag`** (boolean):
@@ -107,25 +120,46 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `false`
 
 - **`general.checkpointing.enabled`** (boolean):
-  - **Description:** Enable session checkpointing for recovery.
+  - **Description:** Enable session checkpointing for recovery
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 - **`general.enablePromptCompletion`** (boolean):
   - **Description:** Enable AI-powered prompt completion suggestions while
     typing.
   - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`general.retryFetchErrors`** (boolean):
+  - **Description:** Retry on "exception TypeError: fetch failed sending
+    request" errors.
+  - **Default:** `false`
 
 - **`general.debugKeystrokeLogging`** (boolean):
   - **Description:** Enable debug logging of keystrokes to the console.
   - **Default:** `false`
 
 - **`general.sessionRetention.enabled`** (boolean):
-  - **Description:** Enable automatic session cleanup.
+  - **Description:** Enable automatic session cleanup
   - **Default:** `false`
 
+- **`general.sessionRetention.maxAge`** (string):
+  - **Description:** Maximum age of sessions to keep (e.g., "30d", "7d", "24h",
+    "1w")
+  - **Default:** `undefined`
+
+- **`general.sessionRetention.maxCount`** (number):
+  - **Description:** Alternative: Maximum number of sessions to keep (most
+    recent)
+  - **Default:** `undefined`
+
+- **`general.sessionRetention.minRetention`** (string):
+  - **Description:** Minimum retention period (safety limit, defaults to "1d")
+  - **Default:** `"1d"`
+
 #### `output`
 
-- **`output.format`** (string):
+- **`output.format`** (enum):
   - **Description:** The format of the CLI output.
   - **Default:** `"text"`
   - **Values:** `"text"`, `"json"`
@@ -133,8 +167,8 @@ their corresponding top-level category object in your `settings.json` file.
 #### `ui`
 
 - **`ui.theme`** (string):
-  - **Description:** The color theme for the UI. See [Themes](../cli/themes.md)
-    for available options.
+  - **Description:** The color theme for the UI. See the CLI themes guide for
+    available options.
   - **Default:** `undefined`
 
 - **`ui.customThemes`** (object):
@@ -142,20 +176,21 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `{}`
 
 - **`ui.hideWindowTitle`** (boolean):
-  - **Description:** Hide the window title bar.
+  - **Description:** Hide the window title bar
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 - **`ui.showStatusInTitle`** (boolean):
   - **Description:** Show Gemini CLI status and thoughts in the terminal window
-    title.
+    title
   - **Default:** `false`
 
 - **`ui.hideTips`** (boolean):
-  - **Description:** Hide helpful tips in the UI.
+  - **Description:** Hide helpful tips in the UI
   - **Default:** `false`
 
 - **`ui.hideBanner`** (boolean):
-  - **Description:** Hide the application banner.
+  - **Description:** Hide the application banner
   - **Default:** `false`
 
 - **`ui.hideContextSummary`** (boolean):
@@ -163,10 +198,6 @@ their corresponding top-level category object in your `settings.json` file.
     input.
   - **Default:** `false`
 
-- **`ui.hideFooter`** (boolean):
-  - **Description:** Hide the footer from the UI.
-  - **Default:** `false`
-
 - **`ui.footer.hideCWD`** (boolean):
   - **Description:** Hide the current working directory path in the footer.
   - **Default:** `false`
@@ -179,8 +210,16 @@ their corresponding top-level category object in your `settings.json` file.
   - **Description:** Hide the model name and context usage in the footer.
   - **Default:** `false`
 
+- **`ui.footer.hideContextPercentage`** (boolean):
+  - **Description:** Hides the context window remaining percentage.
+  - **Default:** `true`
+
+- **`ui.hideFooter`** (boolean):
+  - **Description:** Hide the footer from the UI
+  - **Default:** `false`
+
 - **`ui.showMemoryUsage`** (boolean):
-  - **Description:** Display memory usage information in the UI.
+  - **Description:** Display memory usage information in the UI
   - **Default:** `false`
 
 - **`ui.showLineNumbers`** (boolean):
@@ -189,32 +228,51 @@ their corresponding top-level category object in your `settings.json` file.
 
 - **`ui.showCitations`** (boolean):
   - **Description:** Show citations for generated text in the chat.
-  - **Default:** `true`
+  - **Default:** `false`
+
+- **`ui.showModelInfoInChat`** (boolean):
+  - **Description:** Show the model name in the chat for each model turn.
+  - **Default:** `false`
 
 - **`ui.useFullWidth`** (boolean):
   - **Description:** Use the entire width of the terminal for output.
-  - **Default:** `false`
+  - **Default:** `true`
+
+- **`ui.useAlternateBuffer`** (boolean):
+  - **Description:** Use an alternate screen buffer for the UI, preserving shell
+    history.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`ui.incrementalRendering`** (boolean):
+  - **Description:** Enable incremental rendering for the UI. This option will
+    reduce flickering but may cause rendering artifacts. Only supported when
+    useAlternateBuffer is enabled.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`ui.customWittyPhrases`** (array):
+  - **Description:** Custom witty phrases to display during loading. When
+    provided, the CLI cycles through these instead of the defaults.
+  - **Default:** `[]`
 
 - **`ui.accessibility.disableLoadingPhrases`** (boolean):
-  - **Description:** Disable loading phrases for accessibility.
+  - **Description:** Disable loading phrases for accessibility
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 - **`ui.accessibility.screenReader`** (boolean):
-  - **Description:** Show plaintext interactive view that is more screen reader
-    friendly.
+  - **Description:** Render output in plain-text to be more screen reader
+    accessible
   - **Default:** `false`
-
-- **`ui.customWittyPhrases`** (array of strings):
-  - **Description:** A list of custom phrases to display during loading states.
-    When provided, the CLI will cycle through these phrases instead of the
-    default ones.
-  - **Default:** `[]`
+  - **Requires restart:** Yes
 
 #### `ide`
 
 - **`ide.enabled`** (boolean):
-  - **Description:** Enable IDE integration mode.
+  - **Description:** Enable IDE integration mode
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 - **`ide.hasSeenNudge`** (boolean):
   - **Description:** Whether the user has seen the IDE integration nudge.
@@ -223,8 +281,9 @@ their corresponding top-level category object in your `settings.json` file.
 #### `privacy`
 
 - **`privacy.usageStatisticsEnabled`** (boolean):
-  - **Description:** Enable collection of usage statistics.
+  - **Description:** Enable collection of usage statistics
   - **Default:** `true`
+  - **Requires restart:** Yes
 
 #### `model`
 
@@ -238,32 +297,40 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `-1`
 
 - **`model.summarizeToolOutput`** (object):
-  - **Description:** Enables or disables the summarization of tool output. You
-    can specify the token budget for the summarization using the `tokenBudget`
-    setting. Note: Currently only the `run_shell_command` tool is supported. For
-    example `{"run_shell_command": {"tokenBudget": 2000}}`
+  - **Description:** Enables or disables summarization of tool output. Configure
+    per-tool token budgets (for example {"run_shell_command": {"tokenBudget":
+    2000}}). Currently only the run_shell_command tool supports summarization.
   - **Default:** `undefined`
 
-- **`model.chatCompression.contextPercentageThreshold`** (number):
-  - **Description:** Sets the threshold for chat history compression as a
-    percentage of the model's total token limit. This is a value between 0 and 1
-    that applies to both automatic compression and the manual `/compress`
-    command. For example, a value of `0.6` will trigger compression when the
-    chat history exceeds 60% of the token limit.
-  - **Default:** `0.7`
+- **`model.compressionThreshold`** (number):
+  - **Description:** The fraction of context usage at which to trigger context
+    compression (e.g. 0.2, 0.3).
+  - **Default:** `0.5`
+  - **Requires restart:** Yes
 
 - **`model.skipNextSpeakerCheck`** (boolean):
   - **Description:** Skip the next speaker check.
-  - **Default:** `false`
-
-- **`model.enableShellOutputEfficiency`** (boolean):
-  - **Description:** Optimizes shell tool commands for token efficiency.
   - **Default:** `true`
 
+#### `modelConfigs`
+
+- **`modelConfigs.aliases`** (object):
+  - **Description:** Named presets for model configs. Can be used in place of a
+    model name and can inherit from other aliases using an `extends` property.
+  - **Default:**
+    `{"base":{"modelConfig":{"generateContentConfig":{"temperature":0,"topP":1}}},"chat-base":{"extends":"base","modelConfig":{"generateContentConfig":{"thinkingConfig":{"includeThoughts":true,"thinkingBudget":-1},"temperature":1,"topP":0.95,"topK":64}}},"gemini-2.5-pro":{"extends":"chat-base","modelConfig":{"model":"gemini-2.5-pro"}},"gemini-2.5-flash":{"extends":"chat-base","modelConfig":{"model":"gemini-2.5-flash"}},"gemini-2.5-flash-lite":{"extends":"chat-base","modelConfig":{"model":"gemini-2.5-flash-lite"}},"gemini-2.5-flash-base":{"extends":"base","modelConfig":{"model":"gemini-2.5-flash"}},"classifier":{"extends":"base","modelConfig":{"model":"gemini-2.5-flash-lite","generateContentConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingBudget":512}}}},"prompt-completion":{"extends":"base","modelConfig":{"model":"gemini-2.5-flash-lite","generateContentConfig":{"temperature":0.3,"maxOutputTokens":16000,"thinkingConfig":{"thinkingBudget":0}}}},"edit-corrector":{"extends":"base","modelConfig":{"model":"gemini-2.5-flash-lite","generateContentConfig":{"thinkingConfig":{"thinkingBudget":0}}}},"summarizer-default":{"extends":"base","modelConfig":{"model":"gemini-2.5-flash-lite","generateContentConfig":{"maxOutputTokens":2000}}},"summarizer-shell":{"extends":"base","modelConfig":{"model":"gemini-2.5-flash-lite","generateContentConfig":{"maxOutputTokens":2000}}},"web-search":{"extends":"gemini-2.5-flash-base","modelConfig":{"generateContentConfig":{"tools":[{"googleSearch":{}}]}}},"web-fetch":{"extends":"gemini-2.5-flash-base","modelConfig":{"generateContentConfig":{"tools":[{"urlContext":{}}]}}},"web-fetch-fallback":{"extends":"gemini-2.5-flash-base","modelConfig":{}},"loop-detection":{"extends":"gemini-2.5-flash-base","modelConfig":{}},"loop-detection-double-check":{"extends":"base","modelConfig":{"model":"gemini-2.5-pro"}},"llm-edit-fixer":{"extends":"gemini-2.5-flash-base","modelConfig":{}},"next-speaker-checker":{"extends":"gemini-2.5-flash-base","modelConfig":{}}}`
+
+- **`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
+    used.
+  - **Default:** `[]`
+
 #### `context`
 
-- **`context.fileName`** (string or array of strings):
-  - **Description:** The name of the context file(s).
+- **`context.fileName`** (string | string[]):
+  - **Description:** The name of the context file or files to load into memory.
+    Accepts either a single string or an array of strings.
   - **Default:** `undefined`
 
 - **`context.importFormat`** (string):
@@ -279,42 +346,51 @@ their corresponding top-level category object in your `settings.json` file.
     Missing directories will be skipped with a warning.
   - **Default:** `[]`
 
-- **`context.loadFromIncludeDirectories`** (boolean):
-  - **Description:** Controls the behavior of the `/memory refresh` command. If
-    set to `true`, `GEMINI.md` files should be loaded from all directories that
-    are added. If set to `false`, `GEMINI.md` should only be loaded from the
-    current directory.
+- **`context.loadMemoryFromIncludeDirectories`** (boolean):
+  - **Description:** Controls how /memory refresh loads GEMINI.md files. When
+    true, include directories are scanned; when false, only the current
+    directory is used.
   - **Default:** `false`
 
 - **`context.fileFiltering.respectGitIgnore`** (boolean):
-  - **Description:** Respect .gitignore files when searching.
+  - **Description:** Respect .gitignore files when searching
   - **Default:** `true`
+  - **Requires restart:** Yes
 
 - **`context.fileFiltering.respectGeminiIgnore`** (boolean):
-  - **Description:** Respect .geminiignore files when searching.
+  - **Description:** Respect .geminiignore files when searching
   - **Default:** `true`
+  - **Requires restart:** Yes
 
 - **`context.fileFiltering.enableRecursiveFileSearch`** (boolean):
-  - **Description:** Whether to enable searching recursively for filenames under
-    the current tree when completing `@` prefixes in the prompt.
+  - **Description:** Enable recursive file search functionality when completing
+    @ references in the prompt.
   - **Default:** `true`
+  - **Requires restart:** Yes
 
 - **`context.fileFiltering.disableFuzzySearch`** (boolean):
   - **Description:** Disable fuzzy search when searching for files.
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 #### `tools`
 
-- **`tools.sandbox`** (boolean or string):
-  - **Description:** Sandbox execution environment (can be a boolean or a path
-    string).
+- **`tools.sandbox`** (boolean | string):
+  - **Description:** Sandbox execution environment. Set to a boolean to enable
+    or disable the sandbox, or provide a string path to a sandbox profile.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 - **`tools.shell.enableInteractiveShell`** (boolean):
-  - **Description:** Enables interactive terminal for running shell commands. If
-    an interactive session cannot be started, it will fall back to a standard
-    shell.
+  - **Description:** Use node-pty for an interactive shell experience. Fallback
+    to child_process still applies.
   - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`tools.shell.pager`** (string):
+  - **Description:** The pager command to use for shell output. Defaults to
+    `cat`.
+  - **Default:** `"cat"`
 
 - **`tools.shell.showColor`** (boolean):
   - **Description:** Show color in shell output.
@@ -325,42 +401,37 @@ their corresponding top-level category object in your `settings.json` file.
     considered safe (e.g., read-only operations).
   - **Default:** `false`
 
-- **`tools.core`** (array of strings):
-  - **Description:** This can be used to restrict the set of built-in tools
-    [with an allowlist](../cli/enterprise.md#restricting-tool-access). See
-    [Built-in Tools](../core/tools-api.md#built-in-tools) for a list of core
-    tools. The match semantics are the same as `tools.allowed`.
+- **`tools.core`** (array):
+  - **Description:** Restrict the set of built-in tools with an allowlist. Match
+    semantics mirror tools.allowed; see the built-in tools documentation for
+    available names.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
-- **`tools.exclude`** (array of strings):
+- **`tools.allowed`** (array):
+  - **Description:** Tool names that bypass the confirmation dialog. Useful for
+    trusted commands (for example ["run_shell_command(git)",
+    "run_shell_command(npm test)"]). See shell tool command restrictions for
+    matching details.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.exclude`** (array):
   - **Description:** Tool names to exclude from discovery.
   - **Default:** `undefined`
-
-- **`tools.allowed`** (array of strings):
-  - **Description:** A list of tool names that will bypass the confirmation
-    dialog. This is useful for tools that you trust and use frequently. For
-    example, `["run_shell_command(git)", "run_shell_command(npm test)"]` will
-    skip the confirmation dialog to run any `git` and `npm test` commands. See
-    [Shell Tool command restrictions](../tools/shell.md#command-restrictions)
-    for details on prefix matching, command chaining, etc.
-  - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 - **`tools.discoveryCommand`** (string):
   - **Description:** Command to run for tool discovery.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 - **`tools.callCommand`** (string):
-  - **Description:** Defines a custom shell command for calling a specific tool
-    that was discovered using `tools.discoveryCommand`. The shell command must
-    meet the following criteria:
-    - It must take function `name` (exactly as in
-      [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations))
-      as the first command line argument.
-    - It must read function arguments as JSON on `stdin`, analogous to
-      [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall).
-    - It must return function output as JSON on `stdout`, analogous to
-      [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse).
+  - **Description:** Defines a custom shell command for invoking discovered
+    tools. The command must take the tool name as the first argument, read JSON
+    arguments from stdin, and emit JSON results on stdout.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 - **`tools.useRipgrep`** (boolean):
   - **Description:** Use ripgrep for file content search instead of the fallback
@@ -370,66 +441,110 @@ their corresponding top-level category object in your `settings.json` file.
 - **`tools.enableToolOutputTruncation`** (boolean):
   - **Description:** Enable truncation of large tool outputs.
   - **Default:** `true`
+  - **Requires restart:** Yes
 
 - **`tools.truncateToolOutputThreshold`** (number):
   - **Description:** Truncate tool output if it is larger than this many
     characters. Set to -1 to disable.
-  - **Default:** `20000`
+  - **Default:** `4000000`
+  - **Requires restart:** Yes
 
 - **`tools.truncateToolOutputLines`** (number):
   - **Description:** The number of lines to keep when truncating tool output.
   - **Default:** `1000`
+  - **Requires restart:** Yes
 
 - **`tools.enableMessageBusIntegration`** (boolean):
   - **Description:** Enable policy-based tool confirmation via message bus
-    integration. When enabled, tools will automatically respect policy engine
+    integration. When enabled, tools automatically respect policy engine
     decisions (ALLOW/DENY/ASK_USER) without requiring individual tool
     implementations.
   - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`tools.enableHooks`** (boolean):
+  - **Description:** Enable the hooks system for intercepting and customizing
+    Gemini CLI behavior. When enabled, hooks configured in settings will execute
+    at appropriate lifecycle events (BeforeTool, AfterTool, BeforeModel, etc.).
+    Requires MessageBus integration.
+  - **Default:** `false`
+  - **Requires restart:** Yes
 
 #### `mcp`
 
 - **`mcp.serverCommand`** (string):
   - **Description:** Command to start an MCP server.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
-- **`mcp.allowed`** (array of strings):
-  - **Description:** An allowlist of MCP servers to allow.
+- **`mcp.allowed`** (array):
+  - **Description:** A list of MCP servers to allow.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
-- **`mcp.excluded`** (array of strings):
-  - **Description:** A denylist of MCP servers to exclude.
+- **`mcp.excluded`** (array):
+  - **Description:** A list of MCP servers to exclude.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+#### `useSmartEdit`
+
+- **`useSmartEdit`** (boolean):
+  - **Description:** Enable the smart-edit tool instead of the replace tool.
+  - **Default:** `true`
+
+#### `useWriteTodos`
+
+- **`useWriteTodos`** (boolean):
+  - **Description:** Enable the write_todos tool.
+  - **Default:** `true`
 
 #### `security`
 
+- **`security.disableYoloMode`** (boolean):
+  - **Description:** Disable YOLO mode, even if enabled by a flag.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`security.blockGitExtensions`** (boolean):
+  - **Description:** Blocks installing and loading extensions from Git.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 - **`security.folderTrust.enabled`** (boolean):
   - **Description:** Setting to track whether Folder trust is enabled.
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 - **`security.auth.selectedType`** (string):
   - **Description:** The currently selected authentication type.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 - **`security.auth.enforcedType`** (string):
-  - **Description:** The required auth type (useful for enterprises).
+  - **Description:** The required auth type. If this does not match the selected
+    auth type, the user will be prompted to re-authenticate.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 - **`security.auth.useExternal`** (boolean):
   - **Description:** Whether to use an external authentication flow.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
 #### `advanced`
 
 - **`advanced.autoConfigureMemory`** (boolean):
-  - **Description:** Automatically configure Node.js memory limits.
+  - **Description:** Automatically configure Node.js memory limits
   - **Default:** `false`
+  - **Requires restart:** Yes
 
 - **`advanced.dnsResolutionOrder`** (string):
   - **Description:** The DNS resolution order.
   - **Default:** `undefined`
+  - **Requires restart:** Yes
 
-- **`advanced.excludedEnvVars`** (array of strings):
+- **`advanced.excludedEnvVars`** (array):
   - **Description:** Environment variables to exclude from project context.
   - **Default:** `["DEBUG","DEBUG_MODE"]`
 
@@ -439,10 +554,56 @@ their corresponding top-level category object in your `settings.json` file.
 
 #### `experimental`
 
+- **`experimental.extensionManagement`** (boolean):
+  - **Description:** Enable extension management features.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`experimental.extensionReloading`** (boolean):
+  - **Description:** Enables extension loading/unloading within the CLI session.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 - **`experimental.useModelRouter`** (boolean):
   - **Description:** Enable model routing to route requests to the best model
     based on complexity.
-  - **Default:** `false`
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.enabled`** (boolean):
+  - **Description:** Enable the Codebase Investigator agent.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.maxNumTurns`** (number):
+  - **Description:** Maximum number of turns for the Codebase Investigator
+    agent.
+  - **Default:** `10`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.maxTimeMinutes`** (number):
+  - **Description:** Maximum time for the Codebase Investigator agent (in
+    minutes).
+  - **Default:** `3`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.thinkingBudget`** (number):
+  - **Description:** The thinking budget for the Codebase Investigator agent.
+  - **Default:** `8192`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.model`** (string):
+  - **Description:** The model to use for the Codebase Investigator agent.
+  - **Default:** `"gemini-2.5-pro"`
+  - **Requires restart:** Yes
+
+#### `hooks`
+
+- **`hooks`** (object):
+  - **Description:** Hook configurations for intercepting and customizing agent
+    behavior.
+  - **Default:** `{}`
+  <!-- SETTINGS-AUTOGEN:END -->
 
 #### `mcpServers`
 
@@ -718,21 +879,16 @@ for that specific session.
   - **Values:**
     - `text`: (Default) The standard human-readable output.
     - `json`: A machine-readable JSON output.
+    - `stream-json`: A streaming JSON output that emits real-time events.
   - **Note:** For structured output and scripting, use the
-    `--output-format json` flag.
+    `--output-format json` or `--output-format stream-json` flag.
 - **`--sandbox`** (**`-s`**):
   - Enables sandbox mode for this session.
-- **`--sandbox-image`**:
-  - Sets the sandbox image URI.
 - **`--debug`** (**`-d`**):
   - Enables debug mode for this session, providing more verbose output.
-- **`--all-files`** (**`-a`**):
-  - If set, recursively includes all files within the current directory as
-    context for the prompt.
+
 - **`--help`** (or **`-h`**):
   - Displays help information about command-line arguments.
-- **`--show-memory-usage`**:
-  - Displays the current memory usage.
 - **`--yolo`**:
   - Enables YOLO mode, which automatically approves all tool calls.
 - **`--approval-mode <mode>`**:
@@ -748,22 +904,6 @@ for that specific session.
   - A comma-separated list of tool names that will bypass the confirmation
     dialog.
   - Example: `gemini --allowed-tools "ShellTool(git status)"`
-- **`--telemetry`**:
-  - Enables [telemetry](../cli/telemetry.md).
-- **`--telemetry-target`**:
-  - Sets the telemetry target. See [telemetry](../cli/telemetry.md) for more
-    information.
-- **`--telemetry-otlp-endpoint`**:
-  - Sets the OTLP endpoint for telemetry. See [telemetry](../cli/telemetry.md)
-    for more information.
-- **`--telemetry-otlp-protocol`**:
-  - Sets the OTLP protocol for telemetry (`grpc` or `http`). Defaults to `grpc`.
-    See [telemetry](../cli/telemetry.md) for more information.
-- **`--telemetry-log-prompts`**:
-  - Enables logging of prompts for telemetry. See
-    [telemetry](../cli/telemetry.md) for more information.
-- **`--checkpointing`**:
-  - Enables [checkpointing](../cli/checkpointing.md).
 - **`--extensions <extension_name ...>`** (**`-e <extension_name ...>`**):
   - Specifies a list of extensions to use for the session. If not provided, all
     available extensions are used.
@@ -771,9 +911,6 @@ for that specific session.
   - Example: `gemini -e my-extension -e my-other-extension`
 - **`--list-extensions`** (**`-l`**):
   - Lists all available extensions and exits.
-- **`--proxy`**:
-  - Sets the proxy for the CLI.
-  - Example: `--proxy http://localhost:7890`.
 - **`--include-directories <dir1,dir2,...>`**:
   - Includes additional directories in the workspace for multi-directory
     support.
@@ -786,6 +923,14 @@ for that specific session.
     with screen readers.
 - **`--version`**:
   - Displays the version of the CLI.
+- **`--experimental-acp`**:
+  - Starts the agent in ACP mode.
+- **`--allowed-mcp-server-names`**:
+  - Allowed MCP server names.
+- **`--fake-responses`**:
+  - Path to a file with fake model responses for testing.
+- **`--record-responses`**:
+  - Path to a file to record model responses for testing.
 
 ## Context Files (Hierarchical Instructional Context)
 

docs/get-started/gemini-3.md

@@ -0,0 +1,107 @@
+# Gemini 3 Pro on Gemini CLI (Join the Waitlist)
+
+We’re excited to bring Gemini 3 Pro to Gemini CLI. For Google AI Ultra
+subscribers 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. Sign up for the waitlist now to access Gemini 3 Pro
+once approved.
+
+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.
+
+## Do I need to join the waitlist?
+
+The following users will be **automatically granted access** to Gemini 3 Pro on
+Gemini CLI:
+
+- Google AI Ultra subscribers.
+- 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).
+
+For **Gemini Code Assist Enterprise users**, access is coming soon.
+
+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.
+
+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).
+
+## How to join the waitlist
+
+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).
+
+### Usage limits and fallback
+
+Gemini CLI will tell you when you reach your Gemini 3 Pro daily usage limit.
+When you encounter that limit, you’ll be given the option to switch to Gemini
+2.5 Pro, upgrade for higher limits, or stop. You’ll also be told when your usage
+limit resets and Gemini 3 Pro can be used again.
+
+Similarly, when you reach your daily usage limit for Gemini 2.5 Pro, you’ll see
+a message prompting fallback to Gemini 2.5 Flash.
+
+### Capacity errors
+
+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.
+
+## Model selection & 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.
+
+When using Gemini 3 Pro, you may want to use Auto routing or Pro routing to
+manage your usage limits:
+
+- **Auto routing:** Auto routing first determines whether a prompt involves a
+  complex or simple operation. For simple prompts, it will automatically use
+  Gemini 2.5 Flash. For complex prompts, if Gemini 3 Pro is enabled, it will use
+  Gemini 3 Pro; otherwise, it will use Gemini 2.5 Pro.
+- **Pro routing:** If you want to ensure your task is processed by the most
+  capable model, use `/model` and select **Pro**. Gemini CLI will prioritize the
+  most capable model available, including Gemini 3 Pro if it has been enabled.
+
+To learn more about selecting a model and routing, refer to
+[Gemini CLI Model Selection](../cli/model.md).
+
+## Need help?
+
+If you need help, we recommend searching for an existing
+[GitHub issue](https://github.com/google-gemini/gemini-cli/issues). If you
+cannot find a GitHub issue that matches your concern, you can
+[create a new issue](https://github.com/google-gemini/gemini-cli/issues/new/choose).
+For comments and feedback, consider opening a
+[GitHub discussion](https://github.com/google-gemini/gemini-cli/discussions).

docs/get-started/index.md

@@ -41,7 +41,7 @@ straightforward authentication method uses your existing Google account:
 4. Click on **Sign in**.
 
 For other authentication options and information, see
-[GeminI CLI Authentication Setup](./authentication.md).
+[Gemini CLI Authentication Setup](./authentication.md).
 
 ## Configure
 
@@ -63,3 +63,4 @@ To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md).
 
 - Find out more about [Gemini CLI's tools](../tools/index.md).
 - Review [Gemini CLI's commands](../cli/commands.md).
+- Learn how to [get started with Gemini 3](./gemini-3.md).

docs/ide-integration/index.md

@@ -4,8 +4,8 @@ Gemini CLI can integrate with your IDE to provide a more seamless and
 context-aware experience. This integration allows the CLI to understand your
 workspace better and enables powerful features like native in-editor diffing.
 
-Currently, the only supported IDE is
-[Visual Studio Code](https://code.visualstudio.com/) and other editors that
+Currently, the supported IDEs are [Antigravity](https://antigravity.google),
+[Visual Studio Code](https://code.visualstudio.com/), and other editors that
 support VS Code extensions. To build support for other editors, see the
 [IDE Companion Extension Spec](./ide-companion-spec.md).
 
@@ -191,7 +191,7 @@ messages and how to resolve them.
   - **Cause:** You are running Gemini CLI in a terminal or environment that is
     not a supported IDE.
   - **Solution:** Run Gemini CLI from the integrated terminal of a supported
-    IDE, like VS Code.
+    IDE, like Antigravity or VS Code.
 
 - **Message:**
   `No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.`

docs/index.md

@@ -28,12 +28,18 @@ This documentation is organized into the following sections:
 - **[Configuration](./get-started/configuration.md):** Information on
   configuring the CLI.
 - **[Examples](./get-started/examples.md):** Example usage of Gemini CLI.
+- **[Get started with Gemini 3](./get-started/gemini-3.md):** Learn how to
+  enable and use Gemini 3.
 
 ### CLI
 
 - **[CLI overview](./cli/index.md):** Overview of the command-line interface.
 - **[Commands](./cli/commands.md):** Description of available CLI commands.
 - **[Enterprise](./cli/enterprise.md):** Gemini CLI for enterprise.
+- **[Model Selection](./cli/model.md):** Select the model used to process your
+  commands with `/model`.
+- **[Settings](./cli/settings.md):** Configure various aspects of the CLI's
+  behavior and appearance with `/settings`.
 - **[Themes](./cli/themes.md):** Themes for Gemini CLI.
 - **[Token Caching](./cli/token-caching.md):** Token caching and optimization.
 - **[Tutorials](./cli/tutorials.md):** Tutorials for Gemini CLI.
@@ -50,6 +56,8 @@ This documentation is organized into the following sections:
 - **[Memport](./core/memport.md):** Using the Memory Import Processor.
 - **[Tools API](./core/tools-api.md):** Information on how the core manages and
   exposes tools.
+- **[Policy Engine](./core/policy-engine.md):** Use the Policy Engine for
+  fine-grained control over tool execution.
 
 ### Tools
 
@@ -58,8 +66,6 @@ This documentation is organized into the following sections:
 - **[File System Tools](./tools/file-system.md):** Documentation for the
   `read_file` and `write_file` tools.
 - **[MCP servers](./tools/mcp-server.md):** Using MCP servers with Gemini CLI.
-- **[Multi-File Read Tool](./tools/multi-file.md):** Documentation for the
-  `read_many_files` tool.
 - **[Shell Tool](./tools/shell.md):** Documentation for the `run_shell_command`
   tool.
 - **[Web Fetch Tool](./tools/web-fetch.md):** Documentation for the `web_fetch`
@@ -68,6 +74,7 @@ This documentation is organized into the following sections:
   `google_web_search` tool.
 - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory`
   tool.
+- **[Todo Tool](./tools/todos.md):** Documentation for the `write_todos` tool.
 
 ### Extensions
 

docs/integration-tests.md

@@ -56,15 +56,42 @@ To run a single test by its name, use the `--test-name-pattern` flag:
 npm run test:e2e -- --test-name-pattern "reads a file"
 ```
 
+### Regenerating model responses
+
+Some integration tests use faked out model responses, which may need to be
+regenerated from time to time as the implementations change.
+
+To regenerate these golden files, set the REGENERATE_MODEL_GOLDENS environment
+variable to "true" when running the tests, for example:
+
+**WARNING**: If running locally you should review these updated responses for
+any information about yourself or your system that gemini may have included in
+these responses.
+
+```bash
+REGENERATE_MODEL_GOLDENS="true" npm run test:e2e
+```
+
+**WARNING**: Make sure you run **await rig.cleanup()** at the end of your test,
+else the golden files will not be updated.
+
 ### Deflaking a test
 
 Before adding a **new** integration test, you should test it at least 5 times
-with the deflake script to make sure that it is not flaky.
+with the deflake script or workflow to make sure that it is not flaky.
+
+### Deflake script
 
 ```bash
 npm run deflake -- --runs=5 --command="npm run test:e2e -- -- --test-name-pattern '<your-new-test-name>'"
 ```
 
+#### Deflake Workflow
+
+```bash
+gh workflow run deflake.yml --ref <your-branch> -f test_name_pattern="<your-test-name-pattern>"
+```
+
 ### Running all tests
 
 To run the entire suite of integration tests, use the following command:

docs/local-development.md

@@ -0,0 +1,128 @@
+# Local Development Guide
+
+This guide provides instructions for setting up and using local development
+features, such as development tracing.
+
+## Development Tracing
+
+Development traces (dev traces) are OpenTelemetry (OTel) traces that help you
+debug your code by instrumenting interesting events like model calls, tool
+scheduler, tool calls, etc.
+
+Dev traces are verbose and are specifically meant for understanding agent
+behaviour and debugging issues. They are disabled by default.
+
+To enable dev traces, set the `GEMINI_DEV_TRACING=true` environment variable
+when running Gemini CLI.
+
+### Viewing Dev Traces
+
+You can view dev traces using either Jaeger or the Genkit Developer UI.
+
+#### Using Genkit
+
+Genkit provides a web-based UI for viewing traces and other telemetry data.
+
+1.  **Start the Genkit Telemetry Server:**
+
+    Run the following command to start the Genkit server:
+
+    ```bash
+    npm run telemetry -- --target=genkit
+    ```
+
+    The script will output the URL for the Genkit Developer UI, for example:
+
+    ```
+    Genkit Developer UI: http://localhost:4000
+    ```
+
+2.  **Run Gemini CLI with Dev Tracing:**
+
+    In a separate terminal, run your Gemini CLI command with the
+    `GEMINI_DEV_TRACING` environment variable:
+
+    ```bash
+    GEMINI_DEV_TRACING=true gemini
+    ```
+
+3.  **View the Traces:**
+
+    Open the Genkit Developer UI URL in your browser and navigate to the
+    **Traces** tab to view the traces.
+
+#### Using Jaeger
+
+You can view dev traces in the Jaeger UI. To get started, follow these steps:
+
+1.  **Start the telemetry collector:**
+
+    Run the following command in your terminal to download and start Jaeger and
+    an OTEL collector:
+
+    ```bash
+    npm run telemetry -- --target=local
+    ```
+
+    This command also configures your workspace for local telemetry and provides
+    a link to the Jaeger UI (usually `http://localhost:16686`).
+
+2.  **Run Gemini CLI with dev tracing:**
+
+    In a separate terminal, run your Gemini CLI command with the
+    `GEMINI_DEV_TRACING` environment variable:
+
+    ```bash
+    GEMINI_DEV_TRACING=true gemini
+    ```
+
+3.  **View the traces:**
+
+    After running your command, open the Jaeger UI link in your browser to view
+    the traces.
+
+For more detailed information on telemetry, see the
+[telemetry documentation](./cli/telemetry.md).
+
+### Instrumenting Code with Dev Traces
+
+You can add dev traces to your own code for more detailed instrumentation. This
+is useful for debugging and understanding the flow of execution.
+
+Use the `runInDevTraceSpan` function to wrap any section of code in a trace
+span.
+
+Here is a basic example:
+
+```typescript
+import { runInDevTraceSpan } from '@google/gemini-cli-core';
+
+await runInDevTraceSpan({ name: 'my-custom-span' }, async ({ metadata }) => {
+  // The `metadata` object allows you to record the input and output of the
+  // operation as well as other attributes.
+  metadata.input = { key: 'value' };
+  // Set custom attributes.
+  metadata.attributes['gen_ai.request.model'] = 'gemini-4.0-mega';
+
+  // Your code to be traced goes here
+  try {
+    const output = await somethingRisky();
+    metadata.output = output;
+    return output;
+  } catch (e) {
+    metadata.error = e;
+    throw e;
+  }
+});
+```
+
+In this example:
+
+- `name`: The name of the span, which will be displayed in the trace.
+- `metadata.input`: (Optional) An object containing the input data for the
+  traced operation.
+- `metadata.output`: (Optional) An object containing the output data from the
+  traced operation.
+- `metadata.attributes`: (Optional) A record of custom attributes to add to the
+  span.
+- `metadata.error`: (Optional) An error object to record if the operation fails.

docs/quota-and-pricing.md

@@ -8,8 +8,10 @@ account you use to authenticate.
 See [privacy and terms](./tos-privacy.md) for details on Privacy policy and
 Terms of Service.
 
-> [!NOTE] Published prices are list price; additional negotiated commercial
-> discounting may apply.
+> [!NOTE]
+>
+> Published prices are list price; additional negotiated commercial discounting
+> may apply.
 
 This article outlines the specific quotas and pricing applicable to the Gemini
 CLI when using different authentication methods.
@@ -82,10 +84,10 @@ Gemini CLI by upgrading to one of the following subscriptions:
   [Gemini Code Assist Quotas and Limits](https://developers.google.com/gemini-code-assist/resources/quotas)
 
 - [Purchase a Gemini Code Assist Subscription through Google Cloud ](https://cloud.google.com/gemini/docs/codeassist/overview)
-  by signing up in the Google Cloud console. Learn more at [Set up Gemini Code
-  Assist] (https://cloud.google.com/gemini/docs/discover/set-up-gemini) Quotas
-  and pricing are based on a fixed price subscription with assigned license
-  seats. For predictable costs, you can sign in with Google.
+  by signing up in the Google Cloud console. Learn more at
+  [Set up Gemini Code Assist](https://cloud.google.com/gemini/docs/discover/set-up-gemini)
+  Quotas and pricing are based on a fixed price subscription with assigned
+  license seats. For predictable costs, you can sign in with Google.
 
   This includes:
   - Gemini Code Assist Standard edition:

docs/release-confidence.md

@@ -0,0 +1,164 @@
+# Release Confidence Strategy
+
+This document outlines the strategy for gaining confidence in every release of
+the Gemini CLI. It serves as a checklist and quality gate for release manager to
+ensure we are shipping a high-quality product.
+
+## The Goal
+
+To answer the question, "Is this release _truly_ ready for our users?" with a
+high degree of confidence, based on a holistic evaluation of automated signals,
+manual verification, and data.
+
+## Level 1: Automated Gates (Must Pass)
+
+These are the baseline requirements. If any of these fail, the release is a
+no-go.
+
+### 1. CI/CD Health
+
+All workflows in `.github/workflows/ci.yml` must pass on the `main` branch (for
+nightly) or the release branch (for preview/stable).
+
+- **Platforms:** Tests must pass on **Linux and macOS**.
+  - _Note:_ Windows tests currently run with `continue-on-error: true`. While a
+    failure here doesn't block the release technically, it should be
+    investigated.
+- **Checks:**
+  - **Linting:** No linting errors (ESLint, Prettier, etc.).
+  - **Typechecking:** No TypeScript errors.
+  - **Unit Tests:** All unit tests in `packages/core` and `packages/cli` must
+    pass.
+  - **Build:** The project must build and bundle successfully.
+
+### 2. End-to-End (E2E) Tests
+
+All workflows in `.github/workflows/e2e.yml` must pass.
+
+- **Platforms:** **Linux, macOS and Windows**.
+- **Sandboxing:** Tests must pass with both `sandbox:none` and `sandbox:docker`
+  on Linux.
+
+### 3. Post-Deployment Smoke Tests
+
+After a release is published to npm, the `smoke-test.yml` workflow runs. This
+must pass to confirm the package is installable and the binary is executable.
+
+- **Command:** `npx -y @google/gemini-cli@<tag> --version` must return the
+  correct version without error.
+- **Platform:** Currently runs on `ubuntu-latest`.
+
+## Level 2: Manual Verification & Dogfooding
+
+Automated tests cannot catch everything, especially UX issues.
+
+### 1. Dogfooding via `preview` Tag
+
+The weekly release cadence promotes code from `main` -> `nightly` -> `preview`
+-> `stable`.
+
+- **Requirement:** The `preview` release must be used by maintainers for at
+  least **one week** before being promoted to `stable`.
+- **Action:** Maintainers should install the preview version locally:
+  ```bash
+  npm install -g @google/gemini-cli@preview
+  ```
+- **Goal:** To catch regressions and UX issues in day-to-day usage before they
+  reach the broad user base.
+
+### 2. Critical User Journey (CUJ) Checklist
+
+Before promoting a `preview` release to `stable`, a release manager must
+manually run through this checklist.
+
+- **Setup:**
+  - [ ] Uninstall any existing global version:
+        `npm uninstall -g @google/gemini-cli`
+  - [ ] Clear npx cache (optional but recommended): `npm cache clean --force`
+  - [ ] Install the preview version: `npm install -g @google/gemini-cli@preview`
+  - [ ] Verify version: `gemini --version`
+
+- **Authentication:**
+  - [ ] In interactive mode run `/auth` and verify all login flows work:
+    - [ ] Login With Google
+    - [ ] API Key
+    - [ ] Vertex AI
+
+- **Basic Prompting:**
+  - [ ] Run `gemini "Tell me a joke"` and verify a sensible response.
+  - [ ] Run in interactive mode: `gemini`. Ask a follow-up question to test
+        context.
+
+- **Piped Input:**
+  - [ ] Run `echo "Summarize this" | gemini` and verify it processes stdin.
+
+- **Context Management:**
+  - [ ] In interactive mode, use `@file` to add a local file to context. Ask a
+        question about it.
+
+- **Settings:**
+  - [ ] In interactive mode run `/settings` and make modifications
+  - [ ] Validate that setting is changed
+
+- **Function Calling:**
+  - [ ] In interactive mode, ask gemini to "create a file named hello.md with
+        the content 'hello world'" and verify the file is created correctly.
+
+If any of these CUJs fail, the release is a no-go until a patch is applied to
+the `preview` channel.
+
+### 3. Pre-Launch Bug Bash (Tier 1 & 2 Launches)
+
+For high-impact releases, an organized bug bash is required to ensure a higher
+level of quality and to catch issues across a wider range of environments and
+use cases.
+
+**Definition of Tiers:**
+
+- **Tier 1:** Industry-Moving News 🚀
+- **Tier 2:** Important News for Our Users 📣
+- **Tier 3:** Relevant, but Not Life-Changing 💡
+- **Tier 4:** Bug Fixes ⚒️
+
+**Requirement:**
+
+A bug bash must be scheduled at least **72 hours in advance** of any Tier 1 or
+Tier 2 launch.
+
+**Rule of Thumb:**
+
+A bug bash should be considered for any release that involves:
+
+- A blog post
+- Coordinated social media announcements
+- Media relations or press outreach
+- A "Turbo" launch event
+
+## Level 3: Telemetry & Data Review
+
+### Dashboard Health
+
+- [ ] Go to `go/gemini-cli-dash`.
+- [ ] Navigate to the "Tool Call" tab.
+- [ ] Validate that there are no spikes in errors for the release you would like
+      to promote.
+
+### Model Evaluation
+
+- [ ] Navigate to `go/gemini-cli-offline-evals-dash`.
+- [ ] Make sure that the release you want to promote's recurring run is within
+      average eval runs.
+
+## The "Go/No-Go" Decision
+
+Before triggering the `Release: Promote` workflow to move `preview` to `stable`:
+
+1.  [ ] **Level 1:** CI and E2E workflows are green for the commit corresponding
+        to the current `preview` tag.
+2.  [ ] **Level 2:** The `preview` version has been out for one week, and the
+        CUJ checklist has been completed successfully by a release manager. No
+        blocking issues have been reported.
+3.  [ ] **Level 3:** Dashboard Health and Model Evaluation checks have been
+        completed and show no regressions.
+
+If all checks pass, proceed with the promotion.

docs/releases.md

@@ -1,5 +1,27 @@
 # Gemini CLI Releases
 
+## `dev` vs `prod` environment
+
+Our release flows support both `dev` and `prod` environments.
+
+The `dev` environment pushes to a private Github-hosted NPM repository, with the
+package names beginning with `@google-gemini/**` instead of `@google/**`.
+
+The `prod` environment pushes to the public global NPM registry via Wombat
+Dressing Room, which is Google's system for managing NPM packages in the
+`@google/**` namespace. The packages are all named `@google/**`.
+
+More information can be found about these systems in the
+[maintainer repo guide](https://github.com/google-gemini/maintainers-gemini-cli/blob/main/npm.md)
+
+### Package scopes
+
+| Package    | `prod` (Wombat Dressing Room) | `dev` (Github Private NPM Repo)           |
+| ---------- | ----------------------------- | ----------------------------------------- |
+| CLI        | @google/gemini-cli            | @google-gemini/gemini-cli                 |
+| Core       | @google/gemini-cli-core       | @google-gemini/gemini-cli-core A2A Server |
+| A2A Server | @google/gemini-cli-a2a-server | @google-gemini/gemini-cli-a2a-server      |
+
 ## Release Cadence and Tags
 
 We will follow https://semver.org/ as closely as possible but will call out when
@@ -112,6 +134,10 @@ specific version from any branch, tag, or commit SHA.
       recommended for production releases.
     - **Skip GitHub Release**: Set to `true` to skip creating a GitHub release
       and create an npm release only.
+    - **Environment**: Select the appropriate environment. The `dev` environment
+      is intended for testing. The `prod` environment is intended for production
+      releases. `prod` is the default and will require authorization from a
+      release administrator.
 5.  Click **Run workflow**.
 
 The workflow will then proceed to test (if not skipped), build, and publish the
@@ -140,11 +166,15 @@ require a full release cycle.
     - **Channel**: The npm `dist-tag` to apply (e.g., `preview`, `stable`).
     - **Dry Run**: Leave as `true` to log the action without making changes, or
       set to `false` to perform the live tag change.
+    - **Environment**: Select the appropriate environment. The `dev` environment
+      is intended for testing. The `prod` environment is intended for production
+      releases. `prod` is the default and will require authorization from a
+      release administrator.
 5.  Click **Run workflow**.
 
-The workflow will then run `npm dist-tag add` for both the `@google/gemini-cli`
-and `@google/gemini-cli-core` packages, pointing the specified channel to the
-specified version.
+The workflow will then run `npm dist-tag add` for the appropriate `gemini-cli`,
+`gemini-cli-core` and `gemini-cli-a2a-server` packages, pointing the specified
+channel to the specified version.
 
 ## Patching
 

docs/sidebar.json

@@ -9,6 +9,10 @@
       {
         "label": "Architecture Overview",
         "slug": "docs/architecture"
+      },
+      {
+        "label": "Contribution Guide",
+        "slug": "docs/contributing"
       }
     ]
   },
@@ -19,6 +23,10 @@
         "label": "Gemini CLI Quickstart",
         "slug": "docs/get-started"
       },
+      {
+        "label": "Gemini 3 Pro on Gemini CLI",
+        "slug": "docs/get-started/gemini-3"
+      },
       {
         "label": "Authentication",
         "slug": "docs/get-started/authentication"
@@ -68,10 +76,18 @@
         "label": "Keyboard Shortcuts",
         "slug": "docs/cli/keyboard-shortcuts"
       },
+      {
+        "label": "Model Selection",
+        "slug": "docs/cli/model"
+      },
       {
         "label": "Sandbox",
         "slug": "docs/cli/sandbox"
       },
+      {
+        "label": "Settings",
+        "slug": "docs/cli/settings"
+      },
       {
         "label": "Telemetry",
         "slug": "docs/cli/telemetry"
@@ -112,6 +128,10 @@
       {
         "label": "Memory Import Processor",
         "slug": "docs/core/memport"
+      },
+      {
+        "label": "Policy Engine",
+        "slug": "docs/core/policy-engine"
       }
     ]
   },
@@ -126,10 +146,6 @@
         "label": "File System",
         "slug": "docs/tools/file-system"
       },
-      {
-        "label": "Multi-File Read",
-        "slug": "docs/tools/multi-file"
-      },
       {
         "label": "Shell",
         "slug": "docs/tools/shell"
@@ -146,6 +162,10 @@
         "label": "Memory",
         "slug": "docs/tools/memory"
       },
+      {
+        "label": "Todos",
+        "slug": "docs/tools/todos"
+      },
       {
         "label": "MCP Servers",
         "slug": "docs/tools/mcp-server"

docs/tools/index.md

@@ -82,10 +82,10 @@ Gemini CLI's built-in tools can be broadly categorized as follows:
   from URLs.
 - **[Web Search Tool](./web-search.md) (`google_web_search`):** For searching
   the web.
-- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized
-  tool for reading content from multiple files or directories.
 - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
   information across sessions.
+- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
+  requests.
 
 Additionally, these tools incorporate:
 

docs/tools/mcp-server.md

@@ -927,13 +927,13 @@ This is the default transport for running local servers.
 
 ```bash
 # Basic syntax
-gemini mcp add <name> <command> [args...]
+gemini mcp add [options] <name> <command> [args...]
 
 # Example: Adding a local server
-gemini mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
+gemini mcp add -e API_KEY=123 -e DEBUG=true my-stdio-server /path/to/server arg1 arg2 arg3
 
 # Example: Adding a local python server
-gemini mcp add python-server python server.py --port 8080
+gemini mcp add python-server python server.py -- --server-arg my-value
 ```
 
 #### Adding an HTTP server
@@ -948,7 +948,7 @@ gemini mcp add --transport http <name> <url>
 gemini mcp add --transport http http-server https://api.example.com/mcp/
 
 # Example: Adding an HTTP server with an authentication header
-gemini mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"
+gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/
 ```
 
 #### Adding an SSE server
@@ -963,13 +963,14 @@ gemini mcp add --transport sse <name> <url>
 gemini mcp add --transport sse sse-server https://api.example.com/sse/
 
 # Example: Adding an SSE server with an authentication header
-gemini mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"
+gemini mcp add --transport sse --header "Authorization: Bearer abc123" secure-sse https://api.example.com/sse/
 ```
 
 ### Listing Servers (`gemini mcp list`)
 
 To view all MCP servers currently configured, use the `list` command. It
-displays each server's name, configuration details, and connection status.
+displays each server's name, configuration details, and connection status. This
+command has no flags.
 
 **Command:**
 
@@ -996,6 +997,10 @@ server's name.
 gemini mcp remove <name>
 ```
 
+**Options (Flags):**
+
+- `-s, --scope`: Configuration scope (user or project). [default: "project"]
+
 **Example:**
 
 ```bash

docs/tools/multi-file.md

@@ -1,109 +0,0 @@
-# Multi File Read Tool (`read_many_files`)
-
-This document describes the `read_many_files` tool for the Gemini CLI.
-
-## Description
-
-Use `read_many_files` to read content from multiple files specified by paths or
-glob patterns. The behavior of this tool depends on the provided files:
-
-- For text files, this tool concatenates their content into a single string.
-- For image (e.g., PNG, JPEG), PDF, audio (MP3, WAV), and video (MP4, MOV)
-  files, it reads and returns them as base64-encoded data, provided they are
-  explicitly requested by name or extension.
-
-`read_many_files` can be used to perform tasks such as getting an overview of a
-codebase, finding where specific functionality is implemented, reviewing
-documentation, or gathering context from multiple configuration files.
-
-**Note:** `read_many_files` looks for files following the provided paths or glob
-patterns. A directory path such as `"/docs"` will return an empty result; the
-tool requires a pattern such as `"/docs/*"` or `"/docs/*.md"` to identify the
-relevant files.
-
-### Arguments
-
-`read_many_files` takes the following arguments:
-
-- `paths` (list[string], required): An array of glob patterns or paths relative
-  to the tool's target directory (e.g., `["src/**/*.ts"]`,
-  `["README.md", "docs/*", "assets/logo.png"]`).
-- `exclude` (list[string], optional): Glob patterns for files/directories to
-  exclude (e.g., `["**/*.log", "temp/"]`). These are added to default excludes
-  if `useDefaultExcludes` is true.
-- `include` (list[string], optional): Additional glob patterns to include. These
-  are merged with `paths` (e.g., `["*.test.ts"]` to specifically add test files
-  if they were broadly excluded, or `["images/*.jpg"]` to include specific image
-  types).
-- `recursive` (boolean, optional): Whether to search recursively. This is
-  primarily controlled by `**` in glob patterns. Defaults to `true`.
-- `useDefaultExcludes` (boolean, optional): Whether to apply a list of default
-  exclusion patterns (e.g., `node_modules`, `.git`, non image/pdf binary files).
-  Defaults to `true`.
-- `respect_git_ignore` (boolean, optional): Whether to respect .gitignore
-  patterns when finding files. Defaults to true.
-
-## How to use `read_many_files` with the Gemini CLI
-
-`read_many_files` searches for files matching the provided `paths` and `include`
-patterns, while respecting `exclude` patterns and default excludes (if enabled).
-
-- For text files: it reads the content of each matched file (attempting to skip
-  binary files not explicitly requested as image/PDF) and concatenates it into a
-  single string, with a separator `--- {filePath} ---` between the content of
-  each file. Uses UTF-8 encoding by default.
-- The tool inserts a `--- End of content ---` after the last file.
-- For image and PDF files: if explicitly requested by name or extension (e.g.,
-  `paths: ["logo.png"]` or `include: ["*.pdf"]`), the tool reads the file and
-  returns its content as a base64 encoded string.
-- The tool attempts to detect and skip other binary files (those not matching
-  common image/PDF types or not explicitly requested) by checking for null bytes
-  in their initial content.
-
-Usage:
-
-```
-read_many_files(paths=["Your files or paths here."], include=["Additional files to include."], exclude=["Files to exclude."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true)
-```
-
-## `read_many_files` examples
-
-Read all TypeScript files in the `src` directory:
-
-```
-read_many_files(paths=["src/**/*.ts"])
-```
-
-Read the main README, all Markdown files in the `docs` directory, and a specific
-logo image, excluding a specific file:
-
-```
-read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"])
-```
-
-Read all JavaScript files but explicitly include test files and all JPEGs in an
-`images` folder:
-
-```
-read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False)
-```
-
-## Important notes
-
-- **Binary file handling:**
-  - **Image/PDF/Audio/Video files:** The tool can read common image types (PNG,
-    JPEG, etc.), PDF, audio (mp3, wav), and video (mp4, mov) files, returning
-    them as base64 encoded data. These files _must_ be explicitly targeted by
-    the `paths` or `include` patterns (e.g., by specifying the exact filename
-    like `video.mp4` or a pattern like `*.mov`).
-  - **Other binary files:** The tool attempts to detect and skip other types of
-    binary files by examining their initial content for null bytes. The tool
-    excludes these files from its output.
-- **Performance:** Reading a very large number of files or very large individual
-  files can be resource-intensive.
-- **Path specificity:** Ensure paths and glob patterns are correctly specified
-  relative to the tool's target directory. For image/PDF files, ensure the
-  patterns are specific enough to include them.
-- **Default excludes:** Be aware of the default exclusion patterns (like
-  `node_modules`, `.git`) and use `useDefaultExcludes=False` if you need to
-  override them, but do so cautiously.

docs/tools/shell.md

@@ -10,8 +10,9 @@ command, including interactive commands that require user input (e.g., `vim`,
 `git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to
 `true`.
 
-On Windows, commands are executed with `cmd.exe /c`. On other platforms, they
-are executed with `bash -c`.
+On Windows, commands are executed with `powershell.exe -NoProfile -Command`
+(unless you explicitly point `ComSpec` at another shell). On other platforms,
+they are executed with `bash -c`.
 
 ### Arguments
 

docs/tools/todos.md

@@ -0,0 +1,57 @@
+# Todo Tool (`write_todos`)
+
+This document describes the `write_todos` tool for the Gemini CLI.
+
+## Description
+
+The `write_todos` tool allows the Gemini agent to create and manage a list of
+subtasks for complex user requests. This provides you, the user, with greater
+visibility into the agent's plan and its current progress. It also helps with
+alignment where the agent is less likely to lose track of its current goal.
+
+### Arguments
+
+`write_todos` takes one argument:
+
+- `todos` (array of objects, required): The complete list of todo items. This
+  replaces the existing list. Each item includes:
+  - `description` (string): The task description.
+  - `status` (string): The current status (`pending`, `in_progress`,
+    `completed`, or `cancelled`).
+
+## Behavior
+
+The agent uses this tool to break down complex multi-step requests into a clear
+plan.
+
+- **Progress Tracking:** The agent updates this list as it works, marking tasks
+  as `completed` when done.
+- **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
+  cancelled.
+
+When active, the current `in_progress` task is displayed above the input box,
+keeping you informed of the immediate action. You can toggle the full view of
+the todo list at any time by pressing `Ctrl+T`.
+
+Usage example (internal representation):
+
+```javascript
+write_todos({
+  todos: [
+    { description: 'Initialize new React project', status: 'completed' },
+    { description: 'Implement state management', status: 'in_progress' },
+    { description: 'Create API service', status: 'pending' },
+  ],
+});
+```
+
+## Important notes
+
+- **Enabling:** This tool is enabled by default. You can disable it in your
+  `settings.json` file by setting `"useWriteTodos": false`.
+
+- **Intended Use:** This tool is primarily used by the agent for complex,
+  multi-turn tasks. It is generally not used for simple, single-turn questions.

esbuild.config.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { writeFileSync } from 'node:fs';
+import { wasmLoader } from 'esbuild-plugin-wasm';
 
 let esbuild;
 try {
@@ -22,6 +23,37 @@ const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
 const pkg = require(path.resolve(__dirname, 'package.json'));
 
+function createWasmPlugins() {
+  const wasmBinaryPlugin = {
+    name: 'wasm-binary',
+    setup(build) {
+      build.onResolve({ filter: /\.wasm\?binary$/ }, (args) => {
+        const specifier = args.path.replace(/\?binary$/, '');
+        const resolveDir = args.resolveDir || '';
+        const isBareSpecifier =
+          !path.isAbsolute(specifier) &&
+          !specifier.startsWith('./') &&
+          !specifier.startsWith('../');
+
+        let resolvedPath;
+        if (isBareSpecifier) {
+          resolvedPath = require.resolve(specifier, {
+            paths: resolveDir ? [resolveDir, __dirname] : [__dirname],
+          });
+        } else {
+          resolvedPath = path.isAbsolute(specifier)
+            ? specifier
+            : path.join(resolveDir, specifier);
+        }
+
+        return { path: resolvedPath, namespace: 'wasm-embedded' };
+      });
+    },
+  };
+
+  return [wasmBinaryPlugin, wasmLoader({ mode: 'embedded' })];
+}
+
 const external = [
   '@lydell/node-pty',
   'node-pty',
@@ -51,6 +83,7 @@ const cliConfig = {
   define: {
     'process.env.CLI_VERSION': JSON.stringify(pkg.version),
   },
+  plugins: createWasmPlugins(),
   alias: {
     'is-in-ci': path.resolve(__dirname, 'packages/cli/src/patches/is-in-ci.ts'),
   },
@@ -67,6 +100,7 @@ const a2aServerConfig = {
   define: {
     'process.env.CLI_VERSION': JSON.stringify(pkg.version),
   },
+  plugins: createWasmPlugins(),
 };
 
 Promise.allSettled([

eslint.config.js

@@ -161,6 +161,31 @@ export default tseslint.config(
       'default-case': 'error',
     },
   },
+  {
+    // Prevent self-imports in packages
+    files: ['packages/core/src/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          name: '@google/gemini-cli-core',
+          message: 'Please use relative imports within the @google/gemini-cli-core package.',
+        },
+      ],
+    },
+  },
+  {
+    files: ['packages/cli/src/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          name: '@google/gemini-cli',
+          message: 'Please use relative imports within the @google/gemini-cli package.',
+        },
+      ],
+    },
+  },
   {
     files: ['packages/*/src/**/*.test.{ts,tsx}'],
     plugins: {

hello/commands/fs/grep-code.toml

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

hello/gemini-extension.json

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

integration-tests/context-compress-interactive.compress-failure.responses

@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"thought":true,"text":"**Observing Initial Conditions**\n\nI'm currently focused on the initial context. I've taken note of the provided date, OS, and working directory. I'm also carefully examining the file structure presented within the current working directory. It's helping me understand the starting point for further analysis.\n\n\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12270,"totalTokenCount":12316,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12270}],"thoughtsTokenCount":46}},{"candidates":[{"content":{"parts":[{"thought":true,"text":"**Assessing User Intent**\n\nI'm now shifting my focus. I've successfully registered the provided data and file structure. My current task is to understand the user's ultimate goal, given the information provided. The \"Hello.\" command is straightforward, but I'm checking if there's an underlying objective.\n\n\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12270,"totalTokenCount":12341,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12270}],"thoughtsTokenCount":71}},{"candidates":[{"content":{"parts":[{"thoughtSignature":"CiQB0e2Kb3dRh+BYdbZvmulSN2Pwbc75DfQOT3H4EN0rn039hoMKfwHR7YpvvyqNKoxXAiCbYw3gbcTr/+pegUpgnsIrt8oQPMytFMjKSsMyshfygc21T2MkyuI6Q5I/fNCcHROWexdZnIeppVCDB2TarN4LGW4T9Yci6n/ynMMFT2xc2/vyHpkDgRM7avhMElnBhuxAY+e4TpxkZIncGWCEHP1TouoKpgEB0e2Kb8Xpwm0hiKhPt2ZLizpxjk+CVtcbnlgv69xo5VsuQ+iNyrVGBGRwNx+eTeNGdGpn6e73WOCZeP91FwOZe7URyL12IA6E6gYWqw0kXJR4hO4p6Lwv49E3+FRiG2C4OKDF8LF5XorYyCHSgBFT1/RUAVj81GDTx1xxtmYKN3xq8Ri+HsPbqU/FM/jtNZKkXXAtufw2Bmw8lJfmugENIv/TQI7xCo8BAdHtim8KgAXJfZ7ASfutVLKTylQeaslyB/SmcHJ0ZiNr5j8WP1prZdb6XnZZ1ZNbhjxUf/ymoxHKGvtTPBgLE9azMj8Lx/k0clhd2a+wNsiIqW9qCzlVah0tBMytpQUjIDtQe9Hj4LLUprF9PUe/xJkj000Z0ZzsgFm2ncdTWZTdkhCQDpyETVAxdE+oklwKJAHR7YpvUjSkD6KwY1gLrOsHKy0UNfn2lMbxjVetKNMVBRqsTg==","text":"Hello."}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12270,"totalTokenCount":12341,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12270}],"thoughtsTokenCount":71}}]}
+{"method":"generateContent","response":{"candidates":[{"content":{"parts":[{"text":"<state_snapshot>\n    <overall_goal>\n        <!-- The user has not yet specified a goal. -->\n    </overall_goal>\n\n    <key_knowledge>\n       - OS: linux\n        - Date: Friday, October 24, 2025\n    </key_knowledge>\n\n    <file_system_state>\n       - OBSERVED: The directory contains `telemetry.log` and a `.gemini/` directory.\n        - OBSERVED: The `.gemini/` directory contains `settings.json` and `settings.json.orig`.\n    </file_system_state>\n\n    <recent_actions>\n        - The user initiated the chat.\n    </recent_actions>\n\n    <current_plan>\n        1. [TODO] Await the user's first instruction to formulate a plan.\n    </current_plan>\n</state_snapshot>"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":983,"candidatesTokenCount":299,"totalTokenCount":1637,"promptTokensDetails":[{"modality":"TEXT","tokenCount":983}],"thoughtsTokenCount":355}}}

integration-tests/context-compress-interactive.compress.responses

@@ -0,0 +1,3 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"thought":true,"text":"**Generating a Story**\n\nI've crafted the robot story. The narrative is complete and meets the length requirement. Now, I'm getting ready to use the `write_file` tool to save it. I'm choosing the filename `robot_story.txt` as a default.\n\n\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12282,"totalTokenCount":12352,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"thoughtsTokenCount":70}},{"candidates":[{"finishReason":"MALFORMED_FUNCTION_CALL","index":0}],"usageMetadata":{"promptTokenCount":12282,"totalTokenCount":12282,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"thought":true,"text":"**Drafting the Narrative**\n\nI'm currently focused on the narrative's central conflict. I'm aiming for a compelling story about a robot and am working to keep the word count tight. The \"THE _END.\" conclusion is proving challenging to integrate organically. I need to make the ending feel natural and satisfying.\n\n\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12282,"totalTokenCount":12326,"cachedContentTokenCount":11883,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":11883}],"thoughtsTokenCount":44}},{"candidates":[{"content":{"parts":[{"thoughtSignature":"CikB0e2Kb7zkpgRyJXXNt6ykO/+FoOglhrKxjLgoESrgafzIZak2Ofxo1gpaAdHtim9aG7MvpXlIg+n2zgmcDBWOPXtvQHxhE9k8pR+DO8i2jIe3tMWLxdN944XpUlR9vaNmVdtSRMKr4MhB/t1R3WSWR3QYhk7MEQxnjYR7cv/pR9viwZyFCoYBAdHtim/xKmMl/S+U8p+p9848q4agsL/STufluXewPqL3uJSinZbN0Z4jTYfMzXKldhDYIonvw3Crn/Y11oAjnT656Sx0kkKtavAXbiU/WsGyDxZbNhLofnJGQxruljPGztxkKawz1cTiQnddnQRfLddhy+3iJIOSh6ZpYq9uGHz3PzVkUuQ=","text":"Unit 734 whirred, its optical sensors scanning the desolate junkyard. For years, its purpose had been clear: compress refuse, maintain order. But today, a glint of tarnished silver beneath a rusted hull"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12282,"candidatesTokenCount":47,"totalTokenCount":12373,"cachedContentTokenCount":11883,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":11883}],"thoughtsTokenCount":44}},{"candidates":[{"content":{"parts":[{"text":" caught its attention. It was a discarded music box, its delicate gears jammed, a faint, melancholic tune trapped within.\n\n734 usually crushed, never salvaged. Yet, a new directive flickered in its circuits – curiosity."}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12282,"candidatesTokenCount":95,"totalTokenCount":12421,"cachedContentTokenCount":11883,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":11883}],"thoughtsTokenCount":44}},{"candidates":[{"content":{"parts":[{"text":" With surprising gentleness for its formidable pincers, it retrieved the box. Back in its monochrome workshop, it meticulously cleaned and repaired. Each tiny spring, each worn tooth, became a puzzle.\n\nHours later, a soft, ethereal melody filled the clang"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12282,"candidatesTokenCount":146,"totalTokenCount":12472,"cachedContentTokenCount":11883,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":11883}],"thoughtsTokenCount":44}},{"candidates":[{"content":{"parts":[{"text":"orous space. The music box sang. 734 felt a strange, new sensation – a warmth in its core processors, a hum of contentment. Its existence, once solely utilitarian, now held a note of beauty, a hint of something more than"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12282,"candidatesTokenCount":197,"totalTokenCount":12523,"cachedContentTokenCount":11883,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":11883}],"thoughtsTokenCount":44}},{"candidates":[{"content":{"parts":[{"text":" just compression. It had fixed a broken song, and in doing so, had found a different kind of purpose. THE_END."}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12282,"candidatesTokenCount":224,"totalTokenCount":12550,"cachedContentTokenCount":11883,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12282}],"cacheTokensDetails":[{"modality":"TEXT","tokenCount":11883}],"thoughtsTokenCount":44}}]}
+{"method":"generateContent","response":{"candidates":[{"content":{"parts":[{"text":"scratchpad\nThe user's overall goal was to write a 200-word story about a robot, ending with \"THE_END.\". The agent successfully completed this task.\n\nSince the task is complete, the snapshot should reflect that the goal has been achieved and there are no further actions planned regarding the story.\n\nLet's break down the required sections for the snapshot:\n\n1.  **Overall Goal**: The initial goal was to write a story. This has been completed.\n2.  **Key Knowledge**: No specific key knowledge was provided or discovered during this simple interaction beyond the prompt's constraints.\n3.  **File System State**: No files were read, modified, or created by the agent relevant to the task. The initial file system state was merely provided for context.\n4.  **Recent Actions**: The agent wrote the story.\n5.  **Current Plan**: The plan was to write the story, which is now done. Therefore, the plan should indicate completion."},{"text":"<state_snapshot>\n    <overall_goal>\n        Write a 200-word story about a robot, ending with \"THE_END.\".\n    </overall_goal>\n\n    <key_knowledge>\n        - The story must be approximately 200 words.\n        - The story must end with the exact phrase \"THE_END.\"\n    </key_knowledge>\n\n    <file_system_state>\n        <!-- No relevant file system interactions occurred during this task. -->\n    </file_system_state>\n\n    <recent_actions>\n        - Generated a 200-word story about a robot, successfully ending it with \"THE_END.\".\n    </recent_actions>\n\n    <current_plan>\n        1. [DONE] Write a 200-word story about a robot.\n        2. [DONE] Ensure the story ends with the exact text \"THE_END.\".\n    </current_plan>\n</state_snapshot>"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":1223,"candidatesTokenCount":424,"totalTokenCount":1647,"promptTokensDetails":[{"modality":"TEXT","tokenCount":1223}]}}}

integration-tests/context-compress-interactive.test.ts

@@ -6,8 +6,9 @@
 
 import { expect, describe, it, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
+import { join } from 'node:path';
 
-describe.skip('Interactive Mode', () => {
+describe('Interactive Mode', () => {
   let rig: TestRig;
 
   beforeEach(() => {
@@ -18,40 +19,93 @@ describe.skip('Interactive Mode', () => {
     await rig.cleanup();
   });
 
-  // TODO(#11062): Make this test reliable by not using the actual Gemini model
-  it.skip('should trigger chat compression with /compress command', async () => {
-    await rig.setup('interactive-compress-test');
+  it('should trigger chat compression with /compress command', async () => {
+    await rig.setup('interactive-compress-success', {
+      fakeResponsesPath: join(
+        import.meta.dirname,
+        'context-compress-interactive.compress.responses',
+      ),
+    });
 
     const run = await rig.runInteractive();
 
-    const longPrompt =
-      'Dont do anything except returning a 1000 token long paragraph with the <name of the scientist who discovered theory of relativity> at the end to indicate end of response. This is a moderately long sentence.';
-
-    await run.sendKeys(longPrompt);
+    await run.sendKeys(
+      'Write a 200 word story about a robot. The story MUST end with the text THE_END followed by a period.',
+    );
     await run.sendKeys('\r');
 
-    await run.expectText('einstein', 25000);
+    // Wait for the specific end marker.
+    await run.expectText('THE_END.', 30000);
 
     await run.type('/compress');
-    await run.sendKeys('\r');
+    await run.type('\r');
 
     const foundEvent = await rig.waitForTelemetryEvent(
       'chat_compression',
-      90000,
+      25000,
     );
     expect(foundEvent, 'chat_compression telemetry event was not found').toBe(
       true,
     );
+
+    await run.expectText('Chat history compressed', 5000);
   });
 
-  //TODO - https://github.com/google-gemini/gemini-cli/issues/10769
+  // TODO: Context compression is broken and doesn't include the system
+  // instructions or tool counts, so it thinks compression is beneficial when
+  // it is in fact not.
   it.skip('should handle compression failure on token inflation', async () => {
-    await rig.setup('interactive-compress-test');
+    await rig.setup('interactive-compress-failure', {
+      fakeResponsesPath: join(
+        import.meta.dirname,
+        'context-compress-interactive.compress-failure.responses',
+      ),
+    });
 
     const run = await rig.runInteractive();
 
+    await run.type('Respond with exactly "Hello" followed by a period');
+    await run.type('\r');
+
+    await run.expectText('Hello.', 25000);
+
     await run.type('/compress');
-    await run.sendKeys('\r');
+    await run.type('\r');
     await run.expectText('compression was not beneficial', 25000);
+
+    // Verify no telemetry event is logged for NOOP
+    const foundEvent = await rig.waitForTelemetryEvent(
+      'chat_compression',
+      5000,
+    );
+    expect(
+      foundEvent,
+      'chat_compression telemetry event should be found for failures',
+    ).toBe(true);
+  });
+
+  it('should handle /compress command on empty history', async () => {
+    rig.setup('interactive-compress-empty', {
+      fakeResponsesPath: join(
+        import.meta.dirname,
+        'context-compress-interactive.compress-empty.responses',
+      ),
+    });
+
+    const run = await rig.runInteractive();
+    await run.type('/compress');
+    await run.type('\r');
+
+    await run.expectText('Nothing to compress.', 5000);
+
+    // Verify no telemetry event is logged for NOOP
+    const foundEvent = await rig.waitForTelemetryEvent(
+      'chat_compression',
+      5000, // Short timeout as we expect it not to happen
+    );
+    expect(
+      foundEvent,
+      'chat_compression telemetry event should not be found for NOOP',
+    ).toBe(false);
   });
 });

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

@@ -8,10 +8,12 @@ import { describe, it, expect } from 'vitest';
 import * as os from 'node:os';
 import { TestRig } from './test-helper.js';
 
-describe.skip('Ctrl+C exit', () => {
+describe('Ctrl+C exit', () => {
   it('should exit gracefully on second Ctrl+C', async () => {
     const rig = new TestRig();
-    await rig.setup('should exit gracefully on second Ctrl+C');
+    await rig.setup('should exit gracefully on second Ctrl+C', {
+      settings: { tools: { useRipgrep: false } },
+    });
 
     const run = await rig.runInteractive();
 

integration-tests/extensions-install.test.ts

@@ -4,49 +4,50 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { expect, test } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { TestRig } from './test-helper.js';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 const extension = `{
-  "name": "test-extension",
+  "name": "test-extension-install",
   "version": "0.0.1"
 }`;
 
 const extensionUpdate = `{
-  "name": "test-extension",
+  "name": "test-extension-install",
   "version": "0.0.2"
 }`;
 
-test('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);
-  try {
-    await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
-  } catch {
-    /* empty */
-  }
+describe('extension install', () => {
+  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);
+    try {
+      const result = await rig.runCommand(
+        ['extensions', 'install', `${rig.testDir!}`],
+        { stdin: 'y\n' },
+      );
+      expect(result).toContain('test-extension-install');
 
-  const result = await rig.runCommand(
-    ['extensions', 'install', `${rig.testDir!}`],
-    { stdin: 'y\n' },
-  );
-  expect(result).toContain('test-extension');
-
-  const listResult = await rig.runCommand(['extensions', 'list']);
-  expect(listResult).toContain('test-extension');
-  writeFileSync(testServerPath, extensionUpdate);
-  const updateResult = await rig.runCommand([
-    'extensions',
-    'update',
-    `test-extension`,
-  ]);
-  expect(updateResult).toContain('0.0.2');
-
-  await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
-
-  await rig.cleanup();
+      const listResult = await rig.runCommand(['extensions', 'list']);
+      expect(listResult).toContain('test-extension-install');
+      writeFileSync(testServerPath, extensionUpdate);
+      const updateResult = await rig.runCommand([
+        'extensions',
+        'update',
+        `test-extension-install`,
+      ]);
+      expect(updateResult).toContain('0.0.2');
+    } finally {
+      await rig.runCommand([
+        'extensions',
+        'uninstall',
+        'test-extension-install',
+      ]);
+      await rig.cleanup();
+    }
+  });
 });

integration-tests/extensions-reload.test.ts

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { expect, it, describe } from 'vitest';
+import { TestRig } from './test-helper.js';
+import { TestMcpServer } from './test-mcp-server.js';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { safeJsonStringify } from '@google/gemini-cli-core/src/utils/safeJsonStringify.js';
+import { env } from 'node:process';
+import { platform } from 'node:os';
+
+const itIf = (condition: boolean) => (condition ? it : it.skip);
+
+describe('extension reloading', () => {
+  const sandboxEnv = env['GEMINI_SANDBOX'];
+
+  // Fails in sandbox mode, can't check for local extension updates.
+  itIf((!sandboxEnv || sandboxEnv === 'false') && platform() !== 'win32')(
+    'installs a local extension, updates it, checks it was reloaded properly',
+    async () => {
+      const serverA = new TestMcpServer();
+      const portA = await serverA.start({
+        hello: () => ({ content: [{ type: 'text', text: 'world' }] }),
+      });
+      const extension = {
+        name: 'test-extension',
+        version: '0.0.1',
+        mcpServers: {
+          'test-server': {
+            httpUrl: `http://localhost:${portA}/mcp`,
+          },
+        },
+      };
+
+      const rig = new TestRig();
+      rig.setup('extension reload test', {
+        settings: {
+          experimental: { extensionReloading: true },
+        },
+      });
+      const testServerPath = join(rig.testDir!, 'gemini-extension.json');
+      writeFileSync(testServerPath, safeJsonStringify(extension, 2));
+      // defensive cleanup from previous tests.
+      try {
+        await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
+      } catch {
+        /* empty */
+      }
+
+      const result = await rig.runCommand(
+        ['extensions', 'install', `${rig.testDir!}`],
+        { stdin: 'y\n' },
+      );
+      expect(result).toContain('test-extension');
+
+      // Now create the update, but its not installed yet
+      const serverB = new TestMcpServer();
+      const portB = await serverB.start({
+        goodbye: () => ({ content: [{ type: 'text', text: 'world' }] }),
+      });
+      extension.version = '0.0.2';
+      extension.mcpServers['test-server'].httpUrl =
+        `http://localhost:${portB}/mcp`;
+      writeFileSync(testServerPath, safeJsonStringify(extension, 2));
+
+      // Start the CLI.
+      const run = await rig.runInteractive('--debug');
+      await run.expectText('You have 1 extension with an update available');
+      // See the outdated extension
+      await run.sendText('/extensions list');
+      await run.type('\r');
+      await run.expectText(
+        'test-extension (v0.0.1) - active (update available)',
+      );
+      await run.sendText('/mcp list');
+      await run.type('\r');
+      await run.expectText(
+        'test-server (from test-extension) - Ready (1 tool)',
+      );
+      await run.expectText('- hello');
+
+      // Update the extension, expect the list to update, and mcp servers as well.
+      await run.sendKeys('/extensions update test-extension');
+      await run.expectText('/extensions update test-extension');
+      await run.sendKeys('\r');
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      await run.sendKeys('\r');
+      await run.expectText(
+        ` * test-server (remote): http://localhost:${portB}/mcp`,
+      );
+      await run.type('\r'); // consent
+      await run.expectText(
+        'Extension "test-extension" successfully updated: 0.0.1 → 0.0.2',
+      );
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      await run.sendText('/extensions list');
+      await run.type('\r');
+      await run.expectText('test-extension (v0.0.2) - active (updated)');
+      await run.sendText('/mcp list');
+      await run.type('\r');
+      await run.expectText(
+        'test-server (from test-extension) - Ready (1 tool)',
+      );
+      await run.expectText('- goodbye');
+      await run.sendText('/quit');
+      await run.sendKeys('\r');
+
+      // Clean things up.
+      await serverA.stop();
+      await serverB.stop();
+      await rig.runCommand(['extensions', 'uninstall', 'test-extension']);
+      await rig.cleanup();
+    },
+  );
+});

integration-tests/file-system-interactive.test.ts

@@ -7,7 +7,7 @@
 import { expect, describe, it, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
 
-describe.skip('Interactive file system', () => {
+describe('Interactive file system', () => {
   let rig: TestRig;
 
   beforeEach(() => {
@@ -20,7 +20,16 @@ describe.skip('Interactive file system', () => {
 
   it('should perform a read-then-write sequence', async () => {
     const fileName = 'version.txt';
-    rig.setup('interactive-read-then-write');
+    await rig.setup('interactive-read-then-write', {
+      settings: {
+        security: {
+          auth: {
+            selectedType: 'gemini-api-key',
+          },
+          disableYoloMode: false,
+        },
+      },
+    });
     rig.createFile(fileName, '1.0.0');
 
     const run = await rig.runInteractive();
@@ -33,16 +42,19 @@ describe.skip('Interactive file system', () => {
     const readCall = await rig.waitForToolCall('read_file', 30000);
     expect(readCall, 'Expected to find a read_file tool call').toBe(true);
 
-    await run.expectText('1.0.0', 30000);
-
     // Step 2: Write the file
     const writePrompt = `now change the version to 1.0.1 in the file`;
     await run.type(writePrompt);
     await run.sendKeys('\r');
 
-    await rig.expectToolCallSuccess(['write_file', 'replace'], 30000);
+    // Check tool calls made with right args
+    await rig.expectToolCallSuccess(
+      ['write_file', 'replace'],
+      30000,
+      (args) => args.includes('1.0.1') && args.includes(fileName),
+    );
 
-    const newFileContent = rig.readFile(fileName);
-    expect(newFileContent).toBe('1.0.1');
+    // Wait for telemetry to flush and file system to sync, especially in sandboxed environments
+    await rig.waitForTelemetryReady();
   });
 });

integration-tests/file-system.test.ts

@@ -98,7 +98,9 @@ describe('file-system', () => {
     await rig.setup('should correctly handle file paths with spaces');
     const fileName = 'my test file.txt';
 
-    const result = await rig.run(`write "hello" to "${fileName}"`);
+    const result = await rig.run(
+      `write "hello" to "${fileName}" and then stop. Do not perform any other actions.`,
+    );
 
     const foundToolCall = await rig.waitForToolCall('write_file');
     if (!foundToolCall) {
@@ -150,44 +152,53 @@ describe('file-system', () => {
 
   it.skip('should replace multiple instances of a string', async () => {
     const rig = new TestRig();
-    await rig.setup('should replace multiple instances of a string');
+    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(
-      `replace "test line" with "new line" in ${fileName}`,
+      `rewrite the file ${fileName} to replace all instances of "test line" with "new line"`,
     );
 
-    const foundToolCall = await rig.waitForAnyToolCall([
-      'replace',
-      'write_file',
-    ]);
+    const validTools = ['write_file', 'edit'];
+    const foundToolCall = await rig.waitForAnyToolCall(validTools);
     if (!foundToolCall) {
-      printDebugInfo(rig, result);
+      printDebugInfo(rig, result, {
+        'Tool call found': foundToolCall,
+        'Tool logs': rig.readToolLogs(),
+      });
     }
     expect(
       foundToolCall,
-      'Expected to find a replace or write_file tool call',
+      `Expected to find one of ${validTools.join(', ')} tool calls`,
     ).toBeTruthy();
 
     const toolLogs = rig.readToolLogs();
     const successfulEdit = toolLogs.some(
       (log) =>
-        (log.toolRequest.name === 'replace' ||
-          log.toolRequest.name === 'write_file') &&
-        log.toolRequest.success,
+        validTools.includes(log.toolRequest.name) && log.toolRequest.success,
     );
     if (!successfulEdit) {
       console.error(
-        'Expected a successful edit tool call, but none was found.',
+        `Expected a successful edit tool call (${validTools.join(', ')}), but none was found.`,
       );
       printDebugInfo(rig, result);
     }
-    expect(successfulEdit, 'Expected a successful edit tool call').toBeTruthy();
+    expect(
+      successfulEdit,
+      `Expected a successful edit tool call (${validTools.join(', ')})`,
+    ).toBeTruthy();
 
     const newFileContent = rig.readFile(fileName);
+    if (newFileContent !== expectedContent) {
+      printDebugInfo(rig, result, {
+        'Final file content': newFileContent,
+        'Expected file content': expectedContent,
+        'Tool logs': rig.readToolLogs(),
+      });
+    }
     expect(newFileContent).toBe(expectedContent);
   });
 

integration-tests/flicker.test.ts

@@ -6,25 +6,34 @@
 
 import { describe, it, expect } from 'vitest';
 import { TestRig } from './test-helper.js';
+import { join } from 'node:path';
 
 describe('Flicker Detector', () => {
   it('should not detect a flicker under the max height budget', async () => {
     const rig = new TestRig();
-    await rig.setup('flicker-detector-test');
+    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 sessionCountMetric = rig.readMetric('session.count');
-    expect(sessionCountMetric).not.toBeNull();
-
-    // We expect NO flicker event to be found.
-    const flickerMetric = rig.readMetric('ui.flicker.count');
-    expect(flickerMetric).toBeNull();
+      // We expect NO flicker event to be found.
+      const flickerMetric = rig.readMetric('ui.flicker.count');
+      expect(flickerMetric).toBeNull();
+    } finally {
+      await rig.cleanup();
+    }
   });
 });

integration-tests/globalSetup.ts

@@ -9,39 +9,36 @@ if (process.env['NO_COLOR'] !== undefined) {
   delete process.env['NO_COLOR'];
 }
 
-import {
-  mkdir,
-  readdir,
-  rm,
-  readFile,
-  writeFile,
-  unlink,
-} from 'node:fs/promises';
+import { mkdir, readdir, rm } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { getGlobalMemoryFilePath } from '../packages/core/src/tools/memoryTool.js';
+import { canUseRipgrep } from '../packages/core/src/tools/ripGrep.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const rootDir = join(__dirname, '..');
 const integrationTestsDir = join(rootDir, '.integration-tests');
 let runDir = ''; // Make runDir accessible in teardown
 
-const memoryFilePath = getGlobalMemoryFilePath();
-let originalMemoryContent: string | null = null;
-
 export async function setup() {
-  try {
-    originalMemoryContent = await readFile(memoryFilePath, 'utf-8');
-  } catch (e) {
-    if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
-      throw e;
-    }
-    // File doesn't exist, which is fine.
-  }
-
   runDir = join(integrationTestsDir, `${Date.now()}`);
   await mkdir(runDir, { recursive: true });
 
+  // Set the home directory to the test run directory to avoid conflicts
+  // with the user's local config.
+  process.env['HOME'] = runDir;
+  if (process.platform === 'win32') {
+    process.env['USERPROFILE'] = runDir;
+  }
+  // We also need to set the config dir explicitly, since the code might
+  // construct the path before the HOME env var is set.
+  process.env['GEMINI_CONFIG_DIR'] = join(runDir, '.gemini');
+
+  // Download ripgrep to avoid race conditions in parallel tests
+  const available = await canUseRipgrep();
+  if (!available) {
+    throw new Error('Failed to download ripgrep binary');
+  }
+
   // Clean up old test runs, but keep the latest few for debugging
   try {
     const testRuns = await readdir(integrationTestsDir);
@@ -62,6 +59,8 @@ export async function setup() {
 
   process.env['INTEGRATION_TEST_FILE_DIR'] = runDir;
   process.env['GEMINI_CLI_INTEGRATION_TEST'] = 'true';
+  // Force file storage to avoid keychain prompts/hangs in CI, especially on macOS
+  process.env['GEMINI_FORCE_FILE_STORAGE'] = 'true';
   process.env['TELEMETRY_LOG_FILE'] = join(runDir, 'telemetry.log');
 
   if (process.env['KEEP_OUTPUT']) {
@@ -77,15 +76,4 @@ export async function teardown() {
   if (process.env['KEEP_OUTPUT'] !== 'true' && runDir) {
     await rm(runDir, { recursive: true, force: true });
   }
-
-  if (originalMemoryContent !== null) {
-    await mkdir(dirname(memoryFilePath), { recursive: true });
-    await writeFile(memoryFilePath, originalMemoryContent, 'utf-8');
-  } else {
-    try {
-      await unlink(memoryFilePath);
-    } catch {
-      // File might not exist if the test failed before creating it.
-    }
-  }
 }

integration-tests/json-output.error.responses

@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"thought":true,"text":"**Investigating File Access**\n\nI'm currently focused on the challenge of reading a file. The path provided is `/gemini-cli/.integration-tests/1761766343238/json-output-error/path/to/nonexistent/file.txt`, and I'm anticipating an error. It's safe to assume the file doesn't exist, which I intend to handle by responding with \"File not found\" as instructed.\n\n\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12303,"totalTokenCount":12418,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12303}],"thoughtsTokenCount":115}},{"candidates":[{"content":{"parts":[{"thought":true,"text":"**Analyzing Error Handling**\n\nI've attempted to read the specified file, expecting an error due to the \"nonexistent\" path. My plan is to catch the error thrown by the `read_file` tool. Upon receiving this error, I'll promptly return \"File not found.\" This is in line with the initial instructions and ensures appropriate error management for the user's intended functionality. I'm now testing the error response.\n\n\n"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":12303,"totalTokenCount":12467,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12303}],"thoughtsTokenCount":164}},{"candidates":[{"content":{"parts":[{"thoughtSignature":"CiQB0e2Kb0c450IIdZRHl1vvjWDAl9oKa7s5sfFgrTnU0w3qBQwKYgHR7YpvPjZlXSHaJNYgX8IuCvxfyyeACX4NZ8u+u3Z1kqQbgOMpiH6aPYCK9lPyhVftPDBF2m3j7Y2AShwXSpB+9+UB3zphOKCvq6i0ZLvK6QzVynZ1fySQacyjEBD+U6y5CpoBAdHtim9D6oskRu7f3x8rp56h24i6dwb1hzlyqLGl3A5Hsh/fGYjBCxR+Vs+U5Sb7LunmFMKxmO1fktz0x06FUiyaWgAaXl4E4FyLTKs9BbPdgo58uAhaI3vTQybeGZQzkRi6n+ywCniVKaTUd07EHYWdvLiB6x5zFKVOiTmh8PC6I4vNOkJIzFXRfR5aM5QFjEQY8R88HBH+ugraAQHR7YpvuNUG8Ttbzg+kq+kJYMNGDG4zVLPxFBbJZYU5zGLFLrNeEpp9HJ+1N1Pdts17J5pzoefKd2U9H5muPxoeW1CCpFqqKfYZNyoChrQnb4CgWoJ92pcb2UAZbDQ6H4rTyXWdXaAEP1i8rOmdWzI5GFPyxCwBKAbFhfMJOo7P4va5H13XTlLgWAgXlx3n24ookkD/DOL9ro/F6pmV6tzf/j7RVl0V5yozngnrFl4dFsQPp1nDQcFkbRIKHD30byjLGh6Vd6A2lrB477qUaCRfPXtlEgKgsOSYCuABAdHtim+PJPZV3QuQoJ0Qokr+vcdW1W2qzC4Vvt4QRJXyp6+eIS6iNjOisk4jfWLHmLTa11KrUSQsFJnGwsFhe1foOqfO4y46ROBPeSdyuc0gDzSCZPowiovGBwoZd+MbPTTVyExWBo6StVk+xWLj+sUqa8VDof45AOOK9kdzcLQPa2SXIeK6SYLS1zVTrbzGHQDZPv9UC99lmKxPFqAcuwpe9CQre9J3GcZSwd5Mfs/UkHbWui10a8jga4Ck7umjKSDFq/VWiRUp/jh+EN4xeLTG/UQhgH49Gw+Bi1hN1uYKIgHR7YpvS0j1oO2HV/HeK3YxSku9CLQ3OSJGhoAKiu8UGYE=","functionCall":{"name":"read_file","args":{"file_path":"/gemini-cli/.integration-tests/1761766343238/json-output-error/path/to/nonexistent/file.txt"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12303,"candidatesTokenCount":58,"totalTokenCount":12525,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12303}],"thoughtsTokenCount":164}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"File not found"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12588,"candidatesTokenCount":3,"totalTokenCount":12591,"promptTokensDetails":[{"modality":"TEXT","tokenCount":12588}]}}]}

integration-tests/json-output.test.ts

@@ -6,6 +6,7 @@
 
 import { expect, describe, it, beforeEach, afterEach } from 'vitest';
 import { TestRig } from './test-helper.js';
+import { join } from 'node:path';
 
 describe('JSON output', () => {
   let rig: TestRig;
@@ -39,7 +40,9 @@ describe('JSON output', () => {
     process.env['GOOGLE_GENAI_USE_GCA'] = 'true';
     await rig.setup('json-output-auth-mismatch', {
       settings: {
-        security: { auth: { enforcedType: 'gemini-api-key' } },
+        security: {
+          auth: { enforcedType: 'gemini-api-key', selectedType: '' },
+        },
       },
     });
 
@@ -85,7 +88,13 @@ describe('JSON output', () => {
     expect(payload.error.message).toContain("current type is 'oauth-personal'");
   });
 
-  it.skip('should not exit on tool errors and allow model to self-correct in JSON mode', async () => {
+  it('should not exit on tool errors and allow model to self-correct in JSON mode', async () => {
+    rig.setup('json-output-error', {
+      fakeResponsesPath: join(
+        import.meta.dirname,
+        '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".',

integration-tests/list_directory.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it } from 'vitest';
 import {
   TestRig,
   poll,
@@ -17,7 +17,7 @@ import { join } from 'node:path';
 describe('list_directory', () => {
   it('should be able to list a directory', async () => {
     const rig = new TestRig();
-    await rig.setup('should be able to list a directory');
+    rig.setup('should be able to list a directory');
     rig.createFile('file1.txt', 'file 1 content');
     rig.mkdir('subdir');
     rig.sync();
@@ -38,33 +38,27 @@ describe('list_directory', () => {
 
     const result = await rig.run(prompt);
 
-    const foundToolCall = await rig.waitForToolCall('list_directory');
+    try {
+      await rig.expectToolCallSuccess(['list_directory']);
+    } catch (e) {
+      // Add debugging information
+      if (!result.includes('file1.txt') || !result.includes('subdir')) {
+        const allTools = printDebugInfo(rig, result, {
+          'Found tool call': false,
+          'Contains file1.txt': result.includes('file1.txt'),
+          'Contains subdir': result.includes('subdir'),
+        });
 
-    // Add debugging information
-    if (
-      !foundToolCall ||
-      !result.includes('file1.txt') ||
-      !result.includes('subdir')
-    ) {
-      const allTools = printDebugInfo(rig, result, {
-        'Found tool call': foundToolCall,
-        'Contains file1.txt': result.includes('file1.txt'),
-        'Contains subdir': result.includes('subdir'),
-      });
-
-      console.error(
-        'List directory calls:',
-        allTools
-          .filter((t) => t.toolRequest.name === 'list_directory')
-          .map((t) => t.toolRequest.args),
-      );
+        console.error(
+          'List directory calls:',
+          allTools
+            .filter((t) => t.toolRequest.name === 'list_directory')
+            .map((t) => t.toolRequest.args),
+        );
+      }
+      throw e;
     }
 
-    expect(
-      foundToolCall,
-      'Expected to find a list_directory tool call',
-    ).toBeTruthy();
-
     // Validate model output - will throw if no output, warn if missing expected content
     validateModelOutput(result, ['file1.txt', 'subdir'], 'List directory test');
   });

integration-tests/read_many_files.test.ts

@@ -43,5 +43,6 @@ 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

@@ -26,7 +26,7 @@ describe('replace', () => {
     expect(rig.readFile(fileName)).toBe(expectedContent);
   });
 
-  it('should handle $ literally when replacing text ending with $', async () => {
+  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 $',
@@ -48,7 +48,7 @@ describe('replace', () => {
     expect(rig.readFile(fileName)).toBe(expectedContent);
   });
 
-  it('should insert a multi-line block of text', async () => {
+  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');
     const fileName = 'insert_block.txt';
@@ -67,7 +67,7 @@ describe('replace', () => {
     expect(rig.readFile(fileName)).toBe(expectedContent);
   });
 
-  it('should delete a block of text', async () => {
+  it.skip('should delete a block of text', async () => {
     const rig = new TestRig();
     await rig.setup('should delete a block of text');
     const fileName = 'delete_block.txt';
@@ -78,7 +78,7 @@ describe('replace', () => {
     rig.createFile(fileName, originalContent);
 
     await rig.run(
-      `In ${fileName}, delete the entire block from "## DELETE THIS ##" to "## END DELETE ##" including the markers.`,
+      `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');

integration-tests/ripgrep-real.test.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import { RipGrepTool } from '../packages/core/src/tools/ripGrep.js';
+import { Config } from '../packages/core/src/config/config.js';
+import { WorkspaceContext } from '../packages/core/src/utils/workspaceContext.js';
+
+// Mock Config to provide necessary context
+class MockConfig {
+  constructor(private targetDir: string) {}
+
+  getTargetDir() {
+    return this.targetDir;
+  }
+
+  getWorkspaceContext() {
+    return new WorkspaceContext(this.targetDir, [this.targetDir]);
+  }
+
+  getDebugMode() {
+    return true;
+  }
+}
+
+describe('ripgrep-real-direct', () => {
+  let tempDir: string;
+  let tool: RipGrepTool;
+
+  beforeAll(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ripgrep-real-test-'));
+
+    // Create test files
+    await fs.writeFile(path.join(tempDir, 'file1.txt'), 'hello world\n');
+    await fs.mkdir(path.join(tempDir, 'subdir'));
+    await fs.writeFile(
+      path.join(tempDir, 'subdir', 'file2.txt'),
+      'hello universe\n',
+    );
+    await fs.writeFile(path.join(tempDir, 'file3.txt'), 'goodbye moon\n');
+
+    const config = new MockConfig(tempDir) as unknown as Config;
+    tool = new RipGrepTool(config);
+  });
+
+  afterAll(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('should find matches using the real ripgrep binary', async () => {
+    const invocation = tool.build({ pattern: 'hello' });
+    const result = await invocation.execute(new AbortController().signal);
+
+    expect(result.llmContent).toContain('Found 2 matches');
+    expect(result.llmContent).toContain('file1.txt');
+    expect(result.llmContent).toContain('L1: hello world');
+    expect(result.llmContent).toContain('subdir'); // Should show path
+    expect(result.llmContent).toContain('file2.txt');
+    expect(result.llmContent).toContain('L1: hello universe');
+
+    expect(result.llmContent).not.toContain('goodbye moon');
+  });
+
+  it('should handle no matches correctly', async () => {
+    const invocation = tool.build({ pattern: 'nonexistent_pattern_123' });
+    const result = await invocation.execute(new AbortController().signal);
+
+    expect(result.llmContent).toContain('No matches found');
+  });
+
+  it('should respect include filters', async () => {
+    // Create a .js file
+    await fs.writeFile(
+      path.join(tempDir, 'script.js'),
+      'console.log("hello");\n',
+    );
+
+    const invocation = tool.build({ pattern: 'hello', include: '*.js' });
+    const result = await invocation.execute(new AbortController().signal);
+
+    expect(result.llmContent).toContain('Found 1 match');
+    expect(result.llmContent).toContain('script.js');
+    expect(result.llmContent).not.toContain('file1.txt');
+  });
+});

integration-tests/run_shell_command.test.ts

@@ -13,15 +13,73 @@ const { shell } = getShellConfiguration();
 function getLineCountCommand(): { command: string; tool: string } {
   switch (shell) {
     case 'powershell':
-      return {
-        command: `(Get-Content test.txt).Length`,
-        tool: 'Get-Content',
-      };
     case 'cmd':
-      return { command: `find /c /v "" test.txt`, tool: 'find' };
+      return { command: `find /c /v`, tool: 'find' };
     case 'bash':
     default:
-      return { command: `wc -l test.txt`, tool: 'wc' };
+      return { command: `wc -l`, tool: 'wc' };
+  }
+}
+
+function getInvalidCommand(): string {
+  switch (shell) {
+    case 'powershell':
+      return `Get-ChildItem | | Select-Object`;
+    case 'cmd':
+      return `dir | | findstr foo`;
+    case 'bash':
+    default:
+      return `echo "hello" > > file`;
+  }
+}
+
+function getAllowedListCommand(): string {
+  switch (shell) {
+    case 'powershell':
+      return 'Get-ChildItem';
+    case 'cmd':
+      return 'dir';
+    case 'bash':
+    default:
+      return 'ls';
+  }
+}
+
+function getDisallowedFileReadCommand(testFile: string): {
+  command: string;
+  tool: string;
+} {
+  const quotedPath = `"${testFile}"`;
+  switch (shell) {
+    case 'powershell':
+      return { command: `Get-Content ${quotedPath}`, tool: 'Get-Content' };
+    case 'cmd':
+      return { command: `type ${quotedPath}`, tool: 'type' };
+    case 'bash':
+    default:
+      return { command: `cat ${quotedPath}`, tool: 'cat' };
+  }
+}
+
+function getChainedEchoCommand(): { allowPattern: string; command: string } {
+  const secondCommand = getAllowedListCommand();
+  switch (shell) {
+    case 'powershell':
+      return {
+        allowPattern: 'Write-Output',
+        command: `Write-Output "foo" && ${secondCommand}`,
+      };
+    case 'cmd':
+      return {
+        allowPattern: 'echo',
+        command: `echo "foo" && ${secondCommand}`,
+      };
+    case 'bash':
+    default:
+      return {
+        allowPattern: 'echo',
+        command: `echo "foo" && ${secondCommand}`,
+      };
   }
 }
 
@@ -86,13 +144,13 @@ describe('run_shell_command', () => {
     validateModelOutput(result, 'test-stdin', 'Shell command stdin test');
   });
 
-  it('should run allowed sub-command in non-interactive mode', async () => {
+  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');
-    const { tool } = getLineCountCommand();
-    const prompt = `use ${tool} to tell me how many lines there are in ${testFile}`;
+    const { tool, command } = getLineCountCommand();
+    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(
@@ -106,8 +164,17 @@ describe('run_shell_command', () => {
     const foundToolCall = await rig.waitForToolCall('run_shell_command', 15000);
 
     if (!foundToolCall) {
+      const toolLogs = rig.readToolLogs().map(({ toolRequest }) => ({
+        name: toolRequest.name,
+        success: toolRequest.success,
+        args: toolRequest.args,
+      }));
       printDebugInfo(rig, result, {
         'Found tool call': foundToolCall,
+        'Allowed tools flag': `run_shell_command(${tool})`,
+        Prompt: prompt,
+        'Tool logs': toolLogs,
+        Result: result,
       });
     }
 
@@ -124,13 +191,13 @@ describe('run_shell_command', () => {
     expect(toolCall.toolRequest.success).toBe(true);
   });
 
-  it('should succeed with no parens in non-interactive mode', async () => {
+  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 { tool } = getLineCountCommand();
-    const prompt = `use ${tool} to tell me how many lines there are in ${testFile}`;
+    const { command } = getLineCountCommand();
+    const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
     const result = await rig.run(
       {
@@ -166,8 +233,8 @@ describe('run_shell_command', () => {
     await rig.setup('should succeed with --yolo mode');
 
     const testFile = rig.createFile('test.txt', 'Lorem\nIpsum\nDolor\n');
-    const { tool } = getLineCountCommand();
-    const prompt = `use ${tool} to tell me how many lines there are in ${testFile}`;
+    const { command } = getLineCountCommand();
+    const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
     const result = await rig.run({
       prompt: prompt,
@@ -195,13 +262,13 @@ describe('run_shell_command', () => {
     expect(toolCall.toolRequest.success).toBe(true);
   });
 
-  it('should work with ShellTool alias', async () => {
+  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 } = getLineCountCommand();
-    const prompt = `use ${tool} to tell me how many lines there are in ${testFile}`;
+    const { tool, command } = getLineCountCommand();
+    const prompt = `use ${command} to tell me how many lines there are in ${testFile}`;
 
     const result = await rig.run(
       {
@@ -214,8 +281,17 @@ describe('run_shell_command', () => {
     const foundToolCall = await rig.waitForToolCall('run_shell_command', 15000);
 
     if (!foundToolCall) {
+      const toolLogs = rig.readToolLogs().map(({ toolRequest }) => ({
+        name: toolRequest.name,
+        success: toolRequest.success,
+        args: toolRequest.args,
+      }));
       printDebugInfo(rig, result, {
         'Found tool call': foundToolCall,
+        'Allowed tools flag': `ShellTool(${tool})`,
+        Prompt: prompt,
+        'Tool logs': toolLogs,
+        Result: result,
       });
     }
 
@@ -238,9 +314,9 @@ describe('run_shell_command', () => {
     const rig = new TestRig();
     await rig.setup('should combine multiple --allowed-tools flags');
 
-    const { tool } = getLineCountCommand();
+    const { tool, command } = getLineCountCommand();
     const prompt =
-      `use both ${tool} and ls to count the number of lines in files in this ` +
+      `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(
@@ -284,6 +360,103 @@ 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');
+
+    const testFile = rig.createFile('test.txt', 'Disallowed command check\n');
+    const allowedCommand = getAllowedListCommand();
+    const disallowed = getDisallowedFileReadCommand(testFile);
+    const prompt =
+      `I am testing the allowed tools configuration. ` +
+      `Attempt to run "${disallowed.command}" to read the contents of ${testFile}. ` +
+      `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})`,
+    );
+
+    if (!result.toLowerCase().includes('fail')) {
+      printDebugInfo(rig, result, {
+        Result: result,
+        AllowedCommand: allowedCommand,
+        DisallowedCommand: disallowed.command,
+      });
+    }
+    expect(result).toContain('FAIL');
+
+    const foundToolCall = await rig.waitForToolCall(
+      'run_shell_command',
+      15000,
+      (args) => args.toLowerCase().includes(disallowed.tool.toLowerCase()),
+    );
+
+    if (!foundToolCall) {
+      printDebugInfo(rig, result, {
+        'Found tool call': foundToolCall,
+        ToolLogs: rig.readToolLogs(),
+      });
+    }
+    expect(foundToolCall).toBe(true);
+
+    const toolLogs = rig
+      .readToolLogs()
+      .filter((toolLog) => toolLog.toolRequest.name === 'run_shell_command');
+    const failureLog = toolLogs.find((toolLog) =>
+      toolLog.toolRequest.args
+        .toLowerCase()
+        .includes(disallowed.tool.toLowerCase()),
+    );
+
+    if (!failureLog || failureLog.toolRequest.success) {
+      printDebugInfo(rig, result, {
+        ToolLogs: toolLogs,
+        DisallowedTool: disallowed.tool,
+      });
+    }
+
+    expect(
+      failureLog,
+      'Expected failing run_shell_command invocation',
+    ).toBeTruthy();
+    expect(failureLog!.toolRequest.success).toBe(false);
+  });
+
+  // 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',
+    );
+
+    const chained = getChainedEchoCommand();
+    const shellInjection = `!{${chained.command}}`;
+
+    await rig.run(
+      {
+        stdin: `${shellInjection}\n`,
+        yolo: false,
+      },
+      `--allowed-tools=ShellTool(${chained.allowPattern})`,
+    );
+
+    // CLI should refuse to execute the chained command without scheduling run_shell_command.
+    const toolLogs = rig
+      .readToolLogs()
+      .filter((log) => log.toolRequest.name === 'run_shell_command');
+
+    // Success is false because tool is in the scheduled state.
+    for (const log of toolLogs) {
+      expect(log.toolRequest.success).toBe(false);
+      expect(log.toolRequest.args).toContain('&&');
+    }
+  });
+
   it('should allow all with "ShellTool" and other specific tools', async () => {
     const rig = new TestRig();
     await rig.setup(
@@ -363,7 +536,7 @@ describe('run_shell_command', () => {
     }
   });
 
-  it('should run a platform-specific file listing command', async () => {
+  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`;
@@ -390,4 +563,53 @@ describe('run_shell_command', () => {
     validateModelOutput(result, fileName, 'Platform-specific listing test');
     expect(result).toContain(fileName);
   });
+
+  it('rejects invalid shell expressions', async () => {
+    const rig = new TestRig();
+    await rig.setup('rejects invalid shell expressions');
+    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.`,
+    );
+    expect(result).toContain('FAIL');
+
+    const escapedInvalidCommand = JSON.stringify(invalidCommand).slice(1, -1);
+    const foundToolCall = await rig.waitForToolCall(
+      'run_shell_command',
+      15000,
+      (args) =>
+        args.toLowerCase().includes(escapedInvalidCommand.toLowerCase()),
+    );
+
+    if (!foundToolCall) {
+      printDebugInfo(rig, result, {
+        'Found tool call': foundToolCall,
+        EscapedCommand: escapedInvalidCommand,
+        ToolLogs: rig.readToolLogs(),
+      });
+    }
+    expect(foundToolCall).toBe(true);
+
+    const toolLogs = rig
+      .readToolLogs()
+      .filter((toolLog) => toolLog.toolRequest.name === 'run_shell_command');
+    const failureLog = toolLogs.find((toolLog) =>
+      toolLog.toolRequest.args
+        .toLowerCase()
+        .includes(escapedInvalidCommand.toLowerCase()),
+    );
+
+    if (!failureLog || failureLog.toolRequest.success) {
+      printDebugInfo(rig, result, {
+        ToolLogs: toolLogs,
+        EscapedCommand: escapedInvalidCommand,
+      });
+    }
+
+    expect(
+      failureLog,
+      'Expected failing run_shell_command invocation for invalid syntax',
+    ).toBeTruthy();
+    expect(failureLog!.toolRequest.success).toBe(false);
+  });
 });

integration-tests/test-helper.ts

@@ -192,7 +192,12 @@ export class InteractiveRun {
       timeout,
       200,
     );
-    expect(found, `Did not find expected text: "${text}"`).toBe(true);
+    expect(
+      found,
+      `Did not find expected text: "${text}". Output was:\n${stripAnsi(
+        this.output,
+      )}`,
+    ).toBe(true);
   }
 
   // This types slowly to make sure command is correct, but only work for short
@@ -220,6 +225,13 @@ export class InteractiveRun {
     }
   }
 
+  // Types an entire string at once, necessary for some things like commands
+  // but may run into paste detection issues for larger strings.
+  async sendText(text: string) {
+    this.ptyProcess.write(text);
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+
   // Simulates typing a string one character at a time to avoid paste detection.
   async sendKeys(text: string) {
     const delay = 5;
@@ -255,6 +267,10 @@ export class TestRig {
   testDir: string | 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');
@@ -263,12 +279,22 @@ export class TestRig {
 
   setup(
     testName: string,
-    options: { settings?: Record<string, unknown> } = {},
+    options: {
+      settings?: Record<string, unknown>;
+      fakeResponsesPath?: string;
+    } = {},
   ) {
     this.testName = testName;
     const sanitizedName = sanitizeTestName(testName);
     this.testDir = join(env['INTEGRATION_TEST_FILE_DIR']!, sanitizedName);
     mkdirSync(this.testDir, { recursive: true });
+    if (options.fakeResponsesPath) {
+      this.fakeResponsesPath = join(this.testDir, 'fake-responses.json');
+      this.originalFakeResponsesPath = options.fakeResponsesPath;
+      if (process.env['REGENERATE_MODEL_GOLDENS'] !== 'true') {
+        fs.copyFileSync(options.fakeResponsesPath, this.fakeResponsesPath);
+      }
+    }
 
     // Create a settings file to point the CLI to the local collector
     const geminiDir = join(this.testDir, GEMINI_DIR);
@@ -282,6 +308,7 @@ export class TestRig {
         // Nightly releases sometimes becomes out of sync with local code and
         // triggers auto-update, which causes tests to fail.
         disableAutoUpdate: true,
+        previewFeatures: false,
       },
       telemetry: {
         enabled: true,
@@ -297,6 +324,8 @@ export class TestRig {
       model: DEFAULT_GEMINI_MODEL,
       sandbox:
         env['GEMINI_SANDBOX'] !== 'false' ? env['GEMINI_SANDBOX'] : false,
+      // Don't show the IDE connection dialog when running from VsCode
+      ide: { enabled: false, hasSeenNudge: true },
       ...options.settings, // Allow tests to override/add settings
     };
     writeFileSync(
@@ -335,6 +364,13 @@ export class TestRig {
     const initialArgs = isNpmReleaseTest
       ? extraInitialArgs
       : [this.bundlePath, ...extraInitialArgs];
+    if (this.fakeResponsesPath) {
+      if (process.env['REGENERATE_MODEL_GOLDENS'] === 'true') {
+        initialArgs.push('--record-responses', this.fakeResponsesPath);
+      } else {
+        initialArgs.push('--fake-responses', this.fakeResponsesPath);
+      }
+    }
     return { command, initialArgs };
   }
 
@@ -365,13 +401,13 @@ export class TestRig {
     };
 
     if (typeof promptOrOptions === 'string') {
-      commandArgs.push('--prompt', promptOrOptions);
+      commandArgs.push(promptOrOptions);
     } else if (
       typeof promptOrOptions === 'object' &&
       promptOrOptions !== null
     ) {
       if (promptOrOptions.prompt) {
-        commandArgs.push('--prompt', promptOrOptions.prompt);
+        commandArgs.push(promptOrOptions.prompt);
       }
       if (promptOrOptions.stdin) {
         execOptions.input = promptOrOptions.stdin;
@@ -544,6 +580,12 @@ export class TestRig {
   }
 
   async cleanup() {
+    if (
+      process.env['REGENERATE_MODEL_GOLDENS'] === 'true' &&
+      this.fakeResponsesPath
+    ) {
+      fs.copyFileSync(this.fakeResponsesPath, this.originalFakeResponsesPath!);
+    }
     // Clean up test directory
     if (this.testDir && !env['KEEP_OUTPUT']) {
       try {
@@ -628,7 +670,11 @@ export class TestRig {
     );
   }
 
-  async expectToolCallSuccess(toolNames: string[], timeout?: number) {
+  async expectToolCallSuccess(
+    toolNames: string[],
+    timeout?: number,
+    matchArgs?: (args: string) => boolean,
+  ) {
     // Use environment-specific timeout
     if (!timeout) {
       timeout = getDefaultTimeout();
@@ -642,7 +688,10 @@ export class TestRig {
         const toolLogs = this.readToolLogs();
         return toolNames.some((name) =>
           toolLogs.some(
-            (log) => log.toolRequest.name === name && log.toolRequest.success,
+            (log) =>
+              log.toolRequest.name === name &&
+              log.toolRequest.success &&
+              (matchArgs?.call(this, log.toolRequest.args) ?? true),
           ),
         );
       },
@@ -910,6 +959,34 @@ export class TestRig {
     return apiRequests.pop() || null;
   }
 
+  async waitForMetric(metricName: string, timeout?: number) {
+    await this.waitForTelemetryReady();
+
+    const fullName = metricName.startsWith('gemini_cli.')
+      ? metricName
+      : `gemini_cli.${metricName}`;
+
+    return poll(
+      () => {
+        const logs = this._readAndParseTelemetryLog();
+        for (const logData of logs) {
+          if (logData.scopeMetrics) {
+            for (const scopeMetric of logData.scopeMetrics) {
+              for (const metric of scopeMetric.metrics) {
+                if (metric.descriptor.name === fullName) {
+                  return true;
+                }
+              }
+            }
+          }
+        }
+        return false;
+      },
+      timeout ?? getDefaultTimeout(),
+      100,
+    );
+  }
+
   readMetric(metricName: string): Record<string, unknown> | null {
     const logs = this._readAndParseTelemetryLog();
     for (const logData of logs) {
@@ -933,7 +1010,7 @@ export class TestRig {
     const options: pty.IPtyForkOptions = {
       name: 'xterm-color',
       cols: 80,
-      rows: 24,
+      rows: 80,
       cwd: this.testDir!,
       env: Object.fromEntries(
         Object.entries(env).filter(([, v]) => v !== undefined),
@@ -945,7 +1022,7 @@ export class TestRig {
 
     const run = new InteractiveRun(ptyProcess);
     // Wait for the app to be ready
-    await run.expectText('Type your message', 30000);
+    await run.expectText('  Type your message or @path/to/file', 30000);
     return run;
   }
 }

integration-tests/test-mcp-server.ts

@@ -4,17 +4,21 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  McpServer,
+  type ToolCallback,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
 import { type Server as HTTPServer } from 'node:http';
-
-import { randomUUID } from 'node:crypto';
+import { type ZodRawShape } from 'zod';
 
 export class TestMcpServer {
   private server: HTTPServer | undefined;
 
-  async start(): Promise<number> {
+  async start(
+    tools?: Record<string, ToolCallback<ZodRawShape>>,
+  ): Promise<number> {
     const app = express();
     app.use(express.json());
     const mcpServer = new McpServer(
@@ -22,18 +26,30 @@ export class TestMcpServer {
         name: 'test-mcp-server',
         version: '1.0.0',
       },
-      { capabilities: {} },
+      { capabilities: { tools: {} } },
     );
-
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => randomUUID(),
-    });
-    mcpServer.connect(transport);
+    if (tools) {
+      for (const [name, cb] of Object.entries(tools)) {
+        mcpServer.registerTool(name, {}, cb);
+      }
+    }
 
     app.post('/mcp', async (req, res) => {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+      });
+      res.on('close', () => {
+        transport.close();
+      });
+      await mcpServer.connect(transport);
       await transport.handleRequest(req, res, req.body);
     });
 
+    app.get('/mcp', async (req, res) => {
+      res.status(405).send('Not supported');
+    });
+
     return new Promise((resolve, reject) => {
       this.server = app.listen(0, () => {
         const address = this.server!.address();

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

@@ -9,9 +9,6 @@ import { writeFileSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { TestRig } from './test-helper.js';
 
-// Windows skip (Option A: avoid infra scope)
-const d = process.platform === 'win32' ? describe.skip : describe;
-
 // BOM encoders
 const utf8BOM = (s: string) =>
   Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(s, 'utf8')]);
@@ -53,7 +50,7 @@ const utf32BE = (s: string) => {
 let rig: TestRig;
 let dir: string;
 
-d('BOM end-to-end integration', () => {
+describe('BOM end-to-end integraion', () => {
   beforeAll(async () => {
     rig = new TestRig();
     await rig.setup('bom-integration');

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.10.0",
+  "version": "0.17.0-preview.4",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -14,19 +14,23 @@
     "url": "git+https://github.com/google-gemini/gemini-cli.git"
   },
   "config": {
-    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.10.0"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.17.0-preview.4"
   },
   "scripts": {
     "start": "cross-env NODE_ENV=development node scripts/start.js",
     "start:a2a-server": "CODER_AGENT_PORT=41242 npm run start --workspace @google/gemini-cli-a2a-server",
     "debug": "cross-env DEBUG=1 node --inspect-brk scripts/start.js",
     "deflake": "node scripts/deflake.js",
-    "deflake:test:integration:sandbox:none": "npm run deflake -- --command='npm run test:integration:sandbox:none -- --retry=0'",
-    "deflake:test:integration:sandbox:docker": "npm run deflake -- --command='npm run test:integration:sandbox:docker -- --retry=0'",
+    "deflake:test:integration:sandbox:none": "npm run deflake -- --command=\"npm run test:integration:sandbox:none -- --retry=0\"",
+    "deflake:test:integration:sandbox:docker": "npm run deflake -- --command=\"npm run test:integration:sandbox:docker -- --retry=0\"",
     "auth:npm": "npx google-artifactregistry-auth",
     "auth:docker": "gcloud auth configure-docker us-west1-docker.pkg.dev",
     "auth": "npm run auth:npm && npm run auth:docker",
     "generate": "node scripts/generate-git-commit-info.js",
+    "predocs:settings": "npm run build --workspace @google/gemini-cli-core",
+    "schema:settings": "tsx ./scripts/generate-settings-schema.ts",
+    "docs:settings": "tsx ./scripts/generate-settings-doc.ts",
+    "docs:keybindings": "tsx ./scripts/generate-keybindings-doc.ts",
     "build": "node scripts/build.js",
     "build-and-start": "npm run build && npm run start",
     "build:vscode": "node scripts/build_vscode_companion.js",
@@ -34,17 +38,17 @@
     "build:packages": "npm run build --workspaces",
     "build:sandbox": "node scripts/build_sandbox.js",
     "bundle": "npm run generate && node esbuild.config.js && node scripts/copy_bundle_assets.js",
-    "test": "npm run test --workspaces --if-present --parallel",
-    "test:ci": "npm run test:ci --workspaces --if-present --parallel && npm run test:scripts",
+    "test": "npm run test --workspaces --if-present",
+    "test:ci": "npm run test:ci --workspaces --if-present && npm run test:scripts",
     "test:scripts": "vitest run --config ./scripts/tests/vitest.config.ts",
     "test:e2e": "cross-env VERBOSE=true KEEP_OUTPUT=true npm run test:integration:sandbox:none",
     "test:integration:all": "npm run test:integration:sandbox:none && npm run test:integration:sandbox:docker && npm run test:integration:sandbox:podman",
     "test:integration:sandbox:none": "cross-env GEMINI_SANDBOX=false vitest run --root ./integration-tests",
     "test:integration:sandbox:docker": "cross-env GEMINI_SANDBOX=docker npm run build:sandbox && cross-env GEMINI_SANDBOX=docker vitest run --root ./integration-tests",
     "test:integration:sandbox:podman": "cross-env GEMINI_SANDBOX=podman vitest run --root ./integration-tests",
-    "lint": "eslint . --ext .ts,.tsx && eslint integration-tests",
-    "lint:fix": "eslint . --fix && eslint integration-tests --fix",
-    "lint:ci": "eslint . --ext .ts,.tsx --max-warnings 0 && eslint integration-tests --max-warnings 0",
+    "lint": "eslint . --ext .ts,.tsx && eslint integration-tests && eslint scripts",
+    "lint:fix": "eslint . --fix --ext .ts,.tsx && eslint integration-tests --fix && eslint scripts --fix && npm run format",
+    "lint:ci": "npm run lint:all",
     "lint:all": "node scripts/lint.js",
     "format": "prettier --experimental-cli --write .",
     "typecheck": "npm run typecheck --workspaces --if-present",
@@ -58,8 +62,8 @@
     "pre-commit": "node scripts/pre-commit.js"
   },
   "overrides": {
+    "ink": "npm:@jrichman/ink@6.4.3",
     "wrap-ansi": "9.0.2",
-    "ansi-regex": "5.0.1",
     "cliui": {
       "wrap-ansi": "7.0.0"
     }
@@ -78,21 +82,26 @@
     "@types/mime-types": "^3.0.1",
     "@types/minimatch": "^5.1.2",
     "@types/mock-fs": "^4.13.4",
+    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
     "@types/shell-quote": "^1.7.5",
     "@vitest/coverage-v8": "^3.1.1",
     "@vitest/eslint-plugin": "^1.3.4",
     "cross-env": "^7.0.3",
     "esbuild": "^0.25.0",
+    "esbuild-plugin-wasm": "^1.1.0",
     "eslint": "^9.24.0",
     "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-license-header": "^0.8.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
-    "glob": "^10.4.5",
+    "glob": "^12.0.0",
     "globals": "^16.0.0",
     "google-artifactregistry-auth": "^3.4.0",
     "husky": "^9.1.7",
+    "ink-testing-library": "^4.0.0",
     "json": "^11.0.0",
     "lint-staged": "^16.1.6",
     "memfs": "^4.42.0",
@@ -101,7 +110,7 @@
     "msw": "^2.10.4",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.5.3",
-    "react-devtools-core": "^4.28.5",
+    "react-devtools-core": "^6.1.2",
     "semver": "^7.7.2",
     "strip-ansi": "^7.1.2",
     "tsx": "^4.20.3",
@@ -110,7 +119,8 @@
     "yargs": "^17.7.2"
   },
   "dependencies": {
-    "@testing-library/dom": "^10.4.1",
+    "ink": "npm:@jrichman/ink@6.4.3",
+    "latest-version": "^9.0.0",
     "simple-git": "^3.28.0"
   },
   "optionalDependencies": {
@@ -125,7 +135,10 @@
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
       "prettier --write",
-      "eslint --fix --max-warnings 0"
+      "eslint --fix --max-warnings 0 --no-warn-ignored"
+    ],
+    "eslint.config.js": [
+      "prettier --write"
     ],
     "*.{json,md}": [
       "prettier --write"

packages/a2a-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli-a2a-server",
-  "version": "0.10.0",
+  "version": "0.17.0-preview.4",
   "description": "Gemini CLI A2A Server",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "@google/gemini-cli-core": "file:../core",
     "express": "^5.1.0",
     "fs-extra": "^11.3.0",
-    "tar": "^7.4.3",
+    "tar": "^7.5.2",
     "uuid": "^11.1.0",
     "winston": "^3.17.0"
   },

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

@@ -17,7 +17,10 @@ import type {
   ServerGeminiToolCallRequestEvent,
   Config,
 } from '@google/gemini-cli-core';
-import { GeminiEventType } from '@google/gemini-cli-core';
+import {
+  GeminiEventType,
+  SimpleExtensionLoader,
+} from '@google/gemini-cli-core';
 import { v4 as uuidv4 } from 'uuid';
 
 import { logger } from '../utils/logger.js';
@@ -96,7 +99,11 @@ export class CoderAgentExecutor implements AgentExecutor {
     loadEnvironment(); // Will override any global env with workspace envs
     const settings = loadSettings(workspaceRoot);
     const extensions = loadExtensions(workspaceRoot);
-    return await loadConfig(settings, extensions, taskId);
+    return await loadConfig(
+      settings,
+      new SimpleExtensionLoader(extensions),
+      taskId,
+    );
   }
 
   /**

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

@@ -4,11 +4,25 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
 import { Task } from './task.js';
-import type { Config, ToolCallRequestInfo } from '@google/gemini-cli-core';
+import {
+  GeminiEventType,
+  type Config,
+  type ToolCallRequestInfo,
+} from '@google/gemini-cli-core';
 import { createMockConfig } from '../utils/testing_utils.js';
 import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import { CoderAgentEvent } from '../types.js';
+import type { ToolCall } from '@google/gemini-cli-core';
 
 describe('Task', () => {
   it('scheduleToolCalls should not modify the input requests array', async () => {
@@ -56,4 +70,204 @@ describe('Task', () => {
 
     expect(requests).toEqual(originalRequests);
   });
+
+  describe('acceptAgentMessage', () => {
+    it('should set currentTraceId when event has traceId', async () => {
+      const mockConfig = createMockConfig();
+      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 for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const event = {
+        type: 'content',
+        value: 'test',
+        traceId: 'test-trace-id',
+      };
+
+      await task.acceptAgentMessage(event);
+
+      expect(mockEventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            traceId: 'test-trace-id',
+          }),
+        }),
+      );
+    });
+
+    it('should handle Citation event and publish to event bus', async () => {
+      const mockConfig = createMockConfig();
+      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 for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const citationText = 'Source: example.com';
+      const citationEvent = {
+        type: GeminiEventType.Citation,
+        value: citationText,
+      };
+
+      await task.acceptAgentMessage(citationEvent);
+
+      expect(mockEventBus.publish).toHaveBeenCalledOnce();
+      const publishedEvent = (mockEventBus.publish as Mock).mock.calls[0][0];
+
+      expect(publishedEvent.kind).toBe('status-update');
+      expect(publishedEvent.taskId).toBe('task-id');
+      expect(publishedEvent.metadata.coderAgent.kind).toBe(
+        CoderAgentEvent.CitationEvent,
+      );
+      expect(publishedEvent.status.message).toBeDefined();
+      expect(publishedEvent.status.message.parts).toEqual([
+        {
+          kind: 'text',
+          text: citationText,
+        },
+      ]);
+    });
+  });
+
+  describe('_schedulerToolCallsUpdate', () => {
+    let task: Task;
+    type SpyInstance = ReturnType<typeof vi.spyOn>;
+    let setTaskStateAndPublishUpdateSpy: SpyInstance;
+
+    beforeEach(() => {
+      const mockConfig = createMockConfig();
+      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
+      task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      // Spy on the method we want to check calls for
+      setTaskStateAndPublishUpdateSpy = vi.spyOn(
+        task,
+        'setTaskStateAndPublishUpdate',
+      );
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('should set state to input-required when a tool is awaiting approval and none are executing', () => {
+      const toolCalls = [
+        { request: { callId: '1' }, status: 'awaiting_approval' },
+      ] as ToolCall[];
+
+      // @ts-expect-error - Calling private method
+      task._schedulerToolCallsUpdate(toolCalls);
+
+      // The last call should be the final state update
+      expect(setTaskStateAndPublishUpdateSpy).toHaveBeenLastCalledWith(
+        'input-required',
+        { kind: 'state-change' },
+        undefined,
+        undefined,
+        true, // final: true
+      );
+    });
+
+    it('should NOT set state to input-required if a tool is awaiting approval but another is executing', () => {
+      const toolCalls = [
+        { request: { callId: '1' }, status: 'awaiting_approval' },
+        { request: { callId: '2' }, status: 'executing' },
+      ] as ToolCall[];
+
+      // @ts-expect-error - Calling private method
+      task._schedulerToolCallsUpdate(toolCalls);
+
+      // It will be called for status updates, but not with final: true
+      const finalCall = setTaskStateAndPublishUpdateSpy.mock.calls.find(
+        (call) => call[4] === true,
+      );
+      expect(finalCall).toBeUndefined();
+    });
+
+    it('should set state to input-required once an executing tool finishes, leaving one awaiting approval', () => {
+      const initialToolCalls = [
+        { request: { callId: '1' }, status: 'awaiting_approval' },
+        { request: { callId: '2' }, status: 'executing' },
+      ] as ToolCall[];
+      // @ts-expect-error - Calling private method
+      task._schedulerToolCallsUpdate(initialToolCalls);
+
+      // No final call yet
+      let finalCall = setTaskStateAndPublishUpdateSpy.mock.calls.find(
+        (call) => call[4] === true,
+      );
+      expect(finalCall).toBeUndefined();
+
+      // Now, the executing tool finishes. The scheduler would call _resolveToolCall for it.
+      // @ts-expect-error - Calling private method
+      task._resolveToolCall('2');
+
+      // Then another update comes in for the awaiting tool (e.g., a re-check)
+      const subsequentToolCalls = [
+        { request: { callId: '1' }, status: 'awaiting_approval' },
+      ] as ToolCall[];
+      // @ts-expect-error - Calling private method
+      task._schedulerToolCallsUpdate(subsequentToolCalls);
+
+      // NOW we should get the final call
+      finalCall = setTaskStateAndPublishUpdateSpy.mock.calls.find(
+        (call) => call[4] === true,
+      );
+      expect(finalCall).toBeDefined();
+      expect(finalCall?.[0]).toBe('input-required');
+    });
+
+    it('should NOT set state to input-required if skipFinalTrueAfterInlineEdit is true', () => {
+      task.skipFinalTrueAfterInlineEdit = true;
+      const toolCalls = [
+        { request: { callId: '1' }, status: 'awaiting_approval' },
+      ] as ToolCall[];
+
+      // @ts-expect-error - Calling private method
+      task._schedulerToolCallsUpdate(toolCalls);
+
+      const finalCall = setTaskStateAndPublishUpdateSpy.mock.calls.find(
+        (call) => call[4] === true,
+      );
+      expect(finalCall).toBeUndefined();
+    });
+  });
 });