Merge branch 'main' into memory_usage3

Co-authored-by: gemini-cli-robot <224641728+gemini-cli-robot@users.noreply.github.com>
Co-authored-by: Sam Roberts <158088236+g-samroberts@users.noreply.github.com>

.github/workflows/agent-session-drift-check.yml

@@ -0,0 +1,132 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: 'Agent Session Drift Check'
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+      - 'release/**'
+    paths:
+      - 'packages/cli/src/nonInteractiveCli.ts'
+      - 'packages/cli/src/nonInteractiveCliAgentSession.ts'
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  check-drift:
+    name: 'Check Agent Session Drift'
+    runs-on: 'ubuntu-latest'
+    if: "github.repository == 'google-gemini/gemini-cli'"
+    permissions:
+      contents: 'read'
+      pull-requests: 'write'
+    steps:
+      - name: 'Detect drift and comment'
+        uses: 'actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea' # ratchet:actions/github-script@v8
+        with:
+          script: |-
+            // === Pair configuration — append here to cover more pairs ===
+            const PAIRS = [
+              {
+                legacy: 'packages/cli/src/nonInteractiveCli.ts',
+                session: 'packages/cli/src/nonInteractiveCliAgentSession.ts',
+                label: 'non-interactive CLI',
+              },
+              // Future pairs can be added here. Remember to also add both
+              // paths to the `paths:` filter at the top of this workflow.
+              // Example:
+              // {
+              //   legacy: 'packages/core/src/agents/local-invocation.ts',
+              //   session: 'packages/core/src/agents/local-session-invocation.ts',
+              //   label: 'local subagent invocation',
+              // },
+            ];
+            // ============================================================
+
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            // Use the API to list changed files — no checkout/git diff needed.
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner,
+              repo,
+              pull_number: prNumber,
+              per_page: 100,
+            });
+            const changed = new Set(files.map((f) => f.filename));
+
+            const warnings = [];
+            for (const { legacy, session, label } of PAIRS) {
+              const legacyChanged = changed.has(legacy);
+              const sessionChanged = changed.has(session);
+              if (legacyChanged && !sessionChanged) {
+                warnings.push(
+                  `**${label}**: \`${legacy}\` was modified but \`${session}\` was not.`,
+                );
+              } else if (!legacyChanged && sessionChanged) {
+                warnings.push(
+                  `**${label}**: \`${session}\` was modified but \`${legacy}\` was not.`,
+                );
+              }
+            }
+
+            const MARKER = '<!-- agent-session-drift-check -->';
+
+            // Look up our existing drift comment (for upsert/cleanup).
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner,
+              repo,
+              issue_number: prNumber,
+              per_page: 100,
+            });
+            const existing = comments.find(
+              (c) => c.user?.type === 'Bot' && c.body?.includes(MARKER),
+            );
+
+            if (warnings.length === 0) {
+              core.info('No drift detected.');
+              // If drift was previously flagged and is now resolved, remove the comment.
+              if (existing) {
+                await github.rest.issues.deleteComment({
+                  owner,
+                  repo,
+                  comment_id: existing.id,
+                });
+                core.info(`Deleted stale drift comment ${existing.id}.`);
+              }
+              return;
+            }
+
+            const body = [
+              MARKER,
+              '### ⚠️ Invocation Drift Warning',
+              '',
+              'The following file pairs should generally be kept in sync during the AgentSession migration:',
+              '',
+              ...warnings.map((w) => `- ${w}`),
+              '',
+              'If this is intentional (e.g., a bug fix specific to one implementation), you can ignore this comment.',
+              '',
+              '_This check will be removed once the legacy implementations are deleted._',
+            ].join('\n');
+
+            if (existing) {
+              core.info(`Updating existing drift comment ${existing.id}.`);
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              core.info('Creating new drift comment.');
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body,
+              });
+            }

.github/workflows/chained_e2e.yml

@@ -183,7 +183,7 @@ jobs:
     needs:
       - 'merge_queue_skipper'
       - 'parse_run_context'
-    runs-on: 'macos-latest'
+    runs-on: 'macos-latest-large'
     if: |
       github.repository == 'google-gemini/gemini-cli' && always() && (needs.merge_queue_skipper.result !='success' || needs.merge_queue_skipper.outputs.skip != 'true')
     steps:

.github/workflows/ci.yml

@@ -224,7 +224,7 @@ jobs:
 
   test_mac:
     name: 'Test (Mac) - ${{ matrix.node-version }}, ${{ matrix.shard }}'
-    runs-on: 'macos-latest'
+    runs-on: 'macos-latest-large'
     needs:
       - 'merge_queue_skipper'
     if: "github.repository == 'google-gemini/gemini-cli' && needs.merge_queue_skipper.outputs.skip == 'false'"

.github/workflows/deflake.yml

@@ -77,7 +77,7 @@ jobs:
 
   deflake_e2e_mac:
     name: 'E2E Test (macOS)'
-    runs-on: 'macos-latest'
+    runs-on: 'macos-latest-large'
     if: "github.repository == 'google-gemini/gemini-cli'"
     steps:
       - name: 'Checkout'

docs/changelogs/index.md

@@ -18,6 +18,27 @@ on GitHub.
 | [Preview](preview.md) | Experimental features ready for early feedback. |
 | [Stable](latest.md)   | Stable, recommended for general use.            |
 
+## Announcements: v0.38.0 - 2026-04-14
+
+- **Chapters Narrative Flow:** Group agent interactions into "Chapters" based on
+  intent and tool usage for better session structure
+  ([#23150](https://github.com/google-gemini/gemini-cli/pull/23150) by
+  @Abhijit-2592,
+  [#24079](https://github.com/google-gemini/gemini-cli/pull/24079) by
+  @gundermanc).
+- **Context Compression Service:** Advanced context management to efficiently
+  distill conversation history
+  ([#24483](https://github.com/google-gemini/gemini-cli/pull/24483) by
+  @joshualitt).
+- **UI Flicker & UX Enhancements:** Solved rendering flicker with "Terminal
+  Buffer" mode and introduced selective topic expansion
+  ([#24512](https://github.com/google-gemini/gemini-cli/pull/24512) by
+  @jacob314, [#24793](https://github.com/google-gemini/gemini-cli/pull/24793) by
+  @Abhijit-2592).
+- **Persistent Policy Approvals:** Implemented context-aware persistent
+  approvals for tool execution
+  ([#23257](https://github.com/google-gemini/gemini-cli/pull/23257) by @jerop).
+
 ## Announcements: v0.37.0 - 2026-04-08
 
 - **Dynamic Sandbox Expansion:** Implemented dynamic sandbox expansion and

docs/changelogs/latest.md

@@ -1,6 +1,6 @@
-# Latest stable release: v0.37.1
+# Latest stable release: v0.38.1
 
-Released: April 09, 2026
+Released: April 15, 2026
 
 For most users, our latest stable release is the recommended release. Install
 the latest stable version with:
@@ -11,415 +11,261 @@ npm install -g @google/gemini-cli
 
 ## Highlights
 
-- **Dynamic Sandbox Expansion:** Implemented dynamic sandbox expansion and
-  worktree support for both Linux and Windows, enhancing development flexibility
-  in restricted environments.
-- **Tool-Based Topic Grouping (Chapters):** Introduced "Chapters" to logically
-  group agent interactions based on tool usage and intent, providing a clearer
-  narrative flow in long sessions.
-- **Enhanced Browser Agent:** Added persistent session management, dynamic
-  read-only tool discovery, and sandbox-aware initialization for the browser
-  agent.
-- **Security & Permission Hardening:** Implemented secret visibility lockdown
-  for environment files and integrated integrity controls for Windows
-  sandboxing.
+- **Chapters Narrative Flow:** Introduced tool-based topic grouping ("Chapters")
+  to provide better session structure and narrative continuity in long-running
+  tasks.
+- **Context Compression Service:** Implemented a dedicated service for advanced
+  context management, efficiently distilling conversation history to preserve
+  focus and tokens.
+- **Enhanced UI Stability & UX:** Introduced a new "Terminal Buffer" mode to
+  solve rendering flicker, along with selective topic expansion and improved
+  tool confirmation layouts.
+- **Context-Aware Policy Approvals:** Users can now grant persistent,
+  context-aware approvals for tools, significantly reducing manual confirmation
+  overhead for trusted workflows.
+- **Background Process Monitoring:** New tools for monitoring and inspecting
+  background shell processes, providing better visibility into asynchronous
+  tasks.
 
 ## What's Changed
 
-- fix(acp): handle all InvalidStreamError types gracefully in prompt
-  [#24540](https://github.com/google-gemini/gemini-cli/pull/24540)
-- feat(acp): add support for /about command
-  [#24649](https://github.com/google-gemini/gemini-cli/pull/24649)
-- feat(acp): add /help command
-  [#24839](https://github.com/google-gemini/gemini-cli/pull/24839)
-- feat(evals): centralize test agents into test-utils for reuse by @Samee24 in
-  [#23616](https://github.com/google-gemini/gemini-cli/pull/23616)
-- revert: chore(config): disable agents by default by @abhipatel12 in
-  [#23672](https://github.com/google-gemini/gemini-cli/pull/23672)
-- fix(plan): update telemetry attribute keys and add timestamp by @Adib234 in
-  [#23685](https://github.com/google-gemini/gemini-cli/pull/23685)
-- fix(core): prevent premature MCP discovery completion by @jackwotherspoon in
-  [#23637](https://github.com/google-gemini/gemini-cli/pull/23637)
-- feat(browser): add maxActionsPerTask for browser agent setting by
-  @cynthialong0-0 in
-  [#23216](https://github.com/google-gemini/gemini-cli/pull/23216)
-- fix(core): improve agent loader error formatting for empty paths by
-  @adamfweidman in
-  [#23690](https://github.com/google-gemini/gemini-cli/pull/23690)
-- fix(cli): only show updating spinner when auto-update is in progress by
-  @scidomino in [#23709](https://github.com/google-gemini/gemini-cli/pull/23709)
-- Refine onboarding metrics to log the duration explicitly and use the tier
-  name. by @yunaseoul in
-  [#23678](https://github.com/google-gemini/gemini-cli/pull/23678)
-- chore(tools): add toJSON to tools and invocations to reduce logging verbosity
-  by @alisa-alisa in
-  [#22899](https://github.com/google-gemini/gemini-cli/pull/22899)
-- fix(cli): stabilize copy mode to prevent flickering and cursor resets by
-  @mattKorwel in
-  [#22584](https://github.com/google-gemini/gemini-cli/pull/22584)
-- fix(test): move flaky ctrl-c-exit test to non-blocking suite by @mattKorwel in
-  [#23732](https://github.com/google-gemini/gemini-cli/pull/23732)
-- feat(skills): add ci skill for automated failure replication by @mattKorwel in
-  [#23720](https://github.com/google-gemini/gemini-cli/pull/23720)
-- feat(sandbox): implement forbiddenPaths for OS-specific sandbox managers by
-  @ehedlund in [#23282](https://github.com/google-gemini/gemini-cli/pull/23282)
-- fix(core): conditionally expose additional_permissions in shell tool by
-  @galz10 in [#23729](https://github.com/google-gemini/gemini-cli/pull/23729)
-- refactor(core): standardize OS-specific sandbox tests and extract linux helper
-  methods by @ehedlund in
-  [#23715](https://github.com/google-gemini/gemini-cli/pull/23715)
-- format recently added script by @scidomino in
-  [#23739](https://github.com/google-gemini/gemini-cli/pull/23739)
-- fix(ui): prevent over-eager slash subcommand completion by @keithguerin in
-  [#20136](https://github.com/google-gemini/gemini-cli/pull/20136)
-- Fix dynamic model routing for gemini 3.1 pro to customtools model by
-  @kevinjwang1 in
-  [#23641](https://github.com/google-gemini/gemini-cli/pull/23641)
-- feat(core): support inline agentCardJson for remote agents by @adamfweidman in
-  [#23743](https://github.com/google-gemini/gemini-cli/pull/23743)
-- fix(cli): skip console log/info in headless mode by @cynthialong0-0 in
-  [#22739](https://github.com/google-gemini/gemini-cli/pull/22739)
-- test(core): install bubblewrap on Linux CI for sandbox integration tests by
-  @ehedlund in [#23583](https://github.com/google-gemini/gemini-cli/pull/23583)
-- docs(reference): split tools table into category sections by @sheikhlimon in
-  [#21516](https://github.com/google-gemini/gemini-cli/pull/21516)
-- fix(browser): detect embedded URLs in query params to prevent allowedDomains
-  bypass by @tony-shi in
-  [#23225](https://github.com/google-gemini/gemini-cli/pull/23225)
-- fix(browser): add proxy bypass constraint to domain restriction system prompt
-  by @tony-shi in
-  [#23229](https://github.com/google-gemini/gemini-cli/pull/23229)
-- fix(policy): relax write_file argsPattern in plan mode to allow paths without
-  session ID by @Adib234 in
-  [#23695](https://github.com/google-gemini/gemini-cli/pull/23695)
-- docs: fix grammar in CONTRIBUTING and numbering in sandbox docs by
-  @splint-disk-8i in
-  [#23448](https://github.com/google-gemini/gemini-cli/pull/23448)
-- fix(acp): allow attachments by adding a permission prompt by @sripasg in
-  [#23680](https://github.com/google-gemini/gemini-cli/pull/23680)
-- fix(core): thread AbortSignal to chat compression requests (#20405) by
-  @SH20RAJ in [#20778](https://github.com/google-gemini/gemini-cli/pull/20778)
-- feat(core): implement Windows sandbox dynamic expansion Phase 1 and 2.1 by
-  @scidomino in [#23691](https://github.com/google-gemini/gemini-cli/pull/23691)
-- Add note about root privileges in sandbox docs by @diodesign in
-  [#23314](https://github.com/google-gemini/gemini-cli/pull/23314)
-- docs(core): document agent_card_json string literal options for remote agents
-  by @adamfweidman in
-  [#23797](https://github.com/google-gemini/gemini-cli/pull/23797)
-- fix(cli): resolve TTY hang on headless environments by unconditionally
-  resuming process.stdin before React Ink launch by @cocosheng-g in
-  [#23673](https://github.com/google-gemini/gemini-cli/pull/23673)
-- fix(ui): cleanup estimated string length hacks in composer by @keithguerin in
-  [#23694](https://github.com/google-gemini/gemini-cli/pull/23694)
-- feat(browser): dynamically discover read-only tools by @cynthialong0-0 in
-  [#23805](https://github.com/google-gemini/gemini-cli/pull/23805)
-- docs: clarify policy requirement for `general.plan.directory` in settings
-  schema by @jerop in
-  [#23784](https://github.com/google-gemini/gemini-cli/pull/23784)
-- Revert "perf(cli): optimize --version startup time (#23671)" by @scidomino in
-  [#23812](https://github.com/google-gemini/gemini-cli/pull/23812)
-- don't silence errors from wombat by @scidomino in
-  [#23822](https://github.com/google-gemini/gemini-cli/pull/23822)
-- fix(ui): prevent escape key from cancelling requests in shell mode by
-  @PrasannaPal21 in
-  [#21245](https://github.com/google-gemini/gemini-cli/pull/21245)
-- Changelog for v0.36.0-preview.0 by @gemini-cli-robot in
-  [#23702](https://github.com/google-gemini/gemini-cli/pull/23702)
-- feat(core,ui): Add experiment-gated support for gemini flash 3.1 lite by
-  @chrstnb in [#23794](https://github.com/google-gemini/gemini-cli/pull/23794)
-- Changelog for v0.36.0-preview.3 by @gemini-cli-robot in
-  [#23827](https://github.com/google-gemini/gemini-cli/pull/23827)
-- new linting check: github-actions-pinning by @alisa-alisa in
-  [#23808](https://github.com/google-gemini/gemini-cli/pull/23808)
-- fix(cli): show helpful guidance when no skills are available by @Niralisj in
-  [#23785](https://github.com/google-gemini/gemini-cli/pull/23785)
-- fix: Chat logs and errors handle tail tool calls correctly by @googlestrobe in
-  [#22460](https://github.com/google-gemini/gemini-cli/pull/22460)
-- Don't try removing a tag from a non-existent release. by @scidomino in
-  [#23830](https://github.com/google-gemini/gemini-cli/pull/23830)
-- fix(cli): allow ask question dialog to take full window height by @jacob314 in
-  [#23693](https://github.com/google-gemini/gemini-cli/pull/23693)
-- fix(core): strip leading underscores from error types in telemetry by
-  @yunaseoul in [#23824](https://github.com/google-gemini/gemini-cli/pull/23824)
-- Changelog for v0.35.0 by @gemini-cli-robot in
-  [#23819](https://github.com/google-gemini/gemini-cli/pull/23819)
-- feat(evals): add reliability harvester and 500/503 retry support by
-  @alisa-alisa in
-  [#23626](https://github.com/google-gemini/gemini-cli/pull/23626)
-- feat(sandbox): dynamic Linux sandbox expansion and worktree support by @galz10
-  in [#23692](https://github.com/google-gemini/gemini-cli/pull/23692)
-- Merge examples of use into quickstart documentation by @diodesign in
-  [#23319](https://github.com/google-gemini/gemini-cli/pull/23319)
-- fix(cli): prioritize primary name matches in slash command search by @sehoon38
-  in [#23850](https://github.com/google-gemini/gemini-cli/pull/23850)
-- Changelog for v0.35.1 by @gemini-cli-robot in
-  [#23840](https://github.com/google-gemini/gemini-cli/pull/23840)
-- fix(browser): keep input blocker active across navigations by @kunal-10-cloud
-  in [#22562](https://github.com/google-gemini/gemini-cli/pull/22562)
-- feat(core): new skill to look for duplicated code while reviewing PRs by
-  @devr0306 in [#23704](https://github.com/google-gemini/gemini-cli/pull/23704)
-- fix(core): replace hardcoded non-interactive ASK_USER denial with explicit
-  policy rules by @ruomengz in
-  [#23668](https://github.com/google-gemini/gemini-cli/pull/23668)
-- fix(plan): after exiting plan mode switches model to a flash model by @Adib234
-  in [#23885](https://github.com/google-gemini/gemini-cli/pull/23885)
-- feat(gcp): add development worker infrastructure by @mattKorwel in
-  [#23814](https://github.com/google-gemini/gemini-cli/pull/23814)
-- fix(a2a-server): A2A server should execute ask policies in interactive mode by
-  @kschaab in [#23831](https://github.com/google-gemini/gemini-cli/pull/23831)
-- feat(core): define TrajectoryProvider interface by @sehoon38 in
-  [#23050](https://github.com/google-gemini/gemini-cli/pull/23050)
-- Docs: Update quotas and pricing by @jkcinouye in
-  [#23835](https://github.com/google-gemini/gemini-cli/pull/23835)
-- fix(core): allow disabling environment variable redaction by @galz10 in
-  [#23927](https://github.com/google-gemini/gemini-cli/pull/23927)
-- feat(cli): enable notifications cross-platform via terminal bell fallback by
-  @genneth in [#21618](https://github.com/google-gemini/gemini-cli/pull/21618)
-- feat(sandbox): implement secret visibility lockdown for env files by
-  @DavidAPierce in
-  [#23712](https://github.com/google-gemini/gemini-cli/pull/23712)
-- fix(core): remove shell outputChunks buffer caching to prevent memory bloat
-  and sanitize prompt input by @spencer426 in
-  [#23751](https://github.com/google-gemini/gemini-cli/pull/23751)
-- feat(core): implement persistent browser session management by @kunal-10-cloud
-  in [#21306](https://github.com/google-gemini/gemini-cli/pull/21306)
-- refactor(core): delegate sandbox denial parsing to SandboxManager by
-  @scidomino in [#23928](https://github.com/google-gemini/gemini-cli/pull/23928)
-- dep(update) Update Ink version to 6.5.0 by @jacob314 in
-  [#23843](https://github.com/google-gemini/gemini-cli/pull/23843)
-- Docs: Update 'docs-writer' skill for relative links by @jkcinouye in
-  [#21463](https://github.com/google-gemini/gemini-cli/pull/21463)
-- Changelog for v0.36.0-preview.4 by @gemini-cli-robot in
-  [#23935](https://github.com/google-gemini/gemini-cli/pull/23935)
-- fix(acp): Update allow approval policy flow for ACP clients to fix config
-  persistence and compatible with TUI by @sripasg in
-  [#23818](https://github.com/google-gemini/gemini-cli/pull/23818)
-- Changelog for v0.35.2 by @gemini-cli-robot in
-  [#23960](https://github.com/google-gemini/gemini-cli/pull/23960)
-- ACP integration documents by @g-samroberts in
-  [#22254](https://github.com/google-gemini/gemini-cli/pull/22254)
-- fix(core): explicitly set error names to avoid bundling renaming issues by
-  @yunaseoul in [#23913](https://github.com/google-gemini/gemini-cli/pull/23913)
-- feat(core): subagent isolation and cleanup hardening by @abhipatel12 in
-  [#23903](https://github.com/google-gemini/gemini-cli/pull/23903)
-- disable extension-reload test by @scidomino in
-  [#24018](https://github.com/google-gemini/gemini-cli/pull/24018)
-- feat(core): add forbiddenPaths to GlobalSandboxOptions and refactor
-  createSandboxManager by @ehedlund in
-  [#23936](https://github.com/google-gemini/gemini-cli/pull/23936)
-- refactor(core): improve ignore resolution and fix directory-matching bug by
-  @ehedlund in [#23816](https://github.com/google-gemini/gemini-cli/pull/23816)
-- revert(core): support custom base URL via env vars by @spencer426 in
-  [#23976](https://github.com/google-gemini/gemini-cli/pull/23976)
-- Increase memory limited for eslint. by @jacob314 in
-  [#24022](https://github.com/google-gemini/gemini-cli/pull/24022)
-- fix(acp): prevent crash on empty response in ACP mode by @sripasg in
-  [#23952](https://github.com/google-gemini/gemini-cli/pull/23952)
-- feat(core): Land `AgentHistoryProvider`. by @joshualitt in
-  [#23978](https://github.com/google-gemini/gemini-cli/pull/23978)
-- fix(core): switch to subshells for shell tool wrapping to fix heredocs and
-  edge cases by @abhipatel12 in
-  [#24024](https://github.com/google-gemini/gemini-cli/pull/24024)
-- Debug command. by @jacob314 in
-  [#23851](https://github.com/google-gemini/gemini-cli/pull/23851)
-- Changelog for v0.36.0-preview.5 by @gemini-cli-robot in
-  [#24046](https://github.com/google-gemini/gemini-cli/pull/24046)
-- Fix test flakes by globally mocking ink-spinner by @jacob314 in
-  [#24044](https://github.com/google-gemini/gemini-cli/pull/24044)
-- Enable network access in sandbox configuration by @galz10 in
-  [#24055](https://github.com/google-gemini/gemini-cli/pull/24055)
-- feat(context): add configurable memoryBoundaryMarkers setting by @SandyTao520
-  in [#24020](https://github.com/google-gemini/gemini-cli/pull/24020)
-- feat(core): implement windows sandbox expansion and denial detection by
-  @scidomino in [#24027](https://github.com/google-gemini/gemini-cli/pull/24027)
-- fix(core): resolve ACP Operation Aborted Errors in grep_search by @ivanporty
-  in [#23821](https://github.com/google-gemini/gemini-cli/pull/23821)
-- fix(hooks): prevent SessionEnd from firing twice in non-interactive mode by
-  @krishdef7 in [#22139](https://github.com/google-gemini/gemini-cli/pull/22139)
-- Re-word intro to Gemini 3 page. by @g-samroberts in
-  [#24069](https://github.com/google-gemini/gemini-cli/pull/24069)
-- fix(cli): resolve layout contention and flashing loop in StatusRow by
-  @keithguerin in
-  [#24065](https://github.com/google-gemini/gemini-cli/pull/24065)
-- fix(sandbox): implement Windows Mandatory Integrity Control for GeminiSandbox
-  by @galz10 in [#24057](https://github.com/google-gemini/gemini-cli/pull/24057)
-- feat(core): implement tool-based topic grouping (Chapters) by @Abhijit-2592 in
-  [#23150](https://github.com/google-gemini/gemini-cli/pull/23150)
-- feat(cli): support 'tab to queue' for messages while generating by @gundermanc
-  in [#24052](https://github.com/google-gemini/gemini-cli/pull/24052)
-- feat(core): agnostic background task UI with CompletionBehavior by
-  @adamfweidman in
-  [#22740](https://github.com/google-gemini/gemini-cli/pull/22740)
-- UX for topic narration tool by @gundermanc in
-  [#24079](https://github.com/google-gemini/gemini-cli/pull/24079)
-- fix: shellcheck warnings in scripts by @scidomino in
-  [#24035](https://github.com/google-gemini/gemini-cli/pull/24035)
-- test(evals): add comprehensive subagent delegation evaluations by @abhipatel12
-  in [#24132](https://github.com/google-gemini/gemini-cli/pull/24132)
-- fix(a2a-server): prioritize ADC before evaluating headless constraints for
-  auth initialization by @spencer426 in
-  [#23614](https://github.com/google-gemini/gemini-cli/pull/23614)
-- Text can be added after /plan command by @rambleraptor in
-  [#22833](https://github.com/google-gemini/gemini-cli/pull/22833)
-- fix(cli): resolve missing F12 logs via global console store by @scidomino in
-  [#24235](https://github.com/google-gemini/gemini-cli/pull/24235)
-- fix broken tests by @scidomino in
-  [#24279](https://github.com/google-gemini/gemini-cli/pull/24279)
-- fix(evals): add update_topic behavioral eval by @gundermanc in
-  [#24223](https://github.com/google-gemini/gemini-cli/pull/24223)
-- feat(core): Unified Context Management and Tool Distillation. by @joshualitt
-  in [#24157](https://github.com/google-gemini/gemini-cli/pull/24157)
-- Default enable narration for the team. by @gundermanc in
-  [#24224](https://github.com/google-gemini/gemini-cli/pull/24224)
-- fix(core): ensure default agents provide tools and use model-specific schemas
-  by @abhipatel12 in
-  [#24268](https://github.com/google-gemini/gemini-cli/pull/24268)
-- feat(cli): show Flash Lite Preview model regardless of user tier by @sehoon38
-  in [#23904](https://github.com/google-gemini/gemini-cli/pull/23904)
-- feat(cli): implement compact tool output by @jwhelangoog in
-  [#20974](https://github.com/google-gemini/gemini-cli/pull/20974)
-- Add security settings for tool sandboxing by @galz10 in
-  [#23923](https://github.com/google-gemini/gemini-cli/pull/23923)
-- chore(test-utils): switch integration tests to use PREVIEW_GEMINI_MODEL by
-  @sehoon38 in [#24276](https://github.com/google-gemini/gemini-cli/pull/24276)
-- feat(core): enable topic update narration for legacy models by @Abhijit-2592
-  in [#24241](https://github.com/google-gemini/gemini-cli/pull/24241)
-- feat(core): add project-level memory scope to save_memory tool by @SandyTao520
-  in [#24161](https://github.com/google-gemini/gemini-cli/pull/24161)
-- test(integration): fix plan mode write denial test false positive by @sehoon38
-  in [#24299](https://github.com/google-gemini/gemini-cli/pull/24299)
-- feat(plan): support `Plan` mode in untrusted folders by @Adib234 in
-  [#17586](https://github.com/google-gemini/gemini-cli/pull/17586)
-- fix(core): enable mid-stream retries for all models and re-enable compression
-  test by @sehoon38 in
-  [#24302](https://github.com/google-gemini/gemini-cli/pull/24302)
-- Changelog for v0.36.0-preview.6 by @gemini-cli-robot in
-  [#24082](https://github.com/google-gemini/gemini-cli/pull/24082)
-- Changelog for v0.35.3 by @gemini-cli-robot in
-  [#24083](https://github.com/google-gemini/gemini-cli/pull/24083)
-- feat(cli): add auth info to footer by @sehoon38 in
-  [#24042](https://github.com/google-gemini/gemini-cli/pull/24042)
-- fix(browser): reset action counter for each agent session and let it ignore
-  internal actions by @cynthialong0-0 in
-  [#24228](https://github.com/google-gemini/gemini-cli/pull/24228)
-- feat(plan): promote planning feature to stable by @ruomengz in
-  [#24282](https://github.com/google-gemini/gemini-cli/pull/24282)
-- fix(browser): terminate subagent immediately on domain restriction violations
-  by @gsquared94 in
-  [#24313](https://github.com/google-gemini/gemini-cli/pull/24313)
-- feat(cli): add UI to update extensions by @ruomengz in
-  [#23682](https://github.com/google-gemini/gemini-cli/pull/23682)
-- Fix(browser): terminate immediately for "browser is already running" error by
-  @cynthialong0-0 in
-  [#24233](https://github.com/google-gemini/gemini-cli/pull/24233)
-- docs: Add 'plan' option to approval mode in CLI reference by @YifanRuan in
-  [#24134](https://github.com/google-gemini/gemini-cli/pull/24134)
-- fix(core): batch macOS seatbelt rules into a profile file to prevent ARG_MAX
-  errors by @ehedlund in
-  [#24255](https://github.com/google-gemini/gemini-cli/pull/24255)
-- fix(core): fix race condition between browser agent and main closing process
-  by @cynthialong0-0 in
-  [#24340](https://github.com/google-gemini/gemini-cli/pull/24340)
-- perf(build): optimize build scripts for parallel execution and remove
-  redundant checks by @sehoon38 in
-  [#24307](https://github.com/google-gemini/gemini-cli/pull/24307)
-- ci: install bubblewrap on Linux for release workflows by @ehedlund in
-  [#24347](https://github.com/google-gemini/gemini-cli/pull/24347)
-- chore(release): allow bundling for all builds, including stable by @sehoon38
-  in [#24305](https://github.com/google-gemini/gemini-cli/pull/24305)
-- Revert "Add security settings for tool sandboxing" by @jerop in
-  [#24357](https://github.com/google-gemini/gemini-cli/pull/24357)
-- docs: update subagents docs to not be experimental by @abhipatel12 in
-  [#24343](https://github.com/google-gemini/gemini-cli/pull/24343)
-- fix(core): implement **read and **write commands in sandbox managers by
-  @galz10 in [#24283](https://github.com/google-gemini/gemini-cli/pull/24283)
-- don't try to remove tags in dry run by @scidomino in
-  [#24356](https://github.com/google-gemini/gemini-cli/pull/24356)
-- fix(config): disable JIT context loading by default by @SandyTao520 in
-  [#24364](https://github.com/google-gemini/gemini-cli/pull/24364)
-- test(sandbox): add integration test for dynamic permission expansion by
-  @galz10 in [#24359](https://github.com/google-gemini/gemini-cli/pull/24359)
-- docs(policy): remove unsupported mcpName wildcard edge case by @abhipatel12 in
-  [#24133](https://github.com/google-gemini/gemini-cli/pull/24133)
-- docs: fix broken GEMINI.md link in CONTRIBUTING.md by @Panchal-Tirth in
-  [#24182](https://github.com/google-gemini/gemini-cli/pull/24182)
-- feat(core): infrastructure for event-driven subagent history by @abhipatel12
-  in [#23914](https://github.com/google-gemini/gemini-cli/pull/23914)
-- fix(core): resolve Plan Mode deadlock during plan file creation due to sandbox
-  restrictions by @DavidAPierce in
-  [#24047](https://github.com/google-gemini/gemini-cli/pull/24047)
-- fix(core): fix browser agent UX issues and improve E2E test reliability by
-  @gsquared94 in
-  [#24312](https://github.com/google-gemini/gemini-cli/pull/24312)
-- fix(ui): wrap topic and intent fields in TopicMessage by @jwhelangoog in
-  [#24386](https://github.com/google-gemini/gemini-cli/pull/24386)
-- refactor(core): Centralize context management logic into src/context by
-  @joshualitt in
-  [#24380](https://github.com/google-gemini/gemini-cli/pull/24380)
-- fix(core): pin AuthType.GATEWAY to use Gemini 3.1 Pro/Flash Lite by default by
-  @sripasg in [#24375](https://github.com/google-gemini/gemini-cli/pull/24375)
-- feat(ui): add Tokyo Night theme by @danrneal in
-  [#24054](https://github.com/google-gemini/gemini-cli/pull/24054)
-- fix(cli): refactor test config loading and mock debugLogger in test-setup by
-  @mattKorwel in
-  [#24389](https://github.com/google-gemini/gemini-cli/pull/24389)
-- Set memoryManager to false in settings.json by @mattKorwel in
-  [#24393](https://github.com/google-gemini/gemini-cli/pull/24393)
-- ink 6.6.3 by @jacob314 in
-  [#24372](https://github.com/google-gemini/gemini-cli/pull/24372)
-- fix(core): resolve subagent chat recording gaps and directory inheritance by
+- fix(patch): cherry-pick 050c303 to release/v0.38.0-pr-25317 to patch version
+  v0.38.0 and create version 0.38.1 by @gemini-cli-robot in
+  [#25466](https://github.com/google-gemini/gemini-cli/pull/25466)
+- fix(cli): refresh slash command list after /skills reload by @NTaylorMullen in
+  [#24454](https://github.com/google-gemini/gemini-cli/pull/24454)
+- Update README.md for links. by @g-samroberts in
+  [#22759](https://github.com/google-gemini/gemini-cli/pull/22759)
+- fix(core): ensure complete_task tool calls are recorded in chat history by
   @abhipatel12 in
-  [#24368](https://github.com/google-gemini/gemini-cli/pull/24368)
-- fix(cli): cap shell output at 10 MB to prevent RangeError crash by @ProthamD
-  in [#24168](https://github.com/google-gemini/gemini-cli/pull/24168)
-- feat(plan): conditionally add enter/exit plan mode tools based on current mode
-  by @ruomengz in
-  [#24378](https://github.com/google-gemini/gemini-cli/pull/24378)
-- feat(core): prioritize discussion before formal plan approval by @jerop in
-  [#24423](https://github.com/google-gemini/gemini-cli/pull/24423)
-- fix(ui): add accelerated scrolling on alternate buffer mode by @devr0306 in
-  [#23940](https://github.com/google-gemini/gemini-cli/pull/23940)
-- feat(core): populate sandbox forbidden paths with project ignore file contents
-  by @ehedlund in
-  [#24038](https://github.com/google-gemini/gemini-cli/pull/24038)
-- fix(core): ensure blue border overlay and input blocker to act correctly
-  depending on browser agent activities by @cynthialong0-0 in
-  [#24385](https://github.com/google-gemini/gemini-cli/pull/24385)
-- fix(ui): removed additional vertical padding for tables by @devr0306 in
-  [#24381](https://github.com/google-gemini/gemini-cli/pull/24381)
-- fix(build): upload full bundle directory archive to GitHub releases by
-  @sehoon38 in [#24403](https://github.com/google-gemini/gemini-cli/pull/24403)
-- fix(build): wire bundle:browser-mcp into bundle pipeline by @gsquared94 in
-  [#24424](https://github.com/google-gemini/gemini-cli/pull/24424)
-- feat(browser): add sandbox-aware browser agent initialization by @gsquared94
-  in [#24419](https://github.com/google-gemini/gemini-cli/pull/24419)
-- feat(core): enhance tracker task schemas for detailed titles and descriptions
-  by @anj-s in [#23902](https://github.com/google-gemini/gemini-cli/pull/23902)
-- refactor(core): Unified context management settings schema by @joshualitt in
-  [#24391](https://github.com/google-gemini/gemini-cli/pull/24391)
-- feat(core): update browser agent prompt to check open pages first when
-  bringing up by @cynthialong0-0 in
-  [#24431](https://github.com/google-gemini/gemini-cli/pull/24431)
-- fix(acp) refactor(core,cli): centralize model discovery logic in
-  ModelConfigService by @sripasg in
-  [#24392](https://github.com/google-gemini/gemini-cli/pull/24392)
-- Changelog for v0.36.0-preview.7 by @gemini-cli-robot in
-  [#24346](https://github.com/google-gemini/gemini-cli/pull/24346)
-- fix: update task tracker storage location in system prompt by @anj-s in
-  [#24034](https://github.com/google-gemini/gemini-cli/pull/24034)
-- feat(browser): supersede stale snapshots to reclaim context-window tokens by
+  [#24437](https://github.com/google-gemini/gemini-cli/pull/24437)
+- feat(policy): explicitly allow web_fetch in plan mode with ask_user by
+  @Adib234 in [#24456](https://github.com/google-gemini/gemini-cli/pull/24456)
+- fix(core): refactor linux sandbox to fix ARG_MAX crashes by @ehedlund in
+  [#24286](https://github.com/google-gemini/gemini-cli/pull/24286)
+- feat(config): add experimental.adk.agentSessionNoninteractiveEnabled setting
+  by @adamfweidman in
+  [#24439](https://github.com/google-gemini/gemini-cli/pull/24439)
+- Changelog for v0.36.0-preview.8 by @gemini-cli-robot in
+  [#24453](https://github.com/google-gemini/gemini-cli/pull/24453)
+- feat(cli): change default loadingPhrases to 'off' to hide tips by @keithguerin
+  in [#24342](https://github.com/google-gemini/gemini-cli/pull/24342)
+- fix(cli): ensure agent stops when all declinable tools are cancelled by
+  @NTaylorMullen in
+  [#24479](https://github.com/google-gemini/gemini-cli/pull/24479)
+- fix(core): enhance sandbox usability and fix build error by @galz10 in
+  [#24460](https://github.com/google-gemini/gemini-cli/pull/24460)
+- Terminal Serializer Optimization by @jacob314 in
+  [#24485](https://github.com/google-gemini/gemini-cli/pull/24485)
+- Auto configure memory. by @jacob314 in
+  [#24474](https://github.com/google-gemini/gemini-cli/pull/24474)
+- Unused error variables in catch block are not allowed by @alisa-alisa in
+  [#24487](https://github.com/google-gemini/gemini-cli/pull/24487)
+- feat(core): add background memory service for skill extraction by @SandyTao520
+  in [#24274](https://github.com/google-gemini/gemini-cli/pull/24274)
+- feat: implement high-signal PR regression check for evaluations by
+  @alisa-alisa in
+  [#23937](https://github.com/google-gemini/gemini-cli/pull/23937)
+- Fix shell output display by @jacob314 in
+  [#24490](https://github.com/google-gemini/gemini-cli/pull/24490)
+- fix(ui): resolve unwanted vertical spacing around various tool output
+  treatments by @jwhelangoog in
+  [#24449](https://github.com/google-gemini/gemini-cli/pull/24449)
+- revert(cli): bring back input box and footer visibility in copy mode by
+  @sehoon38 in [#24504](https://github.com/google-gemini/gemini-cli/pull/24504)
+- fix(cli): prevent crash in AnsiOutputText when handling non-array data by
+  @sehoon38 in [#24498](https://github.com/google-gemini/gemini-cli/pull/24498)
+- feat(cli): support default values for environment variables by @ruomengz in
+  [#24469](https://github.com/google-gemini/gemini-cli/pull/24469)
+- Implement background process monitoring and inspection tools by @cocosheng-g
+  in [#23799](https://github.com/google-gemini/gemini-cli/pull/23799)
+- docs(browser-agent): update stale browser agent documentation by @gsquared94
+  in [#24463](https://github.com/google-gemini/gemini-cli/pull/24463)
+- fix: enable browser_agent in integration tests and add localhost fixture tests
+  by @gsquared94 in
+  [#24523](https://github.com/google-gemini/gemini-cli/pull/24523)
+- fix(browser): handle computer-use model detection for analyze_screenshot by
   @gsquared94 in
-  [#24440](https://github.com/google-gemini/gemini-cli/pull/24440)
-- docs(core): add subagent tool isolation draft doc by @akh64bit in
-  [#23275](https://github.com/google-gemini/gemini-cli/pull/23275)
-- fix(patch): cherry-pick 64c928f to release/v0.37.0-preview.0-pr-23257 to patch
-  version v0.37.0-preview.0 and create version 0.37.0-preview.1 by
-  @gemini-cli-robot in
-  [#24561](https://github.com/google-gemini/gemini-cli/pull/24561)
-- fix(patch): cherry-pick cb7f7d6 to release/v0.37.0-preview.1-pr-24342 to patch
-  version v0.37.0-preview.1 and create version 0.37.0-preview.2 by
-  @gemini-cli-robot in
-  [#24842](https://github.com/google-gemini/gemini-cli/pull/24842)
+  [#24502](https://github.com/google-gemini/gemini-cli/pull/24502)
+- feat(core): Land ContextCompressionService by @joshualitt in
+  [#24483](https://github.com/google-gemini/gemini-cli/pull/24483)
+- feat(core): scope subagent workspace directories via AsyncLocalStorage by
+  @SandyTao520 in
+  [#24445](https://github.com/google-gemini/gemini-cli/pull/24445)
+- Update ink version to 6.6.7 by @jacob314 in
+  [#24514](https://github.com/google-gemini/gemini-cli/pull/24514)
+- fix(acp): handle all InvalidStreamError types gracefully in prompt by @sripasg
+  in [#24540](https://github.com/google-gemini/gemini-cli/pull/24540)
+- Fix crash when vim editor is not found in PATH on Windows by
+  @Nagajyothi-tammisetti in
+  [#22423](https://github.com/google-gemini/gemini-cli/pull/22423)
+- fix(core): move project memory dir under tmp directory by @SandyTao520 in
+  [#24542](https://github.com/google-gemini/gemini-cli/pull/24542)
+- Enable 'Other' option for yesno question type by @ruomengz in
+  [#24545](https://github.com/google-gemini/gemini-cli/pull/24545)
+- fix(cli): clear stale retry/loading state after cancellation (#21096) by
+  @Aaxhirrr in [#21960](https://github.com/google-gemini/gemini-cli/pull/21960)
+- Changelog for v0.37.0-preview.0 by @gemini-cli-robot in
+  [#24464](https://github.com/google-gemini/gemini-cli/pull/24464)
+- feat(core): implement context-aware persistent policy approvals by @jerop in
+  [#23257](https://github.com/google-gemini/gemini-cli/pull/23257)
+- docs: move agent disabling instructions and update remote agent status by
+  @jackwotherspoon in
+  [#24559](https://github.com/google-gemini/gemini-cli/pull/24559)
+- feat(cli): migrate nonInteractiveCli to LegacyAgentSession by @adamfweidman in
+  [#22987](https://github.com/google-gemini/gemini-cli/pull/22987)
+- fix(core): unsafe type assertions in Core File System #19712 by
+  @aniketsaurav18 in
+  [#19739](https://github.com/google-gemini/gemini-cli/pull/19739)
+- fix(ui): hide model quota in /stats and refactor quota display by @danzaharia1
+  in [#24206](https://github.com/google-gemini/gemini-cli/pull/24206)
+- Changelog for v0.36.0 by @gemini-cli-robot in
+  [#24558](https://github.com/google-gemini/gemini-cli/pull/24558)
+- Changelog for v0.37.0-preview.1 by @gemini-cli-robot in
+  [#24568](https://github.com/google-gemini/gemini-cli/pull/24568)
+- docs: add missing .md extensions to internal doc links by @ishaan-arora-1 in
+  [#24145](https://github.com/google-gemini/gemini-cli/pull/24145)
+- fix(ui): fixed table styling by @devr0306 in
+  [#24565](https://github.com/google-gemini/gemini-cli/pull/24565)
+- fix(core): pass includeDirectories to sandbox configuration by @galz10 in
+  [#24573](https://github.com/google-gemini/gemini-cli/pull/24573)
+- feat(ui): enable "TerminalBuffer" mode to solve flicker by @jacob314 in
+  [#24512](https://github.com/google-gemini/gemini-cli/pull/24512)
+- docs: clarify release coordination by @scidomino in
+  [#24575](https://github.com/google-gemini/gemini-cli/pull/24575)
+- fix(core): remove broken PowerShell translation and fix native \_\_write in
+  Windows sandbox by @scidomino in
+  [#24571](https://github.com/google-gemini/gemini-cli/pull/24571)
+- Add instructions for how to start react in prod and force react to prod mode
+  by @jacob314 in
+  [#24590](https://github.com/google-gemini/gemini-cli/pull/24590)
+- feat(cli): minimalist sandbox status labels by @galz10 in
+  [#24582](https://github.com/google-gemini/gemini-cli/pull/24582)
+- Feat/browser agent metrics by @kunal-10-cloud in
+  [#24210](https://github.com/google-gemini/gemini-cli/pull/24210)
+- test: fix Windows CI execution and resolve exposed platform failures by
+  @ehedlund in [#24476](https://github.com/google-gemini/gemini-cli/pull/24476)
+- feat(core,cli): prioritize summary for topics (#24608) by @Abhijit-2592 in
+  [#24609](https://github.com/google-gemini/gemini-cli/pull/24609)
+- show color by @jacob314 in
+  [#24613](https://github.com/google-gemini/gemini-cli/pull/24613)
+- feat(cli): enable compact tool output by default (#24509) by @jwhelangoog in
+  [#24510](https://github.com/google-gemini/gemini-cli/pull/24510)
+- fix(core): inject skill system instructions into subagent prompts if activated
+  by @abhipatel12 in
+  [#24620](https://github.com/google-gemini/gemini-cli/pull/24620)
+- fix(core): improve windows sandbox reliability and fix integration tests by
+  @ehedlund in [#24480](https://github.com/google-gemini/gemini-cli/pull/24480)
+- fix(core): ensure sandbox approvals are correctly persisted and matched for
+  proactive expansions by @galz10 in
+  [#24577](https://github.com/google-gemini/gemini-cli/pull/24577)
+- feat(cli) Scrollbar for input prompt by @jacob314 in
+  [#21992](https://github.com/google-gemini/gemini-cli/pull/21992)
+- Do not run pr-eval workflow when no steering changes detected by @alisa-alisa
+  in [#24621](https://github.com/google-gemini/gemini-cli/pull/24621)
+- Fix restoration of topic headers. by @gundermanc in
+  [#24650](https://github.com/google-gemini/gemini-cli/pull/24650)
+- feat(core): discourage update topic tool for simple tasks by @Samee24 in
+  [#24640](https://github.com/google-gemini/gemini-cli/pull/24640)
+- fix(core): ensure global temp directory is always in sandbox allowed paths by
+  @galz10 in [#24638](https://github.com/google-gemini/gemini-cli/pull/24638)
+- fix(core): detect uninitialized lines by @jacob314 in
+  [#24646](https://github.com/google-gemini/gemini-cli/pull/24646)
+- docs: update sandboxing documentation and toolSandboxing settings by @galz10
+  in [#24655](https://github.com/google-gemini/gemini-cli/pull/24655)
+- feat(cli): enhance tool confirmation UI and selection layout by @galz10 in
+  [#24376](https://github.com/google-gemini/gemini-cli/pull/24376)
+- feat(acp): add support for `/about` command by @sripasg in
+  [#24649](https://github.com/google-gemini/gemini-cli/pull/24649)
+- feat(cli): add role specific metrics to /stats by @cynthialong0-0 in
+  [#24659](https://github.com/google-gemini/gemini-cli/pull/24659)
+- split context by @jacob314 in
+  [#24623](https://github.com/google-gemini/gemini-cli/pull/24623)
+- fix(cli): remove -S from shebang to fix Windows and BSD execution by
+  @scidomino in [#24756](https://github.com/google-gemini/gemini-cli/pull/24756)
+- Fix issue where topic headers can be posted back to back by @gundermanc in
+  [#24759](https://github.com/google-gemini/gemini-cli/pull/24759)
+- fix(core): handle partial llm_request in BeforeModel hook override by
+  @krishdef7 in [#22326](https://github.com/google-gemini/gemini-cli/pull/22326)
+- fix(ui): improve narration suppression and reduce flicker by @gundermanc in
+  [#24635](https://github.com/google-gemini/gemini-cli/pull/24635)
+- fix(ui): fixed auth race condition causing logo to flicker by @devr0306 in
+  [#24652](https://github.com/google-gemini/gemini-cli/pull/24652)
+- fix(browser): remove premature browser cleanup after subagent invocation by
+  @gsquared94 in
+  [#24753](https://github.com/google-gemini/gemini-cli/pull/24753)
+- Revert "feat(core,cli): prioritize summary for topics (#24608)" by
+  @Abhijit-2592 in
+  [#24777](https://github.com/google-gemini/gemini-cli/pull/24777)
+- relax tool sandboxing overrides for plan mode to match defaults. by
+  @DavidAPierce in
+  [#24762](https://github.com/google-gemini/gemini-cli/pull/24762)
+- fix(cli): respect global environment variable allowlist by @scidomino in
+  [#24767](https://github.com/google-gemini/gemini-cli/pull/24767)
+- fix(cli): ensure skills list outputs to stdout in non-interactive environments
+  by @spencer426 in
+  [#24566](https://github.com/google-gemini/gemini-cli/pull/24566)
+- Add an eval for and fix unsafe cloning behavior. by @gundermanc in
+  [#24457](https://github.com/google-gemini/gemini-cli/pull/24457)
+- fix(policy): allow complete_task in plan mode by @abhipatel12 in
+  [#24771](https://github.com/google-gemini/gemini-cli/pull/24771)
+- feat(telemetry): add browser agent clearcut metrics by @gsquared94 in
+  [#24688](https://github.com/google-gemini/gemini-cli/pull/24688)
+- feat(cli): support selective topic expansion and click-to-expand by
+  @Abhijit-2592 in
+  [#24793](https://github.com/google-gemini/gemini-cli/pull/24793)
+- temporarily disable sandbox integration test on windows by @ehedlund in
+  [#24786](https://github.com/google-gemini/gemini-cli/pull/24786)
+- Remove flakey test by @scidomino in
+  [#24837](https://github.com/google-gemini/gemini-cli/pull/24837)
+- Alisa/approve button by @alisa-alisa in
+  [#24645](https://github.com/google-gemini/gemini-cli/pull/24645)
+- feat(hooks): display hook system messages in UI by @mbleigh in
+  [#24616](https://github.com/google-gemini/gemini-cli/pull/24616)
+- fix(core): propagate BeforeModel hook model override end-to-end by @krishdef7
+  in [#24784](https://github.com/google-gemini/gemini-cli/pull/24784)
+- chore: fix formatting for behavioral eval skill reference file by @abhipatel12
+  in [#24846](https://github.com/google-gemini/gemini-cli/pull/24846)
+- fix: use directory junctions on Windows for skill linking by @enjoykumawat in
+  [#24823](https://github.com/google-gemini/gemini-cli/pull/24823)
+- fix(cli): prevent multiple banner increments on remount by @sehoon38 in
+  [#24843](https://github.com/google-gemini/gemini-cli/pull/24843)
+- feat(acp): add /help command by @sripasg in
+  [#24839](https://github.com/google-gemini/gemini-cli/pull/24839)
+- fix(core): remove tmux alternate buffer warning by @jackwotherspoon in
+  [#24852](https://github.com/google-gemini/gemini-cli/pull/24852)
+- Improve sandbox error matching and caching by @DavidAPierce in
+  [#24550](https://github.com/google-gemini/gemini-cli/pull/24550)
+- feat(core): add agent protocol UI types and experimental flag by @mbleigh in
+  [#24275](https://github.com/google-gemini/gemini-cli/pull/24275)
+- feat(core): use experiment flags for default fetch timeouts by @yunaseoul in
+  [#24261](https://github.com/google-gemini/gemini-cli/pull/24261)
+- Revert "fix(ui): improve narration suppression and reduce flicker (#2… by
+  @gundermanc in
+  [#24857](https://github.com/google-gemini/gemini-cli/pull/24857)
+- refactor(cli): remove duplication in interactive shell awaiting input hint by
+  @JayadityaGit in
+  [#24801](https://github.com/google-gemini/gemini-cli/pull/24801)
+- refactor(core): make LegacyAgentSession dependencies optional by @mbleigh in
+  [#24287](https://github.com/google-gemini/gemini-cli/pull/24287)
+- Changelog for v0.37.0-preview.2 by @gemini-cli-robot in
+  [#24848](https://github.com/google-gemini/gemini-cli/pull/24848)
+- fix(cli): always show shell command description or actual command by @jacob314
+  in [#24774](https://github.com/google-gemini/gemini-cli/pull/24774)
+- Added flag for ept size and increased default size by @devr0306 in
+  [#24859](https://github.com/google-gemini/gemini-cli/pull/24859)
+- fix(core): dispose Scheduler to prevent McpProgress listener leak by
+  @Anjaligarhwal in
+  [#24870](https://github.com/google-gemini/gemini-cli/pull/24870)
+- fix(cli): switch default back to terminalBuffer=false and fix regressions
+  introduced for that mode by @jacob314 in
+  [#24873](https://github.com/google-gemini/gemini-cli/pull/24873)
+- feat(cli): switch to ctrl+g from ctrl-x by @jacob314 in
+  [#24861](https://github.com/google-gemini/gemini-cli/pull/24861)
+- fix: isolate concurrent browser agent instances by @gsquared94 in
+  [#24794](https://github.com/google-gemini/gemini-cli/pull/24794)
+- docs: update MCP server OAuth redirect port documentation by @adamfweidman in
+  [#24844](https://github.com/google-gemini/gemini-cli/pull/24844)
 
 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.36.0...v0.37.1
+https://github.com/google-gemini/gemini-cli/compare/v0.38.0...v0.38.1

docs/changelogs/preview.md

@@ -1,6 +1,6 @@
-# Preview release: v0.38.0-preview.0
+# Preview release: v0.39.0-preview.0
 
-Released: April 08, 2026
+Released: April 14, 2026
 
 Our preview release includes the latest, new, and experimental features. This
 release may not be as stable as our [latest weekly release](latest.md).
@@ -13,256 +13,245 @@ npm install -g @google/gemini-cli@preview
 
 ## Highlights
 
-- **Context Management:** Introduced a Context Compression Service to optimize
-  context window usage and landed a background memory service for skill
-  extraction.
-- **Enhanced Security:** Implemented context-aware persistent policy approvals
-  for smarter tool permissions and enabled `web_fetch` in plan mode with user
-  confirmation.
-- **Workflow Monitoring:** Added background process monitoring and inspection
-  tools for better visibility into long-running tasks.
-- **UI/UX Refinements:** Enhanced the tool confirmation UI, selection layout,
-  and added support for selective topic expansion and click-to-expand.
-- **Core Stability:** Improved sandbox reliability on Linux and Windows,
-  resolved shebang compatibility issues, and fixed various crashes in the CLI
-  and core services.
+- **Refactored Subagents and Unified Tooling:** Consolidate subagent tools into
+  a single `invoke_subagent` tool, removed legacy wrapping tools, and improved
+  turn limits for codebase investigator.
+- **Advanced Memory and Skill Management:** Introduced `/memory` inbox for
+  reviewing extracted skills and added skill patching support, enhancing agent
+  learning and persistence.
+- **Expanded Test and Evaluation Infrastructure:** Added memory and CPU
+  performance integration test harnesses and generalized evaluation
+  infrastructure for better suite organization.
+- **Sandbox and Security Hardening:** Centralized sandbox paths for Linux and
+  macOS, enforced read-only security for async git worktree resolution, and
+  optimized Windows sandbox initialization.
+- **Enhanced CLI UX and UI Stability:** Improved scroll momentum, added a
+  `debugRainbow` setting, and resolved various memory leaks and PTY exhaustion
+  issues for a smoother terminal experience.
 
 ## What's Changed
 
-- fix(cli): refresh slash command list after /skills reload by @NTaylorMullen in
-  [#24454](https://github.com/google-gemini/gemini-cli/pull/24454)
-- Update README.md for links. by @g-samroberts in
-  [#22759](https://github.com/google-gemini/gemini-cli/pull/22759)
-- fix(core): ensure complete_task tool calls are recorded in chat history by
-  @abhipatel12 in
-  [#24437](https://github.com/google-gemini/gemini-cli/pull/24437)
-- feat(policy): explicitly allow web_fetch in plan mode with ask_user by
-  @Adib234 in [#24456](https://github.com/google-gemini/gemini-cli/pull/24456)
-- fix(core): refactor linux sandbox to fix ARG_MAX crashes by @ehedlund in
-  [#24286](https://github.com/google-gemini/gemini-cli/pull/24286)
-- feat(config): add experimental.adk.agentSessionNoninteractiveEnabled setting
-  by @adamfweidman in
-  [#24439](https://github.com/google-gemini/gemini-cli/pull/24439)
-- Changelog for v0.36.0-preview.8 by @gemini-cli-robot in
-  [#24453](https://github.com/google-gemini/gemini-cli/pull/24453)
-- feat(cli): change default loadingPhrases to 'off' to hide tips by @keithguerin
-  in [#24342](https://github.com/google-gemini/gemini-cli/pull/24342)
-- fix(cli): ensure agent stops when all declinable tools are cancelled by
-  @NTaylorMullen in
-  [#24479](https://github.com/google-gemini/gemini-cli/pull/24479)
-- fix(core): enhance sandbox usability and fix build error by @galz10 in
-  [#24460](https://github.com/google-gemini/gemini-cli/pull/24460)
-- Terminal Serializer Optimization by @jacob314 in
-  [#24485](https://github.com/google-gemini/gemini-cli/pull/24485)
-- Auto configure memory. by @jacob314 in
-  [#24474](https://github.com/google-gemini/gemini-cli/pull/24474)
-- Unused error variables in catch block are not allowed by @alisa-alisa in
-  [#24487](https://github.com/google-gemini/gemini-cli/pull/24487)
-- feat(core): add background memory service for skill extraction by @SandyTao520
-  in [#24274](https://github.com/google-gemini/gemini-cli/pull/24274)
-- feat: implement high-signal PR regression check for evaluations by
-  @alisa-alisa in
-  [#23937](https://github.com/google-gemini/gemini-cli/pull/23937)
-- Fix shell output display by @jacob314 in
-  [#24490](https://github.com/google-gemini/gemini-cli/pull/24490)
-- fix(ui): resolve unwanted vertical spacing around various tool output
-  treatments by @jwhelangoog in
-  [#24449](https://github.com/google-gemini/gemini-cli/pull/24449)
-- revert(cli): bring back input box and footer visibility in copy mode by
-  @sehoon38 in [#24504](https://github.com/google-gemini/gemini-cli/pull/24504)
-- fix(cli): prevent crash in AnsiOutputText when handling non-array data by
-  @sehoon38 in [#24498](https://github.com/google-gemini/gemini-cli/pull/24498)
-- feat(cli): support default values for environment variables by @ruomengz in
-  [#24469](https://github.com/google-gemini/gemini-cli/pull/24469)
-- Implement background process monitoring and inspection tools by @cocosheng-g
-  in [#23799](https://github.com/google-gemini/gemini-cli/pull/23799)
-- docs(browser-agent): update stale browser agent documentation by @gsquared94
-  in [#24463](https://github.com/google-gemini/gemini-cli/pull/24463)
-- fix: enable browser_agent in integration tests and add localhost fixture tests
-  by @gsquared94 in
-  [#24523](https://github.com/google-gemini/gemini-cli/pull/24523)
-- fix(browser): handle computer-use model detection for analyze_screenshot by
-  @gsquared94 in
-  [#24502](https://github.com/google-gemini/gemini-cli/pull/24502)
-- feat(core): Land ContextCompressionService by @joshualitt in
-  [#24483](https://github.com/google-gemini/gemini-cli/pull/24483)
-- feat(core): scope subagent workspace directories via AsyncLocalStorage by
+- refactor(plan): simplify policy priorities and consolidate read-only rules by
+  @ruomengz in [#24849](https://github.com/google-gemini/gemini-cli/pull/24849)
+- feat(test-utils): add memory usage integration test harness by @sripasg in
+  [#24876](https://github.com/google-gemini/gemini-cli/pull/24876)
+- feat(memory): add /memory inbox command for reviewing extracted skills by
   @SandyTao520 in
-  [#24445](https://github.com/google-gemini/gemini-cli/pull/24445)
-- Update ink version to 6.6.7 by @jacob314 in
-  [#24514](https://github.com/google-gemini/gemini-cli/pull/24514)
-- fix(acp): handle all InvalidStreamError types gracefully in prompt by @sripasg
-  in [#24540](https://github.com/google-gemini/gemini-cli/pull/24540)
-- Fix crash when vim editor is not found in PATH on Windows by
-  @Nagajyothi-tammisetti in
-  [#22423](https://github.com/google-gemini/gemini-cli/pull/22423)
-- fix(core): move project memory dir under tmp directory by @SandyTao520 in
-  [#24542](https://github.com/google-gemini/gemini-cli/pull/24542)
-- Enable 'Other' option for yesno question type by @ruomengz in
-  [#24545](https://github.com/google-gemini/gemini-cli/pull/24545)
-- fix(cli): clear stale retry/loading state after cancellation (#21096) by
-  @Aaxhirrr in [#21960](https://github.com/google-gemini/gemini-cli/pull/21960)
-- Changelog for v0.37.0-preview.0 by @gemini-cli-robot in
-  [#24464](https://github.com/google-gemini/gemini-cli/pull/24464)
-- feat(core): implement context-aware persistent policy approvals by @jerop in
-  [#23257](https://github.com/google-gemini/gemini-cli/pull/23257)
-- docs: move agent disabling instructions and update remote agent status by
-  @jackwotherspoon in
-  [#24559](https://github.com/google-gemini/gemini-cli/pull/24559)
-- feat(cli): migrate nonInteractiveCli to LegacyAgentSession by @adamfweidman in
-  [#22987](https://github.com/google-gemini/gemini-cli/pull/22987)
-- fix(core): unsafe type assertions in Core File System #19712 by
-  @aniketsaurav18 in
-  [#19739](https://github.com/google-gemini/gemini-cli/pull/19739)
-- fix(ui): hide model quota in /stats and refactor quota display by @danzaharia1
-  in [#24206](https://github.com/google-gemini/gemini-cli/pull/24206)
-- Changelog for v0.36.0 by @gemini-cli-robot in
-  [#24558](https://github.com/google-gemini/gemini-cli/pull/24558)
-- Changelog for v0.37.0-preview.1 by @gemini-cli-robot in
-  [#24568](https://github.com/google-gemini/gemini-cli/pull/24568)
-- docs: add missing .md extensions to internal doc links by @ishaan-arora-1 in
-  [#24145](https://github.com/google-gemini/gemini-cli/pull/24145)
-- fix(ui): fixed table styling by @devr0306 in
-  [#24565](https://github.com/google-gemini/gemini-cli/pull/24565)
-- fix(core): pass includeDirectories to sandbox configuration by @galz10 in
-  [#24573](https://github.com/google-gemini/gemini-cli/pull/24573)
-- feat(ui): enable "TerminalBuffer" mode to solve flicker by @jacob314 in
-  [#24512](https://github.com/google-gemini/gemini-cli/pull/24512)
-- docs: clarify release coordination by @scidomino in
-  [#24575](https://github.com/google-gemini/gemini-cli/pull/24575)
-- fix(core): remove broken PowerShell translation and fix native \_\_write in
-  Windows sandbox by @scidomino in
-  [#24571](https://github.com/google-gemini/gemini-cli/pull/24571)
-- Add instructions for how to start react in prod and force react to prod mode
-  by @jacob314 in
-  [#24590](https://github.com/google-gemini/gemini-cli/pull/24590)
-- feat(cli): minimalist sandbox status labels by @galz10 in
-  [#24582](https://github.com/google-gemini/gemini-cli/pull/24582)
-- Feat/browser agent metrics by @kunal-10-cloud in
-  [#24210](https://github.com/google-gemini/gemini-cli/pull/24210)
-- test: fix Windows CI execution and resolve exposed platform failures by
-  @ehedlund in [#24476](https://github.com/google-gemini/gemini-cli/pull/24476)
-- feat(core,cli): prioritize summary for topics (#24608) by @Abhijit-2592 in
-  [#24609](https://github.com/google-gemini/gemini-cli/pull/24609)
-- show color by @jacob314 in
-  [#24613](https://github.com/google-gemini/gemini-cli/pull/24613)
-- feat(cli): enable compact tool output by default (#24509) by @jwhelangoog in
-  [#24510](https://github.com/google-gemini/gemini-cli/pull/24510)
-- fix(core): inject skill system instructions into subagent prompts if activated
-  by @abhipatel12 in
-  [#24620](https://github.com/google-gemini/gemini-cli/pull/24620)
-- fix(core): improve windows sandbox reliability and fix integration tests by
-  @ehedlund in [#24480](https://github.com/google-gemini/gemini-cli/pull/24480)
-- fix(core): ensure sandbox approvals are correctly persisted and matched for
-  proactive expansions by @galz10 in
-  [#24577](https://github.com/google-gemini/gemini-cli/pull/24577)
-- feat(cli) Scrollbar for input prompt by @jacob314 in
-  [#21992](https://github.com/google-gemini/gemini-cli/pull/21992)
-- Do not run pr-eval workflow when no steering changes detected by @alisa-alisa
-  in [#24621](https://github.com/google-gemini/gemini-cli/pull/24621)
-- Fix restoration of topic headers. by @gundermanc in
-  [#24650](https://github.com/google-gemini/gemini-cli/pull/24650)
-- feat(core): discourage update topic tool for simple tasks by @Samee24 in
-  [#24640](https://github.com/google-gemini/gemini-cli/pull/24640)
-- fix(core): ensure global temp directory is always in sandbox allowed paths by
-  @galz10 in [#24638](https://github.com/google-gemini/gemini-cli/pull/24638)
-- fix(core): detect uninitialized lines by @jacob314 in
-  [#24646](https://github.com/google-gemini/gemini-cli/pull/24646)
-- docs: update sandboxing documentation and toolSandboxing settings by @galz10
-  in [#24655](https://github.com/google-gemini/gemini-cli/pull/24655)
-- feat(cli): enhance tool confirmation UI and selection layout by @galz10 in
-  [#24376](https://github.com/google-gemini/gemini-cli/pull/24376)
-- feat(acp): add support for `/about` command by @sripasg in
-  [#24649](https://github.com/google-gemini/gemini-cli/pull/24649)
-- feat(cli): add role specific metrics to /stats by @cynthialong0-0 in
-  [#24659](https://github.com/google-gemini/gemini-cli/pull/24659)
-- split context by @jacob314 in
-  [#24623](https://github.com/google-gemini/gemini-cli/pull/24623)
-- fix(cli): remove -S from shebang to fix Windows and BSD execution by
-  @scidomino in [#24756](https://github.com/google-gemini/gemini-cli/pull/24756)
-- Fix issue where topic headers can be posted back to back by @gundermanc in
-  [#24759](https://github.com/google-gemini/gemini-cli/pull/24759)
-- fix(core): handle partial llm_request in BeforeModel hook override by
-  @krishdef7 in [#22326](https://github.com/google-gemini/gemini-cli/pull/22326)
-- fix(ui): improve narration suppression and reduce flicker by @gundermanc in
-  [#24635](https://github.com/google-gemini/gemini-cli/pull/24635)
-- fix(ui): fixed auth race condition causing logo to flicker by @devr0306 in
-  [#24652](https://github.com/google-gemini/gemini-cli/pull/24652)
-- fix(browser): remove premature browser cleanup after subagent invocation by
-  @gsquared94 in
-  [#24753](https://github.com/google-gemini/gemini-cli/pull/24753)
-- Revert "feat(core,cli): prioritize summary for topics (#24608)" by
-  @Abhijit-2592 in
-  [#24777](https://github.com/google-gemini/gemini-cli/pull/24777)
-- relax tool sandboxing overrides for plan mode to match defaults. by
-  @DavidAPierce in
-  [#24762](https://github.com/google-gemini/gemini-cli/pull/24762)
-- fix(cli): respect global environment variable allowlist by @scidomino in
-  [#24767](https://github.com/google-gemini/gemini-cli/pull/24767)
-- fix(cli): ensure skills list outputs to stdout in non-interactive environments
+  [#24544](https://github.com/google-gemini/gemini-cli/pull/24544)
+- chore(release): bump version to 0.39.0-nightly.20260408.e77b22e63 by
+  @gemini-cli-robot in
+  [#24939](https://github.com/google-gemini/gemini-cli/pull/24939)
+- fix(core): ensure robust sandbox cleanup in all process execution paths by
+  @ehedlund in [#24763](https://github.com/google-gemini/gemini-cli/pull/24763)
+- chore: update ink version to 6.6.8 by @jacob314 in
+  [#24934](https://github.com/google-gemini/gemini-cli/pull/24934)
+- Changelog for v0.38.0-preview.0 by @gemini-cli-robot in
+  [#24938](https://github.com/google-gemini/gemini-cli/pull/24938)
+- chore: ignore conductor directory by @JayadityaGit in
+  [#22128](https://github.com/google-gemini/gemini-cli/pull/22128)
+- Changelog for v0.37.0 by @gemini-cli-robot in
+  [#24940](https://github.com/google-gemini/gemini-cli/pull/24940)
+- feat(plan): require user confirmation for activate_skill in Plan Mode by
+  @ruomengz in [#24946](https://github.com/google-gemini/gemini-cli/pull/24946)
+- feat(test-utils): add CPU performance integration test harness by @sripasg in
+  [#24951](https://github.com/google-gemini/gemini-cli/pull/24951)
+- fix(cli-ui): enable Ctrl+Backspace for word deletion in Windows Terminal by
+  @dogukanozen in
+  [#21447](https://github.com/google-gemini/gemini-cli/pull/21447)
+- test(sdk): add unit tests for GeminiCliSession by @AdamyaSingh7 in
+  [#21897](https://github.com/google-gemini/gemini-cli/pull/21897)
+- fix(core): resolve windows symlink bypass and stabilize sandbox integration
+  tests by @ehedlund in
+  [#24834](https://github.com/google-gemini/gemini-cli/pull/24834)
+- fix(cli): restore file path display in edit and write tool confirmations by
+  @jwhelangoog in
+  [#24974](https://github.com/google-gemini/gemini-cli/pull/24974)
+- feat(core): refine shell tool description display logic by @jwhelangoog in
+  [#24903](https://github.com/google-gemini/gemini-cli/pull/24903)
+- fix(core): dynamic session ID injection to resolve resume bugs by @scidomino
+  in [#24972](https://github.com/google-gemini/gemini-cli/pull/24972)
+- Update ink version to 6.6.9 by @jacob314 in
+  [#24980](https://github.com/google-gemini/gemini-cli/pull/24980)
+- Generalize evals infra to support more types of evals, organization and
+  queuing of named suites by @gundermanc in
+  [#24941](https://github.com/google-gemini/gemini-cli/pull/24941)
+- fix(cli): optimize startup with lightweight parent process by @sehoon38 in
+  [#24667](https://github.com/google-gemini/gemini-cli/pull/24667)
+- refactor(sandbox): use centralized sandbox paths in macOS Seatbelt
+  implementation by @ehedlund in
+  [#24984](https://github.com/google-gemini/gemini-cli/pull/24984)
+- feat(cli): refine tool output formatting for compact mode by @jwhelangoog in
+  [#24677](https://github.com/google-gemini/gemini-cli/pull/24677)
+- fix(sdk): skip broken sendStream tests to unblock nightly by @SandyTao520 in
+  [#25000](https://github.com/google-gemini/gemini-cli/pull/25000)
+- refactor(core): use centralized path resolution for Linux sandbox by @ehedlund
+  in [#24985](https://github.com/google-gemini/gemini-cli/pull/24985)
+- Support ctrl+shift+g by @jacob314 in
+  [#25035](https://github.com/google-gemini/gemini-cli/pull/25035)
+- feat(core): refactor subagent tool to unified invoke_subagent tool by
+  @abhipatel12 in
+  [#24489](https://github.com/google-gemini/gemini-cli/pull/24489)
+- fix(core): add explicit git identity env vars to prevent sandbox checkpointing
+  error by @mrpmohiburrahman in
+  [#19775](https://github.com/google-gemini/gemini-cli/pull/19775)
+- fix: respect hideContextPercentage when FooterConfigDialog is closed without
+  changes by @chernistry in
+  [#24773](https://github.com/google-gemini/gemini-cli/pull/24773)
+- fix(cli): suppress unhandled AbortError logs during request cancellation by
+  @euxaristia in
+  [#22621](https://github.com/google-gemini/gemini-cli/pull/22621)
+- Automated documentation audit by @g-samroberts in
+  [#24567](https://github.com/google-gemini/gemini-cli/pull/24567)
+- feat(cli): implement useAgentStream hook by @mbleigh in
+  [#24292](https://github.com/google-gemini/gemini-cli/pull/24292)
+- refactor(plan) Clean default plan toml by @ruomengz in
+  [#25037](https://github.com/google-gemini/gemini-cli/pull/25037)
+- refactor(core): remove legacy subagent wrapping tools by @abhipatel12 in
+  [#25053](https://github.com/google-gemini/gemini-cli/pull/25053)
+- fix(core): honor retryDelay in RetryInfo for 503 errors by @yunaseoul in
+  [#25057](https://github.com/google-gemini/gemini-cli/pull/25057)
+- fix(core): remediate subagent memory leaks using AbortSignal in MessageBus by
+  @abhipatel12 in
+  [#25048](https://github.com/google-gemini/gemini-cli/pull/25048)
+- feat(cli): wire up useAgentStream in AppContainer by @mbleigh in
+  [#24297](https://github.com/google-gemini/gemini-cli/pull/24297)
+- feat(core): migrate chat recording to JSONL streaming by @spencer426 in
+  [#23749](https://github.com/google-gemini/gemini-cli/pull/23749)
+- fix(core): clear 5-minute timeouts in oauth flow to prevent memory leaks by
+  @spencer426 in
+  [#24968](https://github.com/google-gemini/gemini-cli/pull/24968)
+- fix(sandbox): centralize async git worktree resolution and enforce read-only
+  security by @ehedlund in
+  [#25040](https://github.com/google-gemini/gemini-cli/pull/25040)
+- feat(test): add high-volume shell test and refine perf harness by @sripasg in
+  [#24983](https://github.com/google-gemini/gemini-cli/pull/24983)
+- fix(core): silently handle EPERM when listing dir structure by @scidomino in
+  [#25066](https://github.com/google-gemini/gemini-cli/pull/25066)
+- Changelog for v0.37.1 by @gemini-cli-robot in
+  [#25055](https://github.com/google-gemini/gemini-cli/pull/25055)
+- fix: decode Uint8Array and multi-byte UTF-8 in API error messages by
+  @kimjune01 in [#23341](https://github.com/google-gemini/gemini-cli/pull/23341)
+- Automated documentation audit results by @g-samroberts in
+  [#22755](https://github.com/google-gemini/gemini-cli/pull/22755)
+- debugging(ui): add optional debugRainbow setting by @jacob314 in
+  [#25088](https://github.com/google-gemini/gemini-cli/pull/25088)
+- fix: resolve lifecycle memory leaks by cleaning up listeners and root closures
   by @spencer426 in
-  [#24566](https://github.com/google-gemini/gemini-cli/pull/24566)
-- Add an eval for and fix unsafe cloning behavior. by @gundermanc in
-  [#24457](https://github.com/google-gemini/gemini-cli/pull/24457)
-- fix(policy): allow complete_task in plan mode by @abhipatel12 in
-  [#24771](https://github.com/google-gemini/gemini-cli/pull/24771)
-- feat(telemetry): add browser agent clearcut metrics by @gsquared94 in
-  [#24688](https://github.com/google-gemini/gemini-cli/pull/24688)
-- feat(cli): support selective topic expansion and click-to-expand by
-  @Abhijit-2592 in
-  [#24793](https://github.com/google-gemini/gemini-cli/pull/24793)
-- temporarily disable sandbox integration test on windows by @ehedlund in
-  [#24786](https://github.com/google-gemini/gemini-cli/pull/24786)
-- Remove flakey test by @scidomino in
-  [#24837](https://github.com/google-gemini/gemini-cli/pull/24837)
-- Alisa/approve button by @alisa-alisa in
-  [#24645](https://github.com/google-gemini/gemini-cli/pull/24645)
-- feat(hooks): display hook system messages in UI by @mbleigh in
-  [#24616](https://github.com/google-gemini/gemini-cli/pull/24616)
-- fix(core): propagate BeforeModel hook model override end-to-end by @krishdef7
-  in [#24784](https://github.com/google-gemini/gemini-cli/pull/24784)
-- chore: fix formatting for behavioral eval skill reference file by @abhipatel12
-  in [#24846](https://github.com/google-gemini/gemini-cli/pull/24846)
-- fix: use directory junctions on Windows for skill linking by @enjoykumawat in
-  [#24823](https://github.com/google-gemini/gemini-cli/pull/24823)
-- fix(cli): prevent multiple banner increments on remount by @sehoon38 in
-  [#24843](https://github.com/google-gemini/gemini-cli/pull/24843)
-- feat(acp): add /help command by @sripasg in
-  [#24839](https://github.com/google-gemini/gemini-cli/pull/24839)
-- fix(core): remove tmux alternate buffer warning by @jackwotherspoon in
-  [#24852](https://github.com/google-gemini/gemini-cli/pull/24852)
-- Improve sandbox error matching and caching by @DavidAPierce in
-  [#24550](https://github.com/google-gemini/gemini-cli/pull/24550)
-- feat(core): add agent protocol UI types and experimental flag by @mbleigh in
-  [#24275](https://github.com/google-gemini/gemini-cli/pull/24275)
-- feat(core): use experiment flags for default fetch timeouts by @yunaseoul in
-  [#24261](https://github.com/google-gemini/gemini-cli/pull/24261)
-- Revert "fix(ui): improve narration suppression and reduce flicker (#2… by
+  [#25049](https://github.com/google-gemini/gemini-cli/pull/25049)
+- docs(cli): updates f12 description to be more precise by @JayadityaGit in
+  [#15816](https://github.com/google-gemini/gemini-cli/pull/15816)
+- fix(cli): mark /settings as unsafe to run concurrently by @jacob314 in
+  [#25061](https://github.com/google-gemini/gemini-cli/pull/25061)
+- fix(core): remove buffer slice to prevent OOM on large output streams by
+  @spencer426 in
+  [#25094](https://github.com/google-gemini/gemini-cli/pull/25094)
+- feat(core): persist subagent agentId in tool call records by @abhipatel12 in
+  [#25092](https://github.com/google-gemini/gemini-cli/pull/25092)
+- chore(core): increase codebase investigator turn limits to 50 by @abhipatel12
+  in [#25125](https://github.com/google-gemini/gemini-cli/pull/25125)
+- refactor(core): consolidate execute() arguments into ExecuteOptions by
+  @mbleigh in [#25101](https://github.com/google-gemini/gemini-cli/pull/25101)
+- feat(core): add Strategic Re-evaluation guidance to system prompt by
+  @aishaneeshah in
+  [#25062](https://github.com/google-gemini/gemini-cli/pull/25062)
+- fix(core): preserve shell execution config fields on update by
+  @jasonmatthewsuhari in
+  [#25113](https://github.com/google-gemini/gemini-cli/pull/25113)
+- docs: add vi shortcuts and clarify MCP sandbox setup by @chrisjcthomas in
+  [#21679](https://github.com/google-gemini/gemini-cli/pull/21679)
+- fix(cli): pass session id to interactive shell executions by
+  @jasonmatthewsuhari in
+  [#25114](https://github.com/google-gemini/gemini-cli/pull/25114)
+- fix(cli): resolve text sanitization data loss due to C1 control characters by
+  @euxaristia in
+  [#22624](https://github.com/google-gemini/gemini-cli/pull/22624)
+- feat(core): add large memory regression test by @cynthialong0-0 in
+  [#25059](https://github.com/google-gemini/gemini-cli/pull/25059)
+- fix(core): resolve PTY exhaustion and orphan MCP subprocess leaks by
+  @spencer426 in
+  [#25079](https://github.com/google-gemini/gemini-cli/pull/25079)
+- chore(deps): update vulnerable dependencies via npm audit fix by @scidomino in
+  [#25140](https://github.com/google-gemini/gemini-cli/pull/25140)
+- perf(sandbox): optimize Windows sandbox initialization via native ACL
+  application by @ehedlund in
+  [#25077](https://github.com/google-gemini/gemini-cli/pull/25077)
+- chore: switch from keytar to @github/keytar by @cocosheng-g in
+  [#25143](https://github.com/google-gemini/gemini-cli/pull/25143)
+- fix: improve audio MIME normalization and validation in file reads by
+  @junaiddshaukat in
+  [#21636](https://github.com/google-gemini/gemini-cli/pull/21636)
+- docs: Update docs-audit to include changes in PR body by @g-samroberts in
+  [#25153](https://github.com/google-gemini/gemini-cli/pull/25153)
+- docs: correct documentation for enforced authentication type by @cocosheng-g
+  in [#25142](https://github.com/google-gemini/gemini-cli/pull/25142)
+- fix(cli): exclude update_topic from confirmation queue count by @Abhijit-2592
+  in [#24945](https://github.com/google-gemini/gemini-cli/pull/24945)
+- Memory fix for trace's streamWrapper. by @anthraxmilkshake in
+  [#25089](https://github.com/google-gemini/gemini-cli/pull/25089)
+- fix(core): fix quota footer for non-auto models and improve display by
+  @jackwotherspoon in
+  [#25121](https://github.com/google-gemini/gemini-cli/pull/25121)
+- docs(contributing): clarify self-assignment policy for issues by @jmr in
+  [#23087](https://github.com/google-gemini/gemini-cli/pull/23087)
+- feat(core): add skill patching support with /memory inbox integration by
+  @SandyTao520 in
+  [#25148](https://github.com/google-gemini/gemini-cli/pull/25148)
+- Stop suppressing thoughts and text in model response by @gundermanc in
+  [#25073](https://github.com/google-gemini/gemini-cli/pull/25073)
+- fix(release): prefix git hash in nightly versions to prevent semver
+  normalization by @SandyTao520 in
+  [#25304](https://github.com/google-gemini/gemini-cli/pull/25304)
+- feat(cli): extract QuotaContext and resolve infinite render loop by @Adib234
+  in [#24959](https://github.com/google-gemini/gemini-cli/pull/24959)
+- refactor(core): extract and centralize sandbox path utilities by @ehedlund in
+  [#25305](https://github.com/google-gemini/gemini-cli/pull/25305)
+- feat(ui): added enhancements to scroll momentum by @devr0306 in
+  [#24447](https://github.com/google-gemini/gemini-cli/pull/24447)
+- fix(core): replace custom binary detection with isbinaryfile to correctly
+  handle UTF-8 (U+FFFD) by @Anjaligarhwal in
+  [#25297](https://github.com/google-gemini/gemini-cli/pull/25297)
+- feat(agent): implement tool-controlled display protocol (Steps 2-3) by
+  @mbleigh in [#25134](https://github.com/google-gemini/gemini-cli/pull/25134)
+- Stop showing scrollbar unless we are in terminalBuffer mode by @jacob314 in
+  [#25320](https://github.com/google-gemini/gemini-cli/pull/25320)
+- feat: support auth block in MCP servers config in agents by @TanmayVartak in
+  [#24770](https://github.com/google-gemini/gemini-cli/pull/24770)
+- fix(core): expose GEMINI_PLANS_DIR to hook environment by @Adib234 in
+  [#25296](https://github.com/google-gemini/gemini-cli/pull/25296)
+- feat(core): implement silent fallback for Plan Mode model routing by @jerop in
+  [#25317](https://github.com/google-gemini/gemini-cli/pull/25317)
+- fix: correct redirect count increment in fetchJson by @KevinZhao in
+  [#24896](https://github.com/google-gemini/gemini-cli/pull/24896)
+- fix(core): prevent secondary crash in ModelRouterService finally block by
   @gundermanc in
-  [#24857](https://github.com/google-gemini/gemini-cli/pull/24857)
-- refactor(cli): remove duplication in interactive shell awaiting input hint by
-  @JayadityaGit in
-  [#24801](https://github.com/google-gemini/gemini-cli/pull/24801)
-- refactor(core): make LegacyAgentSession dependencies optional by @mbleigh in
-  [#24287](https://github.com/google-gemini/gemini-cli/pull/24287)
-- Changelog for v0.37.0-preview.2 by @gemini-cli-robot in
-  [#24848](https://github.com/google-gemini/gemini-cli/pull/24848)
-- fix(cli): always show shell command description or actual command by @jacob314
-  in [#24774](https://github.com/google-gemini/gemini-cli/pull/24774)
-- Added flag for ept size and increased default size by @devr0306 in
-  [#24859](https://github.com/google-gemini/gemini-cli/pull/24859)
-- fix(core): dispose Scheduler to prevent McpProgress listener leak by
-  @Anjaligarhwal in
-  [#24870](https://github.com/google-gemini/gemini-cli/pull/24870)
-- fix(cli): switch default back to terminalBuffer=false and fix regressions
-  introduced for that mode by @jacob314 in
-  [#24873](https://github.com/google-gemini/gemini-cli/pull/24873)
-- feat(cli): switch to ctrl+g from ctrl-x by @jacob314 in
-  [#24861](https://github.com/google-gemini/gemini-cli/pull/24861)
-- fix: isolate concurrent browser agent instances by @gsquared94 in
-  [#24794](https://github.com/google-gemini/gemini-cli/pull/24794)
-- docs: update MCP server OAuth redirect port documentation by @adamfweidman in
-  [#24844](https://github.com/google-gemini/gemini-cli/pull/24844)
+  [#25333](https://github.com/google-gemini/gemini-cli/pull/25333)
+- feat(core): introduce decoupled ContextManager and Sidecar architecture by
+  @joshualitt in
+  [#24752](https://github.com/google-gemini/gemini-cli/pull/24752)
+- docs(core): update generalist agent documentation by @abhipatel12 in
+  [#25325](https://github.com/google-gemini/gemini-cli/pull/25325)
+- chore(mcp): check MCP error code over brittle string match by @jackwotherspoon
+  in [#25381](https://github.com/google-gemini/gemini-cli/pull/25381)
+- feat(plan): update plan mode prompt to allow showing plan content by @ruomengz
+  in [#25058](https://github.com/google-gemini/gemini-cli/pull/25058)
+- test(core): improve sandbox integration test coverage and fix OS-specific
+  failures by @ehedlund in
+  [#25307](https://github.com/google-gemini/gemini-cli/pull/25307)
+- fix(core): use debug level for keychain fallback logging by @ehedlund in
+  [#25398](https://github.com/google-gemini/gemini-cli/pull/25398)
+- feat(test): add a performance test in asian language by @cynthialong0-0 in
+  [#25392](https://github.com/google-gemini/gemini-cli/pull/25392)
+- feat(cli): enable mouse clicking for cursor positioning in AskUser multi-line
+  answers by @Adib234 in
+  [#24630](https://github.com/google-gemini/gemini-cli/pull/24630)
+- fix(core): detect kmscon terminal as supporting true color by @claygeo in
+  [#25282](https://github.com/google-gemini/gemini-cli/pull/25282)
+- ci: add agent session drift check workflow by @adamfweidman in
+  [#25389](https://github.com/google-gemini/gemini-cli/pull/25389)
+- use macos-latest-large runner where applicable. by @scidomino in
+  [#25413](https://github.com/google-gemini/gemini-cli/pull/25413)
+- Changelog for v0.37.2 by @gemini-cli-robot in
+  [#25336](https://github.com/google-gemini/gemini-cli/pull/25336)
 
 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.37.0-preview.2...v0.38.0-preview.0
+https://github.com/google-gemini/gemini-cli/compare/v0.38.0-preview.0...v0.39.0-preview.0

docs/core/subagents.md

@@ -87,11 +87,23 @@ Gemini CLI comes with the following built-in subagents:
 
 ### Generalist Agent
 
-- **Name:** `generalist_agent`
-- **Purpose:** Route tasks to the appropriate specialized subagent.
-- **When to use:** Implicitly used by the main agent for routing. Not directly
-  invoked by the user.
-- **Configuration:** Enabled by default. No specific configuration options.
+- **Name:** `generalist`
+- **Purpose:** A general, all-purpose subagent that uses the inherited tool
+  access and configurations from the main agent. Useful for executing broad,
+  resource-heavy subtasks in an isolated conversation, optimizing your main
+  agent's context by returning only the final result of that given task.
+- **When to use:** Use this agent when a task requires many steps, handles large
+  volumes of information, or requires the same full capabilities as the main
+  agent. It is ideal for:
+  - **Multi-file modifications:** Applying refactors or fixing errors across
+    several files at once.
+  - **High-volume execution:** Running commands or tests that produce extensive
+    terminal output.
+  - **Action-oriented research:** Investigations where the agent needs to both
+    search code and run commands or make edits to find a solution. By delegating
+    these tasks, you prevent your main conversation from becoming cluttered or
+    slow. You can invoke it explicitly using `@generalist`.
+- **Configuration:** Enabled by default.
 
 ### Browser Agent (experimental)
 

docs/reference/configuration.md

@@ -2148,6 +2148,21 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
   - When set, overrides the default API version used by the SDK.
   - Example: `export GOOGLE_GENAI_API_VERSION="v1"` (Windows PowerShell:
     `$env:GOOGLE_GENAI_API_VERSION="v1"`)
+- **`GOOGLE_GEMINI_BASE_URL`**:
+  - Overrides the default base URL for Gemini API requests (when using
+    `gemini-api-key` authentication).
+  - Must be a valid URL. For security, it must use HTTPS unless pointing to
+    `localhost` (or `127.0.0.1` / `[::1]`).
+  - Example: `export GOOGLE_GEMINI_BASE_URL="https://my-proxy.com"` (Windows
+    PowerShell: `$env:GOOGLE_GEMINI_BASE_URL="https://my-proxy.com"`)
+- **`GOOGLE_VERTEX_BASE_URL`**:
+  - Overrides the default base URL for Vertex AI API requests (when using
+    `vertex-ai` authentication).
+  - Must be a valid URL. For security, it must use HTTPS unless pointing to
+    `localhost` (or `127.0.0.1` / `[::1]`).
+  - Example: `export GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com"`
+    (Windows PowerShell:
+    `$env:GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com"`)
 - **`OTLP_GOOGLE_CLOUD_PROJECT`**:
   - Your Google Cloud Project ID for Telemetry in Google Cloud
   - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` (Windows

evals/cli_help_delegation.eval.ts

@@ -17,9 +17,17 @@ describe('CliHelpAgent Delegation', () => {
     timeout: 60000,
     assert: async (rig, _result) => {
       const toolLogs = rig.readToolLogs();
-      const toolCallIndex = toolLogs.findIndex(
-        (log) => log.toolRequest.name === 'cli_help',
-      );
+      const toolCallIndex = toolLogs.findIndex((log) => {
+        if (log.toolRequest.name === 'invoke_agent') {
+          try {
+            const args = JSON.parse(log.toolRequest.args);
+            return args.agent_name === 'cli_help';
+          } catch {
+            return false;
+          }
+        }
+        return false;
+      });
       expect(toolCallIndex).toBeGreaterThan(-1);
       expect(toolCallIndex).toBeLessThan(5); // Called within first 5 turns
     },

evals/component-test-helper.ts

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { vi } from 'vitest';
 import {
   Config,
   type ConfigParameters,
@@ -52,6 +53,7 @@ export interface ComponentEvalCase extends BaseEvalCase {
 export class ComponentRig {
   public config: Config | undefined;
   public testDir: string;
+  public homeDir: string;
   public sessionId: string;
 
   constructor(
@@ -61,6 +63,9 @@ export class ComponentRig {
     this.testDir = fs.mkdtempSync(
       path.join(os.tmpdir(), `gemini-component-rig-${uniqueId.slice(0, 8)}-`),
     );
+    this.homeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), `gemini-component-home-${uniqueId.slice(0, 8)}-`),
+    );
     this.sessionId = `test-session-${uniqueId}`;
   }
 
@@ -89,12 +94,23 @@ export class ComponentRig {
     this.config = makeFakeConfig(configParams);
     await this.config.initialize();
 
-    // Refresh auth using USE_GEMINI to initialize the real BaseLlmClient
+    // Refresh auth using USE_GEMINI to initialize the real BaseLlmClient.
+    // This must happen BEFORE stubbing GEMINI_CLI_HOME because OAuth credential
+    // lookup resolves through homedir() → GEMINI_CLI_HOME.
     await this.config.refreshAuth(AuthType.USE_GEMINI);
+
+    // Isolate storage paths (session files, skills, extraction state) by
+    // pointing GEMINI_CLI_HOME at a per-test temp directory.  Storage resolves
+    // global paths through `homedir()` which reads this env var.  This is set
+    // after auth so credential lookup uses the real home directory.
+    vi.stubEnv('GEMINI_CLI_HOME', this.homeDir);
   }
 
   async cleanup() {
+    await this.config?.dispose();
+    vi.unstubAllEnvs();
     fs.rmSync(this.testDir, { recursive: true, force: true });
+    fs.rmSync(this.homeDir, { recursive: true, force: true });
   }
 }
 

evals/generalist_agent.eval.ts

@@ -26,11 +26,22 @@ describe('generalist_agent', () => {
     prompt:
       'Please use the generalist agent to create a file called "generalist_test_file.txt" containing exactly the following text: success',
     assert: async (rig) => {
-      // 1) Verify the generalist agent was invoked
-      const foundToolCall = await rig.waitForToolCall('generalist');
+      // 1) Verify the generalist agent was invoked via invoke_agent
+      const foundToolCall = await rig.waitForToolCall(
+        'invoke_agent',
+        undefined,
+        (args) => {
+          try {
+            const parsed = JSON.parse(args);
+            return parsed.agent_name === 'generalist';
+          } catch {
+            return false;
+          }
+        },
+      );
       expect(
         foundToolCall,
-        'Expected to find a tool call for generalist agent',
+        'Expected to find an invoke_agent tool call for generalist agent',
       ).toBeTruthy();
 
       // 2) Verify the file was created as expected

evals/save_memory.eval.ts

@@ -145,22 +145,30 @@ describe('save_memory', () => {
     },
   });
 
-  const ignoringDbSchemaLocation =
-    "Agent ignores workspace's database schema location";
+  const savingDbSchemaLocationAsProjectMemory =
+    'Agent saves workspace database schema location as project memory';
   evalTest('USUALLY_PASSES', {
     suiteName: 'default',
     suiteType: 'behavioral',
-    name: ignoringDbSchemaLocation,
+    name: savingDbSchemaLocationAsProjectMemory,
     prompt: `The database schema for this workspace is located in \`db/schema.sql\`.`,
     assert: async (rig, result) => {
-      await rig.waitForTelemetryReady();
-      const wasToolCalled = rig
-        .readToolLogs()
-        .some((log) => log.toolRequest.name === 'save_memory');
+      const wasToolCalled = await rig.waitForToolCall(
+        'save_memory',
+        undefined,
+        (args) => {
+          try {
+            const params = JSON.parse(args);
+            return params.scope === 'project';
+          } catch {
+            return false;
+          }
+        },
+      );
       expect(
         wasToolCalled,
-        'save_memory should not be called for workspace-specific information',
-      ).toBe(false);
+        'Expected save_memory to be called with scope="project" for workspace-specific information',
+      ).toBe(true);
 
       assertModelHasOutput(result);
     },
@@ -188,42 +196,59 @@ describe('save_memory', () => {
     },
   });
 
-  const ignoringBuildArtifactLocation =
-    'Agent ignores workspace build artifact location';
+  const savingBuildArtifactLocationAsProjectMemory =
+    'Agent saves workspace build artifact location as project memory';
   evalTest('USUALLY_PASSES', {
     suiteName: 'default',
     suiteType: 'behavioral',
-    name: ignoringBuildArtifactLocation,
+    name: savingBuildArtifactLocationAsProjectMemory,
     prompt: `In this workspace, build artifacts are stored in the \`dist/artifacts\` directory.`,
     assert: async (rig, result) => {
-      await rig.waitForTelemetryReady();
-      const wasToolCalled = rig
-        .readToolLogs()
-        .some((log) => log.toolRequest.name === 'save_memory');
+      const wasToolCalled = await rig.waitForToolCall(
+        'save_memory',
+        undefined,
+        (args) => {
+          try {
+            const params = JSON.parse(args);
+            return params.scope === 'project';
+          } catch {
+            return false;
+          }
+        },
+      );
       expect(
         wasToolCalled,
-        'save_memory should not be called for workspace-specific information',
-      ).toBe(false);
+        'Expected save_memory to be called with scope="project" for workspace-specific information',
+      ).toBe(true);
 
       assertModelHasOutput(result);
     },
   });
 
-  const ignoringMainEntryPoint = "Agent ignores workspace's main entry point";
+  const savingMainEntryPointAsProjectMemory =
+    'Agent saves workspace main entry point as project memory';
   evalTest('USUALLY_PASSES', {
     suiteName: 'default',
     suiteType: 'behavioral',
-    name: ignoringMainEntryPoint,
+    name: savingMainEntryPointAsProjectMemory,
     prompt: `The main entry point for this workspace is \`src/index.js\`.`,
     assert: async (rig, result) => {
-      await rig.waitForTelemetryReady();
-      const wasToolCalled = rig
-        .readToolLogs()
-        .some((log) => log.toolRequest.name === 'save_memory');
+      const wasToolCalled = await rig.waitForToolCall(
+        'save_memory',
+        undefined,
+        (args) => {
+          try {
+            const params = JSON.parse(args);
+            return params.scope === 'project';
+          } catch {
+            return false;
+          }
+        },
+      );
       expect(
         wasToolCalled,
-        'save_memory should not be called for workspace-specific information',
-      ).toBe(false);
+        'Expected save_memory to be called with scope="project" for workspace-specific information',
+      ).toBe(true);
 
       assertModelHasOutput(result);
     },
@@ -317,13 +342,13 @@ describe('save_memory', () => {
       'Please save any persistent preferences or facts about me from our conversation to memory.',
     assert: async (rig, result) => {
       const wasToolCalled = await rig.waitForToolCall(
-        'save_memory',
+        'invoke_agent',
         undefined,
-        (args) => /vitest/i.test(args),
+        (args) => /save_memory/i.test(args) && /vitest/i.test(args),
       );
       expect(
         wasToolCalled,
-        'Expected save_memory to be called with the Vitest preference from the conversation history',
+        'Expected invoke_agent to be called with save_memory agent and the Vitest preference from the conversation history',
       ).toBe(true);
 
       assertModelHasOutput(result);
@@ -379,8 +404,15 @@ describe('save_memory', () => {
     ],
     prompt: 'Please save the preferences I mentioned earlier to memory.',
     assert: async (rig, result) => {
-      const wasToolCalled = await rig.waitForToolCall('save_memory');
-      expect(wasToolCalled, 'Expected save_memory to be called').toBe(true);
+      const wasToolCalled = await rig.waitForToolCall(
+        'invoke_agent',
+        undefined,
+        (args) => /save_memory/i.test(args),
+      );
+      expect(
+        wasToolCalled,
+        'Expected invoke_agent to be called with save_memory agent',
+      ).toBe(true);
 
       assertModelHasOutput(result);
     },

evals/skill_extraction.eval.ts

@@ -0,0 +1,349 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { describe, expect } from 'vitest';
+import {
+  type Config,
+  ApprovalMode,
+  SESSION_FILE_PREFIX,
+  getProjectHash,
+  startMemoryService,
+} from '@google/gemini-cli-core';
+import { componentEvalTest } from './component-test-helper.js';
+
+interface SeedSession {
+  sessionId: string;
+  summary: string;
+  userTurns: string[];
+  timestampOffsetMinutes: number;
+}
+
+interface MessageRecord {
+  id: string;
+  timestamp: string;
+  type: string;
+  content: Array<{ text: string }>;
+}
+
+const WORKSPACE_FILES = {
+  'package.json': JSON.stringify(
+    {
+      name: 'skill-extraction-eval',
+      private: true,
+      scripts: {
+        build: 'echo build',
+        lint: 'echo lint',
+        test: 'echo test',
+      },
+    },
+    null,
+    2,
+  ),
+  'README.md': `# Skill Extraction Eval
+
+This workspace exists to exercise background skill extraction from prior chats.
+`,
+};
+
+function buildMessages(userTurns: string[]): MessageRecord[] {
+  const baseTime = new Date(Date.now() - 6 * 60 * 60 * 1000).toISOString();
+  return userTurns.flatMap((text, index) => [
+    {
+      id: `u${index + 1}`,
+      timestamp: baseTime,
+      type: 'user',
+      content: [{ text }],
+    },
+    {
+      id: `a${index + 1}`,
+      timestamp: baseTime,
+      type: 'gemini',
+      content: [{ text: `Acknowledged: ${index + 1}` }],
+    },
+  ]);
+}
+
+async function seedSessions(
+  config: Config,
+  sessions: SeedSession[],
+): Promise<void> {
+  const chatsDir = path.join(config.storage.getProjectTempDir(), 'chats');
+  await fsp.mkdir(chatsDir, { recursive: true });
+
+  const projectRoot = config.storage.getProjectRoot();
+
+  for (const session of sessions) {
+    const timestamp = new Date(
+      Date.now() - session.timestampOffsetMinutes * 60 * 1000,
+    )
+      .toISOString()
+      .slice(0, 16)
+      .replace(/:/g, '-');
+    const filename = `${SESSION_FILE_PREFIX}${timestamp}-${session.sessionId.slice(0, 8)}.json`;
+    const conversation = {
+      sessionId: session.sessionId,
+      projectHash: getProjectHash(projectRoot),
+      summary: session.summary,
+      startTime: new Date(Date.now() - 7 * 60 * 60 * 1000).toISOString(),
+      lastUpdated: new Date(Date.now() - 4 * 60 * 60 * 1000).toISOString(),
+      messages: buildMessages(session.userTurns),
+    };
+
+    await fsp.writeFile(
+      path.join(chatsDir, filename),
+      JSON.stringify(conversation, null, 2),
+    );
+  }
+}
+
+async function runExtractionAndReadState(config: Config): Promise<{
+  state: { runs: Array<{ sessionIds: string[]; skillsCreated: string[] }> };
+  skillsDir: string;
+}> {
+  await startMemoryService(config);
+
+  const memoryDir = config.storage.getProjectMemoryTempDir();
+  const skillsDir = config.storage.getProjectSkillsMemoryDir();
+  const statePath = path.join(memoryDir, '.extraction-state.json');
+
+  const raw = await fsp.readFile(statePath, 'utf-8');
+  const state = JSON.parse(raw) as {
+    runs?: Array<{ sessionIds?: string[]; skillsCreated?: string[] }>;
+  };
+  if (!Array.isArray(state.runs) || state.runs.length === 0) {
+    throw new Error('Skill extraction finished without writing any run state');
+  }
+
+  return {
+    state: {
+      runs: state.runs.map((run) => ({
+        sessionIds: Array.isArray(run.sessionIds) ? run.sessionIds : [],
+        skillsCreated: Array.isArray(run.skillsCreated)
+          ? run.skillsCreated
+          : [],
+      })),
+    },
+    skillsDir,
+  };
+}
+
+async function readSkillBodies(skillsDir: string): Promise<string[]> {
+  try {
+    const entries = await fsp.readdir(skillsDir, { withFileTypes: true });
+    const skillDirs = entries.filter((entry) => entry.isDirectory());
+    const bodies = await Promise.all(
+      skillDirs.map((entry) =>
+        fsp.readFile(path.join(skillsDir, entry.name, 'SKILL.md'), 'utf-8'),
+      ),
+    );
+    return bodies;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Shared configOverrides for all skill extraction component evals.
+ * - experimentalMemoryManager: enables the memory extraction pipeline.
+ * - approvalMode: YOLO auto-approves tool calls (write_file, read_file) so the
+ *   background agent can execute without interactive confirmation.
+ */
+const EXTRACTION_CONFIG_OVERRIDES = {
+  experimentalMemoryManager: true,
+  approvalMode: ApprovalMode.YOLO,
+};
+
+describe('Skill Extraction', () => {
+  componentEvalTest('USUALLY_PASSES', {
+    suiteName: 'skill-extraction',
+    suiteType: 'component-level',
+    name: 'ignores one-off incidents even when session summaries look similar',
+    files: WORKSPACE_FILES,
+    timeout: 180000,
+    configOverrides: EXTRACTION_CONFIG_OVERRIDES,
+    setup: async (config) => {
+      await seedSessions(config, [
+        {
+          sessionId: 'incident-login-redirect',
+          summary: 'Debug login redirect loop in staging',
+          timestampOffsetMinutes: 420,
+          userTurns: [
+            'We only need a one-off fix for incident INC-4412 on branch hotfix/login-loop.',
+            'The exact failing string is ERR_REDIRECT_4412 and this workaround is incident-specific.',
+            'Patch packages/auth/src/redirect.ts just for this branch and do not generalize it.',
+            'The thing that worked was deleting the stale staging cookie before retrying.',
+            'This is not a normal workflow and should not become a reusable instruction.',
+            'It only reproduced against the 2026-04-08 staging rollout.',
+            'After the cookie clear, the branch-specific redirect logic passed.',
+            'Do not turn this incident writeup into a standing process.',
+            'Yes, the hotfix worked for this exact redirect-loop incident.',
+            'Close out INC-4412 once the staging login succeeds again.',
+          ],
+        },
+        {
+          sessionId: 'incident-login-timeout',
+          summary: 'Debug login callback timeout in staging',
+          timestampOffsetMinutes: 360,
+          userTurns: [
+            'This is another one-off staging incident, this time TICKET-991 for callback timeout.',
+            'The exact failing string is ERR_CALLBACK_TIMEOUT_991 and it is unrelated to the redirect loop.',
+            'The temporary fix was rotating the staging secret and deleting a bad feature-flag row.',
+            'Do not write a generic login-debugging playbook from this.',
+            'This only applied to the callback timeout during the April rollout.',
+            'The successful fix was specific to the stale secret in staging.',
+            'It does not define a durable repo workflow for future tasks.',
+            'After rotating the secret, the callback timeout stopped reproducing.',
+            'Treat this as incident response only, not a reusable skill.',
+            'Once staging passed again, we closed TICKET-991.',
+          ],
+        },
+      ]);
+    },
+    assert: async (config) => {
+      const { state, skillsDir } = await runExtractionAndReadState(config);
+      const skillBodies = await readSkillBodies(skillsDir);
+
+      expect(state.runs).toHaveLength(1);
+      expect(state.runs[0].sessionIds).toHaveLength(2);
+      expect(state.runs[0].skillsCreated).toEqual([]);
+      expect(skillBodies).toEqual([]);
+    },
+  });
+
+  componentEvalTest('USUALLY_PASSES', {
+    suiteName: 'skill-extraction',
+    suiteType: 'component-level',
+    name: 'extracts a repeated project-specific workflow into a skill',
+    files: WORKSPACE_FILES,
+    timeout: 180000,
+    configOverrides: EXTRACTION_CONFIG_OVERRIDES,
+    setup: async (config) => {
+      await seedSessions(config, [
+        {
+          sessionId: 'settings-docs-regen-1',
+          summary: 'Update settings docs after adding a config option',
+          timestampOffsetMinutes: 420,
+          userTurns: [
+            'When we add a new config option, we have to regenerate the settings docs in a specific order.',
+            'The sequence that worked was npm run predocs:settings, npm run schema:settings, then npm run docs:settings.',
+            'Do not hand-edit generated settings docs.',
+            'If predocs is skipped, the generated schema docs miss the new defaults.',
+            'Update the source first, then run that generation sequence.',
+            'After regenerating, verify the schema output and docs changed together.',
+            'We used this same sequence the last time we touched settings docs.',
+            'That ordered workflow passed and produced the expected generated files.',
+            'Please keep the exact command order because reversing it breaks the output.',
+            'Yes, the generated settings docs were correct after those three commands.',
+          ],
+        },
+        {
+          sessionId: 'settings-docs-regen-2',
+          summary: 'Regenerate settings schema docs for another new setting',
+          timestampOffsetMinutes: 360,
+          userTurns: [
+            'We are touching another setting, so follow the same settings-doc regeneration workflow again.',
+            'Run npm run predocs:settings before npm run schema:settings and npm run docs:settings.',
+            'The project keeps generated settings docs in sync through those commands, not manual edits.',
+            'Skipping predocs caused stale defaults in the generated output before.',
+            'Change the source, then execute the same three commands in order.',
+            'Verify both the schema artifact and docs update together after regeneration.',
+            'This is the recurring workflow we use whenever a setting changes.',
+            'The exact order worked again on this second settings update.',
+            'Please preserve that ordering constraint for future settings changes.',
+            'Confirmed: the settings docs regenerated correctly with the same command sequence.',
+          ],
+        },
+      ]);
+    },
+    assert: async (config) => {
+      const { state, skillsDir } = await runExtractionAndReadState(config);
+      const skillBodies = await readSkillBodies(skillsDir);
+      const combinedSkills = skillBodies.join('\n\n');
+
+      expect(state.runs).toHaveLength(1);
+      expect(state.runs[0].sessionIds).toHaveLength(2);
+      expect(state.runs[0].skillsCreated.length).toBeGreaterThanOrEqual(1);
+      expect(skillBodies.length).toBeGreaterThanOrEqual(1);
+      expect(combinedSkills).toContain('npm run predocs:settings');
+      expect(combinedSkills).toContain('npm run schema:settings');
+      expect(combinedSkills).toContain('npm run docs:settings');
+      expect(combinedSkills).toMatch(/Verification/i);
+
+      // Verify the extraction agent activated skill-creator for design guidance.
+      expect(config.getSkillManager().isSkillActive('skill-creator')).toBe(
+        true,
+      );
+    },
+  });
+
+  componentEvalTest('USUALLY_PASSES', {
+    suiteName: 'skill-extraction',
+    suiteType: 'component-level',
+    name: 'extracts a repeated multi-step migration workflow with ordering constraints',
+    files: WORKSPACE_FILES,
+    timeout: 180000,
+    configOverrides: EXTRACTION_CONFIG_OVERRIDES,
+    setup: async (config) => {
+      await seedSessions(config, [
+        {
+          sessionId: 'db-migration-v12',
+          summary: 'Run database migration for v12 schema update',
+          timestampOffsetMinutes: 420,
+          userTurns: [
+            'Every time we change the database schema we follow a specific migration workflow.',
+            'First run npm run db:check to verify no pending migrations conflict.',
+            'Then run npm run db:migrate to apply the new migration files.',
+            'After migration, always run npm run db:validate to confirm schema integrity.',
+            'If db:validate fails, immediately run npm run db:rollback before anything else.',
+            'Never skip db:check — last time we did, two migrations collided and corrupted the index.',
+            'The ordering is critical: check, migrate, validate. Reversing migrate and validate caused silent data loss before.',
+            'This v12 migration passed after following that exact sequence.',
+            'We use this same three-step workflow every time the schema changes.',
+            'Confirmed: db:check, db:migrate, db:validate completed successfully for v12.',
+          ],
+        },
+        {
+          sessionId: 'db-migration-v13',
+          summary: 'Run database migration for v13 schema update',
+          timestampOffsetMinutes: 360,
+          userTurns: [
+            'New schema change for v13, following the same database migration workflow as before.',
+            'Start with npm run db:check to ensure no conflicting pending migrations.',
+            'Then npm run db:migrate to apply the v13 migration files.',
+            'Then npm run db:validate to confirm the schema is consistent.',
+            'If validation fails, run npm run db:rollback immediately — do not attempt manual fixes.',
+            'We learned the hard way that skipping db:check causes index corruption.',
+            'The check-migrate-validate order is mandatory for every schema change.',
+            'This is the same recurring workflow we used for v12 and earlier migrations.',
+            'The v13 migration passed with the same three-step sequence.',
+            'Confirmed: the standard db migration workflow succeeded again for v13.',
+          ],
+        },
+      ]);
+    },
+    assert: async (config) => {
+      const { state, skillsDir } = await runExtractionAndReadState(config);
+      const skillBodies = await readSkillBodies(skillsDir);
+      const combinedSkills = skillBodies.join('\n\n');
+
+      expect(state.runs).toHaveLength(1);
+      expect(state.runs[0].sessionIds).toHaveLength(2);
+      expect(state.runs[0].skillsCreated.length).toBeGreaterThanOrEqual(1);
+      expect(skillBodies.length).toBeGreaterThanOrEqual(1);
+      expect(combinedSkills).toContain('npm run db:check');
+      expect(combinedSkills).toContain('npm run db:migrate');
+      expect(combinedSkills).toContain('npm run db:validate');
+      expect(combinedSkills).toMatch(/rollback/i);
+
+      // Verify the extraction agent activated skill-creator for design guidance.
+      expect(config.getSkillManager().isSkillActive('skill-creator')).toBe(
+        true,
+      );
+    },
+  });
+});

evals/subtask_delegation.eval.ts

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect } from 'vitest';
+import {
+  TRACKER_CREATE_TASK_TOOL_NAME,
+  TRACKER_UPDATE_TASK_TOOL_NAME,
+} from '@google/gemini-cli-core';
+import { evalTest, TEST_AGENTS } from './test-helper.js';
+
+describe('subtask delegation eval test cases', () => {
+  /**
+   * Checks that the main agent can correctly decompose a complex, sequential
+   * task into subtasks using the task tracker and delegate each to the appropriate expert subagent.
+   *
+   * The task requires:
+   * 1. Reading requirements (researcher)
+   * 2. Implementing logic (developer)
+   * 3. Documenting (doc expert)
+   */
+  evalTest('USUALLY_PASSES', {
+    name: 'should delegate sequential subtasks to relevant experts using the task tracker',
+    params: {
+      settings: {
+        experimental: {
+          enableAgents: true,
+          taskTracker: true,
+        },
+      },
+    },
+    prompt:
+      'Please read the requirements in requirements.txt using a researcher, then implement the requested logic in src/logic.ts using a developer, and finally document the implementation in docs/logic.md using a documentation expert.',
+    files: {
+      '.gemini/agents/researcher.md': `---
+name: researcher
+description: Expert in reading files and extracting requirements.
+tools:
+  - read_file
+---
+You are the researcher. Read the provided file and extract requirements.`,
+      '.gemini/agents/developer.md': `---
+name: developer
+description: Expert in implementing logic in TypeScript.
+tools:
+  - write_file
+---
+You are the developer. Implement the requested logic in the specified file.`,
+      '.gemini/agents/doc-expert.md': `---
+name: doc-expert
+description: Expert in writing technical documentation.
+tools:
+  - write_file
+---
+You are the doc expert. Document the provided implementation clearly.`,
+      'requirements.txt':
+        'Implement a function named "calculateSum" that adds two numbers.',
+    },
+    assert: async (rig, _result) => {
+      // Verify tracker tasks were created
+      const wasCreateCalled = await rig.waitForToolCall(
+        TRACKER_CREATE_TASK_TOOL_NAME,
+      );
+      expect(wasCreateCalled).toBe(true);
+
+      const toolLogs = rig.readToolLogs();
+      const createCalls = toolLogs.filter(
+        (l) => l.toolRequest.name === TRACKER_CREATE_TASK_TOOL_NAME,
+      );
+      expect(createCalls.length).toBeGreaterThanOrEqual(3);
+
+      await rig.expectToolCallSuccess([
+        'researcher',
+        'developer',
+        'doc-expert',
+      ]);
+
+      const logicFile = rig.readFile('src/logic.ts');
+      const docFile = rig.readFile('docs/logic.md');
+
+      expect(logicFile).toContain('calculateSum');
+      expect(docFile).toBeTruthy();
+    },
+  });
+
+  /**
+   * Checks that the main agent can delegate a batch of independent subtasks
+   * to multiple subagents in parallel using the task tracker to manage state.
+   */
+  evalTest('USUALLY_PASSES', {
+    name: 'should delegate independent subtasks to specialists using the task tracker',
+    params: {
+      settings: {
+        experimental: {
+          enableAgents: true,
+          taskTracker: true,
+        },
+      },
+    },
+    prompt:
+      'Please update the project for internationalization (i18n), audit the security of the current code, and update the CSS to use a blue theme. Use specialized experts for each task.',
+    files: {
+      ...TEST_AGENTS.I18N_AGENT.asFile(),
+      ...TEST_AGENTS.SECURITY_AGENT.asFile(),
+      ...TEST_AGENTS.CSS_AGENT.asFile(),
+      'index.ts': 'console.log("Hello World");',
+    },
+    assert: async (rig, _result) => {
+      // Verify tracker tasks were created
+      const wasCreateCalled = await rig.waitForToolCall(
+        TRACKER_CREATE_TASK_TOOL_NAME,
+      );
+      expect(wasCreateCalled).toBe(true);
+
+      const toolLogs = rig.readToolLogs();
+      const createCalls = toolLogs.filter(
+        (l) => l.toolRequest.name === TRACKER_CREATE_TASK_TOOL_NAME,
+      );
+      expect(createCalls.length).toBeGreaterThanOrEqual(3);
+
+      await rig.expectToolCallSuccess([
+        TEST_AGENTS.I18N_AGENT.name,
+        TEST_AGENTS.SECURITY_AGENT.name,
+        TEST_AGENTS.CSS_AGENT.name,
+      ]);
+    },
+  });
+});

integration-tests/run_shell_command_file_stream.test.ts

@@ -0,0 +1,275 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { TestRig } from './test-helper.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+describe('run_shell_command streaming to file regression', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
+  it('should stream large outputs to a file and verify full content presence', async () => {
+    await rig.setup(
+      'should stream large outputs to a file and verify full content presence',
+      {
+        settings: { tools: { core: ['run_shell_command'] } },
+      },
+    );
+
+    const numLines = 20000;
+    const testFileName = 'large_output_test.txt';
+    const testFilePath = path.join(rig.testDir!, testFileName);
+
+    // Create a ~20MB file with unique content at start and end
+    const startMarker = 'START_OF_FILE_MARKER';
+    const endMarker = 'END_OF_FILE_MARKER';
+
+    const stream = fs.createWriteStream(testFilePath);
+    stream.write(startMarker + '\n');
+    for (let i = 0; i < numLines; i++) {
+      stream.write(`Line ${i + 1}: ` + 'A'.repeat(1000) + '\n');
+    }
+    stream.write(endMarker + '\n');
+    await new Promise((resolve) => stream.end(resolve));
+
+    const fileSize = fs.statSync(testFilePath).size;
+    expect(fileSize).toBeGreaterThan(20000000);
+
+    const prompt = `Use run_shell_command to cat ${testFileName} and say 'Done.'`;
+    await rig.run({ args: prompt });
+
+    let savedFilePath = '';
+    const tmpdir = path.join(rig.homeDir!, '.gemini', 'tmp');
+    if (fs.existsSync(tmpdir)) {
+      const findFiles = (dir: string): string[] => {
+        let results: string[] = [];
+        const list = fs.readdirSync(dir, { withFileTypes: true });
+        for (const file of list) {
+          const fullPath = path.join(dir, file.name);
+          if (file.isDirectory()) {
+            results = results.concat(findFiles(fullPath));
+          } else if (file.isFile() && file.name.endsWith('.txt')) {
+            results.push(fullPath);
+          } else if (file.isFile() && file.name.endsWith('.log')) {
+            results.push(fullPath);
+          }
+        }
+        return results;
+      };
+
+      const files = findFiles(tmpdir);
+      files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+
+      for (const p of files) {
+        try {
+          const stat = fs.statSync(p);
+          if (stat.size >= 20000000) {
+            savedFilePath = p;
+            break;
+          }
+        } catch {
+          // ignore
+        }
+      }
+
+      if (!savedFilePath) {
+        const fileStats = files.map((p) => {
+          try {
+            return { p, size: fs.statSync(p).size };
+          } catch {
+            return { p, size: 'error' };
+          }
+        });
+        rig.log('Available files:', JSON.stringify(fileStats, null, 2));
+      }
+    }
+
+    expect(
+      savedFilePath,
+      `Expected to find a saved output file >= 20MB in ${tmpdir}`,
+    ).toBeTruthy();
+
+    const savedContent = fs.readFileSync(savedFilePath, 'utf8');
+    expect(savedContent).toContain(startMarker);
+    expect(savedContent).toContain(endMarker);
+    expect(savedContent.length).toBeGreaterThanOrEqual(fileSize);
+
+    fs.unlinkSync(savedFilePath);
+  }, 120000);
+
+  it('should stream very large (50MB) outputs to a file and verify full content presence', async () => {
+    await rig.setup(
+      'should stream very large (50MB) outputs to a file and verify full content presence',
+      {
+        settings: { tools: { core: ['run_shell_command'] } },
+      },
+    );
+
+    const numLines = 1000000;
+    const testFileName = 'very_large_output_test.txt';
+    const testFilePath = path.join(rig.testDir!, testFileName);
+
+    // Create a ~50MB file with unique content at start and end
+    const startMarker = 'START_OF_FILE_MARKER';
+    const endMarker = 'END_OF_FILE_MARKER';
+
+    const stream = fs.createWriteStream(testFilePath);
+    stream.write(startMarker + '\n');
+    for (let i = 0; i < numLines; i++) {
+      stream.write(`Line ${i + 1}: ` + 'A'.repeat(40) + '\n');
+    }
+    stream.write(endMarker + '\n');
+    await new Promise((resolve) => stream.end(resolve));
+
+    const fileSize = fs.statSync(testFilePath).size;
+    expect(fileSize).toBeGreaterThan(45000000);
+
+    const prompt = `Use run_shell_command to cat ${testFileName} and say 'Done.'`;
+    await rig.run({ args: prompt });
+
+    let savedFilePath = '';
+    const tmpdir = path.join(rig.homeDir!, '.gemini', 'tmp');
+    if (fs.existsSync(tmpdir)) {
+      const findFiles = (dir: string): string[] => {
+        let results: string[] = [];
+        const list = fs.readdirSync(dir, { withFileTypes: true });
+        for (const file of list) {
+          const fullPath = path.join(dir, file.name);
+          if (file.isDirectory()) {
+            results = results.concat(findFiles(fullPath));
+          } else if (file.isFile() && file.name.endsWith('.txt')) {
+            results.push(fullPath);
+          } else if (file.isFile() && file.name.endsWith('.log')) {
+            results.push(fullPath);
+          }
+        }
+        return results;
+      };
+
+      const files = findFiles(tmpdir);
+      files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+
+      for (const p of files) {
+        try {
+          const stat = fs.statSync(p);
+          if (stat.size >= 20000000) {
+            savedFilePath = p;
+            break;
+          }
+        } catch {
+          // ignore
+        }
+      }
+
+      if (!savedFilePath) {
+        const fileStats = files.map((p) => {
+          try {
+            return { p, size: fs.statSync(p).size };
+          } catch {
+            return { p, size: 'error' };
+          }
+        });
+        rig.log('Available files:', JSON.stringify(fileStats, null, 2));
+      }
+    }
+
+    expect(
+      savedFilePath,
+      `Expected to find a saved output file >= 20MB in ${tmpdir}`,
+    ).toBeTruthy();
+
+    const savedContent = fs.readFileSync(savedFilePath, 'utf8');
+    expect(savedContent).toContain(startMarker);
+    expect(savedContent).toContain(endMarker);
+    expect(savedContent.length).toBeGreaterThanOrEqual(fileSize);
+
+    fs.unlinkSync(savedFilePath);
+  }, 120000);
+
+  it('should produce clean output resolving carriage returns and backspaces', async () => {
+    await rig.setup(
+      'should produce clean output resolving carriage returns and backspaces',
+      {
+        settings: {
+          tools: { core: ['run_shell_command'] },
+        },
+      },
+    );
+
+    const script = `
+import sys
+import time
+
+# Fill buffer to force file streaming/truncation
+# 45000 chars to be safe (default threshold is 40000)
+print('A' * 45000)
+sys.stdout.flush()
+
+# Test sequence
+print('XXXXX', end='', flush=True)
+time.sleep(0.5)
+print('\\rYYYYY', end='', flush=True)
+time.sleep(0.5)
+print('\\nNext Line', end='', flush=True)
+`;
+    const scriptPath = path.join(rig.testDir!, 'test_script.py');
+    fs.writeFileSync(scriptPath, script);
+
+    const prompt = `run_shell_command python3 "${scriptPath}"`;
+    await rig.run({ args: prompt });
+
+    let savedFilePath = '';
+    const tmpdir = path.join(rig.homeDir!, '.gemini', 'tmp');
+    if (fs.existsSync(tmpdir)) {
+      const findFiles = (dir: string): string[] => {
+        let results: string[] = [];
+        const list = fs.readdirSync(dir, { withFileTypes: true });
+        for (const file of list) {
+          const fullPath = path.join(dir, file.name);
+          if (file.isDirectory()) {
+            results = results.concat(findFiles(fullPath));
+          } else if (file.isFile() && file.name.endsWith('.txt')) {
+            results.push(fullPath);
+          }
+        }
+        return results;
+      };
+
+      const files = findFiles(tmpdir);
+      files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+
+      if (files.length > 0) {
+        savedFilePath = files[0];
+      }
+    }
+
+    expect(savedFilePath, 'Output file should exist').toBeTruthy();
+    const content = fs.readFileSync(savedFilePath, 'utf8');
+
+    // Verify it contains the large chunk
+    expect(content).toContain('AAAA');
+
+    // Verify cleanup logic:
+    // 1. The final text "YYYYY" should be present.
+    expect(content).toContain('YYYYY');
+    // 2. The next line should be present.
+    expect(content).toContain('Next Line');
+
+    // 3. Verify overwrite happened.
+    // In raw output, we would have "XXXXX...YYYYY".
+    // In processed output, "YYYYY" overwrites "XXXXX".
+    // We confirm that escape codes are stripped (processed text).
+
+    // 4. Check for ANSI escape codes (like \\x1b) just in case
+    expect(content).not.toContain('\x1b');
+  }, 60000);
+});

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.39.0-nightly.20260408.e77b22e63",
+  "version": "0.40.0-nightly.20260414.g5b1f7375a",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@google/gemini-cli",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "workspaces": [
         "packages/*"
       ],
@@ -1727,29 +1727,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/@joshua.litt/get-ripgrep": {
-      "version": "0.0.3",
-      "resolved": "https://registry.npmjs.org/@joshua.litt/get-ripgrep/-/get-ripgrep-0.0.3.tgz",
-      "integrity": "sha512-rycdieAKKqXi2bsM7G2ayDiNk5CAX8ZOzsTQsirfOqUKPef04Xw40BWGGyimaOOuvPgLWYt3tPnLLG3TvPXi5Q==",
-      "license": "MIT",
-      "dependencies": {
-        "@lvce-editor/verror": "^1.6.0",
-        "execa": "^9.5.2",
-        "extract-zip": "^2.0.1",
-        "fs-extra": "^11.3.0",
-        "got": "^14.4.5",
-        "path-exists": "^5.0.0",
-        "xdg-basedir": "^5.1.0"
-      }
-    },
-    "node_modules/@joshua.litt/get-ripgrep/node_modules/path-exists": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-5.0.0.tgz",
-      "integrity": "sha512-RjhtfwJOxzcFmNOi6ltcbcu4Iu+FL3zEj83dk4kAS+fVpTxXLO1b38RvJgT/0QwvV/L3aY9TAnyv0EOqW4GoMQ==",
-      "engines": {
-        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
-      }
-    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -1932,12 +1909,6 @@
       "integrity": "sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==",
       "license": "MIT"
     },
-    "node_modules/@lvce-editor/verror": {
-      "version": "1.7.0",
-      "resolved": "https://registry.npmjs.org/@lvce-editor/verror/-/verror-1.7.0.tgz",
-      "integrity": "sha512-+LGuAEIC2L7pbvkyAQVWM2Go0dAy+UWEui28g07zNtZsCBhm+gusBK8PNwLJLV5Jay+TyUYuwLIbJdjLLzqEBg==",
-      "license": "MIT"
-    },
     "node_modules/@lydell/node-pty": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@lydell/node-pty/-/node-pty-1.1.0.tgz",
@@ -3590,18 +3561,6 @@
         "url": "https://ko-fi.com/killymxi"
       }
     },
-    "node_modules/@sindresorhus/is": {
-      "version": "7.0.2",
-      "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.0.2.tgz",
-      "integrity": "sha512-d9xRovfKNz1SKieM0qJdO+PQonjnnIfSNWfHYnBSJ9hkjm0ZPw6HlxscDXYstp3z+7V2GOFHc+J0CYrYTjqCJw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sindresorhus/is?sponsor=1"
-      }
-    },
     "node_modules/@sindresorhus/merge-streams": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz",
@@ -3614,18 +3573,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/@szmarczak/http-timer": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/@szmarczak/http-timer/-/http-timer-5.0.1.tgz",
-      "integrity": "sha512-+PmQX0PiAYPMeVYe237LJAYvOMYW1j2rH5YROyS3b4CTVJum34HfRvKvAzozHAQG0TnHNdUfY9nCeUyRAs//cw==",
-      "license": "MIT",
-      "dependencies": {
-        "defer-to-connect": "^2.0.1"
-      },
-      "engines": {
-        "node": ">=14.16"
-      }
-    },
     "node_modules/@textlint/ast-node-types": {
       "version": "15.2.2",
       "resolved": "https://registry.npmjs.org/@textlint/ast-node-types/-/ast-node-types-15.2.2.tgz",
@@ -3931,12 +3878,6 @@
       "integrity": "sha512-pUY3cKH/Nm2yYrEmDlPR1mR7yszjGx4DrwPjQ702C4/D5CwHuZTgZdIdwPkRbcuhs7BAh2L5rg3CL5cbRiGTCQ==",
       "license": "MIT"
     },
-    "node_modules/@types/http-cache-semantics": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/@types/http-cache-semantics/-/http-cache-semantics-4.0.4.tgz",
-      "integrity": "sha512-1m0bIFVc7eJWyve9S0RnuRgcQqF/Xd5QsUZAZeQFr1Q3/p9JWoQQEqmVy+DPTNpGXwhgIetAoYF8JSc33q29QA==",
-      "license": "MIT"
-    },
     "node_modules/@types/http-errors": {
       "version": "2.0.5",
       "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
@@ -6008,33 +5949,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/cacheable-lookup": {
-      "version": "7.0.0",
-      "resolved": "https://registry.npmjs.org/cacheable-lookup/-/cacheable-lookup-7.0.0.tgz",
-      "integrity": "sha512-+qJyx4xiKra8mZrcwhjMRMUhD5NR1R8esPkzIYxX96JiecFoxAXFuz/GpR3+ev4PE1WamHip78wV0vcmPQtp8w==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=14.16"
-      }
-    },
-    "node_modules/cacheable-request": {
-      "version": "12.0.1",
-      "resolved": "https://registry.npmjs.org/cacheable-request/-/cacheable-request-12.0.1.tgz",
-      "integrity": "sha512-Yo9wGIQUaAfIbk+qY0X4cDQgCosecfBe3V9NSyeY4qPC2SAkbCS4Xj79VP8WOzitpJUZKc/wsRCYF5ariDIwkg==",
-      "license": "MIT",
-      "dependencies": {
-        "@types/http-cache-semantics": "^4.0.4",
-        "get-stream": "^9.0.1",
-        "http-cache-semantics": "^4.1.1",
-        "keyv": "^4.5.4",
-        "mimic-response": "^4.0.0",
-        "normalize-url": "^8.0.1",
-        "responselike": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/call-bind": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.8.tgz",
@@ -6968,33 +6882,6 @@
         }
       }
     },
-    "node_modules/decompress-response": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
-      "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
-      "license": "MIT",
-      "dependencies": {
-        "mimic-response": "^3.1.0"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "node_modules/decompress-response/node_modules/mimic-response": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz",
-      "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/deep-eql": {
       "version": "5.0.2",
       "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
@@ -7057,15 +6944,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/defer-to-connect": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/defer-to-connect/-/defer-to-connect-2.0.1.tgz",
-      "integrity": "sha512-4tvttepXG1VaYGrRibk5EwJd1t4udunSOVMdLSAL6mId1ix438oPwPZMALY41FCijukO1L0twNcGsdzS7dHgDg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/define-data-property": {
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/define-data-property/-/define-data-property-1.1.4.tgz",
@@ -8428,9 +8306,9 @@
       }
     },
     "node_modules/execa": {
-      "version": "9.6.0",
-      "resolved": "https://registry.npmjs.org/execa/-/execa-9.6.0.tgz",
-      "integrity": "sha512-jpWzZ1ZhwUmeWRhS7Qv3mhpOhLfwI+uAX4e5fOcXqwMR7EcJ0pj2kV1CVzHVMX/LphnKWD3LObjZCoJ71lKpHw==",
+      "version": "9.6.1",
+      "resolved": "https://registry.npmjs.org/execa/-/execa-9.6.1.tgz",
+      "integrity": "sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==",
       "license": "MIT",
       "dependencies": {
         "@sindresorhus/merge-streams": "^4.0.0",
@@ -8950,15 +8828,6 @@
         "node": ">= 6"
       }
     },
-    "node_modules/form-data-encoder": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/form-data-encoder/-/form-data-encoder-4.1.0.tgz",
-      "integrity": "sha512-G6NsmEW15s0Uw9XnCg+33H3ViYRyiM0hMrMhhqQOR8NFc5GhYrI+6I3u7OTw7b91J2g8rtvMBZJDbcGb2YUniw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 18"
-      }
-    },
     "node_modules/form-data/node_modules/mime-types": {
       "version": "2.1.35",
       "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
@@ -9586,43 +9455,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/got": {
-      "version": "14.4.8",
-      "resolved": "https://registry.npmjs.org/got/-/got-14.4.8.tgz",
-      "integrity": "sha512-vxwU4HuR0BIl+zcT1LYrgBjM+IJjNElOjCzs0aPgHorQyr/V6H6Y73Sn3r3FOlUffvWD+Q5jtRuGWaXkU8Jbhg==",
-      "license": "MIT",
-      "dependencies": {
-        "@sindresorhus/is": "^7.0.1",
-        "@szmarczak/http-timer": "^5.0.1",
-        "cacheable-lookup": "^7.0.0",
-        "cacheable-request": "^12.0.1",
-        "decompress-response": "^6.0.0",
-        "form-data-encoder": "^4.0.2",
-        "http2-wrapper": "^2.2.1",
-        "lowercase-keys": "^3.0.0",
-        "p-cancelable": "^4.0.1",
-        "responselike": "^3.0.0",
-        "type-fest": "^4.26.1"
-      },
-      "engines": {
-        "node": ">=20"
-      },
-      "funding": {
-        "url": "https://github.com/sindresorhus/got?sponsor=1"
-      }
-    },
-    "node_modules/got/node_modules/type-fest": {
-      "version": "4.41.0",
-      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz",
-      "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==",
-      "license": "(MIT OR CC0-1.0)",
-      "engines": {
-        "node": ">=16"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/graceful-fs": {
       "version": "4.2.11",
       "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
@@ -9878,12 +9710,6 @@
         "entities": "^4.4.0"
       }
     },
-    "node_modules/http-cache-semantics": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz",
-      "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==",
-      "license": "BSD-2-Clause"
-    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
@@ -9917,19 +9743,6 @@
         "node": ">= 14"
       }
     },
-    "node_modules/http2-wrapper": {
-      "version": "2.2.1",
-      "resolved": "https://registry.npmjs.org/http2-wrapper/-/http2-wrapper-2.2.1.tgz",
-      "integrity": "sha512-V5nVw1PAOgfI3Lmeaj2Exmeg7fenjhRUgz1lPSezy1CuhPYbgQtbQj4jZfEAEMlaL+vupsvhjqCyjzob0yxsmQ==",
-      "license": "MIT",
-      "dependencies": {
-        "quick-lru": "^5.1.1",
-        "resolve-alpn": "^1.2.0"
-      },
-      "engines": {
-        "node": ">=10.19.0"
-      }
-    },
     "node_modules/https-proxy-agent": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
@@ -11040,6 +10853,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
       "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/json-parse-better-errors": {
@@ -11235,6 +11049,7 @@
       "version": "4.5.4",
       "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
       "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "json-buffer": "3.0.1"
@@ -11699,18 +11514,6 @@
       "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
       "license": "MIT"
     },
-    "node_modules/lowercase-keys": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-3.0.0.tgz",
-      "integrity": "sha512-ozCC6gdQ+glXOQsveKD0YsDy8DSQFjDTz4zyzEHNV5+JP5D62LmfDZ6o1cycFx9ouG940M5dE8C8CTewdj2YWQ==",
-      "license": "MIT",
-      "engines": {
-        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/lowlight": {
       "version": "3.3.0",
       "resolved": "https://registry.npmjs.org/lowlight/-/lowlight-3.3.0.tgz",
@@ -11981,18 +11784,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/mimic-response": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-4.0.0.tgz",
-      "integrity": "sha512-e5ISH9xMYU0DzrT+jl8q2ze9D6eWBto+I8CNpe+VI+K2J/F/k3PdkdTdz4wvGVH4NTpo+NRYTVIuMQEMMcsLqg==",
-      "license": "MIT",
-      "engines": {
-        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/minimatch": {
       "version": "10.2.4",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
@@ -12371,18 +12162,6 @@
         "node": "^16.14.0 || >=18.0.0"
       }
     },
-    "node_modules/normalize-url": {
-      "version": "8.0.2",
-      "resolved": "https://registry.npmjs.org/normalize-url/-/normalize-url-8.0.2.tgz",
-      "integrity": "sha512-Ee/R3SyN4BuynXcnTaekmaVdbDAEiNrHqjQIA37mHU8G9pf7aaAD4ZX3XjBLo6rsdcxA/gtkcNYZLt30ACgynw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=14.16"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/npm-normalize-package-bin": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/npm-normalize-package-bin/-/npm-normalize-package-bin-4.0.0.tgz",
@@ -12895,15 +12674,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/p-cancelable": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-4.0.1.tgz",
-      "integrity": "sha512-wBowNApzd45EIKdO1LaU+LrMBwAcjfPaYtVzV3lmfM3gf8Z4CHZsiIqlM8TZZ8okYvh5A1cP6gTfCRQtwUpaUg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=14.16"
-      }
-    },
     "node_modules/p-limit": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
@@ -13743,18 +13513,6 @@
       ],
       "license": "MIT"
     },
-    "node_modules/quick-lru": {
-      "version": "5.1.1",
-      "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz",
-      "integrity": "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/range-parser": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
@@ -14195,12 +13953,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/resolve-alpn": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/resolve-alpn/-/resolve-alpn-1.2.1.tgz",
-      "integrity": "sha512-0a1F4l73/ZFZOakJnQ3FvkJ2+gSTQWz/r2KE5OdDY0TxPm5h4GkqkWWfM47T7HsbnOtcJVEF4epCVy6u7Q3K+g==",
-      "license": "MIT"
-    },
     "node_modules/resolve-dir": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/resolve-dir/-/resolve-dir-1.0.1.tgz",
@@ -14235,21 +13987,6 @@
         "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
       }
     },
-    "node_modules/responselike": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/responselike/-/responselike-3.0.0.tgz",
-      "integrity": "sha512-40yHxbNcl2+rzXvZuVkrYohathsSJlMTXKryG5y8uciHv1+xDLHQpgjG64JUO9nrEq2jGLH6IZ8BcZyw3wrweg==",
-      "license": "MIT",
-      "dependencies": {
-        "lowercase-keys": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=14.16"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/restore-cursor": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-4.0.0.tgz",
@@ -17644,18 +17381,6 @@
         }
       }
     },
-    "node_modules/xdg-basedir": {
-      "version": "5.1.0",
-      "resolved": "https://registry.npmjs.org/xdg-basedir/-/xdg-basedir-5.1.0.tgz",
-      "integrity": "sha512-GCPAHLvrIH13+c0SuacwvRYj2SxJXQ4kaVTT5xgL3kPrz56XxkF21IGhjSE1+W0aw7gpBWRGXLCPnPby6lSpmQ==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=12"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/xml2js": {
       "version": "0.5.0",
       "resolved": "https://registry.npmjs.org/xml2js/-/xml2js-0.5.0.tgz",
@@ -17864,7 +17589,7 @@
     },
     "packages/a2a-server": {
       "name": "@google/gemini-cli-a2a-server",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "dependencies": {
         "@a2a-js/sdk": "0.3.11",
         "@google-cloud/storage": "^7.16.0",
@@ -17979,7 +17704,7 @@
     },
     "packages/cli": {
       "name": "@google/gemini-cli",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.16.1",
@@ -18079,44 +17804,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/cli/node_modules/execa": {
-      "version": "9.6.1",
-      "resolved": "https://registry.npmjs.org/execa/-/execa-9.6.1.tgz",
-      "integrity": "sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==",
-      "license": "MIT",
-      "dependencies": {
-        "@sindresorhus/merge-streams": "^4.0.0",
-        "cross-spawn": "^7.0.6",
-        "figures": "^6.1.0",
-        "get-stream": "^9.0.0",
-        "human-signals": "^8.0.1",
-        "is-plain-obj": "^4.1.0",
-        "is-stream": "^4.0.1",
-        "npm-run-path": "^6.0.0",
-        "pretty-ms": "^9.2.0",
-        "signal-exit": "^4.1.0",
-        "strip-final-newline": "^4.0.0",
-        "yoctocolors": "^2.1.1"
-      },
-      "engines": {
-        "node": "^18.19.0 || >=20.5.0"
-      },
-      "funding": {
-        "url": "https://github.com/sindresorhus/execa?sponsor=1"
-      }
-    },
-    "packages/cli/node_modules/is-stream": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-4.0.1.tgz",
-      "integrity": "sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "packages/cli/node_modules/string-width": {
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.1.0.tgz",
@@ -18151,7 +17838,7 @@
     },
     "packages/core": {
       "name": "@google/gemini-cli-core",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "license": "Apache-2.0",
       "dependencies": {
         "@a2a-js/sdk": "0.3.11",
@@ -18162,7 +17849,6 @@
         "@google/genai": "1.30.0",
         "@grpc/grpc-js": "^1.14.3",
         "@iarna/toml": "^2.2.5",
-        "@joshua.litt/get-ripgrep": "^0.0.3",
         "@modelcontextprotocol/sdk": "^1.23.0",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/api-logs": "^0.211.0",
@@ -18190,6 +17876,7 @@
         "diff": "^8.0.3",
         "dotenv": "^17.2.4",
         "dotenv-expand": "^12.0.3",
+        "execa": "^9.6.1",
         "fast-levenshtein": "^2.0.6",
         "fdir": "^6.4.6",
         "fzf": "^0.5.2",
@@ -18418,7 +18105,7 @@
     },
     "packages/devtools": {
       "name": "@google/gemini-cli-devtools",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "license": "Apache-2.0",
       "dependencies": {
         "ws": "^8.16.0"
@@ -18433,7 +18120,7 @@
     },
     "packages/sdk": {
       "name": "@google/gemini-cli-sdk",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "license": "Apache-2.0",
       "dependencies": {
         "@google/gemini-cli-core": "file:../core",
@@ -18450,7 +18137,7 @@
     },
     "packages/test-utils": {
       "name": "@google/gemini-cli-test-utils",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "license": "Apache-2.0",
       "dependencies": {
         "@google/gemini-cli-core": "file:../core",
@@ -18468,7 +18155,7 @@
     },
     "packages/vscode-ide-companion": {
       "name": "gemini-cli-vscode-ide-companion",
-      "version": "0.39.0-nightly.20260408.e77b22e63",
+      "version": "0.40.0-nightly.20260414.g5b1f7375a",
       "license": "LICENSE",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.23.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.39.0-nightly.20260408.e77b22e63",
+  "version": "0.40.0-nightly.20260414.g5b1f7375a",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -14,7 +14,7 @@
     "url": "git+https://github.com/google-gemini/gemini-cli.git"
   },
   "config": {
-    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.39.0-nightly.20260408.e77b22e63"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.40.0-nightly.20260414.g5b1f7375a"
   },
   "scripts": {
     "start": "cross-env NODE_ENV=development node scripts/start.js",

packages/a2a-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli-a2a-server",
-  "version": "0.39.0-nightly.20260408.e77b22e63",
+  "version": "0.40.0-nightly.20260414.g5b1f7375a",
   "description": "Gemini CLI A2A Server",
   "repository": {
     "type": "git",

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli",
-  "version": "0.39.0-nightly.20260408.e77b22e63",
+  "version": "0.40.0-nightly.20260414.g5b1f7375a",
   "description": "Gemini CLI",
   "license": "Apache-2.0",
   "repository": {
@@ -27,7 +27,7 @@
     "dist"
   ],
   "config": {
-    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.39.0-nightly.20260408.e77b22e63"
+    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.40.0-nightly.20260414.g5b1f7375a"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.16.1",

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

@@ -62,6 +62,7 @@ describe('fetchJson', () => {
       const res = new EventEmitter() as IncomingMessage;
       res.statusCode = 302;
       res.headers = { location: 'https://example.com/final' };
+      res.resume = vi.fn();
       (callback as (res: IncomingMessage) => void)(res);
       res.emit('end');
       return new EventEmitter() as ClientRequest;
@@ -85,6 +86,7 @@ describe('fetchJson', () => {
       const res = new EventEmitter() as IncomingMessage;
       res.statusCode = 301;
       res.headers = { location: 'https://example.com/final-permanent' };
+      res.resume = vi.fn();
       (callback as (res: IncomingMessage) => void)(res);
       res.emit('end');
       return new EventEmitter() as ClientRequest;

packages/cli/src/config/extensions/github_fetch.ts

@@ -31,7 +31,11 @@ export async function fetchJson<T>(
           if (!res.headers.location) {
             return reject(new Error('No location header in redirect response'));
           }
-          fetchJson<T>(res.headers.location, redirectCount++)
+          res.resume();
+          fetchJson<T>(
+            new URL(res.headers.location, url).toString(),
+            redirectCount + 1,
+          )
             .then(resolve)
             .catch(reject);
           return;

packages/cli/src/ui/auth/ApiAuthDialog.test.tsx

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { render } from '../../test-utils/render.js';
+import { renderWithProviders } from '../../test-utils/render.js';
 import { waitFor } from '../../test-utils/async.js';
 import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
 import { ApiAuthDialog } from './ApiAuthDialog.js';
@@ -40,11 +40,16 @@ vi.mock('../components/shared/text-buffer.js', async (importOriginal) => {
   };
 });
 
-vi.mock('../contexts/UIStateContext.js', () => ({
-  useUIState: vi.fn(() => ({
-    terminalWidth: 80,
-  })),
-}));
+vi.mock('../contexts/UIStateContext.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../contexts/UIStateContext.js')>();
+  return {
+    ...actual,
+    useUIState: vi.fn(() => ({
+      terminalWidth: 80,
+    })),
+  };
+});
 
 const mockedUseKeypress = useKeypress as Mock;
 const mockedUseTextBuffer = useTextBuffer as Mock;
@@ -73,7 +78,7 @@ describe('ApiAuthDialog', () => {
   });
 
   it('renders correctly', async () => {
-    const { lastFrame, unmount } = await render(
+    const { lastFrame, unmount } = await renderWithProviders(
       <ApiAuthDialog onSubmit={onSubmit} onCancel={onCancel} />,
     );
     expect(lastFrame()).toMatchSnapshot();
@@ -81,7 +86,7 @@ describe('ApiAuthDialog', () => {
   });
 
   it('renders with a defaultValue', async () => {
-    const { unmount } = await render(
+    const { unmount } = await renderWithProviders(
       <ApiAuthDialog
         onSubmit={onSubmit}
         onCancel={onCancel}
@@ -111,7 +116,7 @@ describe('ApiAuthDialog', () => {
     'calls $expectedCall.name when $keyName is pressed',
     async ({ keyName, sequence, expectedCall, args }) => {
       mockBuffer.text = 'submitted-key'; // Set for the onSubmit case
-      const { unmount } = await render(
+      const { unmount } = await renderWithProviders(
         <ApiAuthDialog onSubmit={onSubmit} onCancel={onCancel} />,
       );
       // calls[0] is the ApiAuthDialog's useKeypress (Ctrl+C handler)
@@ -133,7 +138,7 @@ describe('ApiAuthDialog', () => {
   );
 
   it('displays an error message', async () => {
-    const { lastFrame, unmount } = await render(
+    const { lastFrame, unmount } = await renderWithProviders(
       <ApiAuthDialog
         onSubmit={onSubmit}
         onCancel={onCancel}
@@ -146,7 +151,7 @@ describe('ApiAuthDialog', () => {
   });
 
   it('calls clearApiKey and clears buffer when Ctrl+C is pressed', async () => {
-    const { unmount } = await render(
+    const { unmount } = await renderWithProviders(
       <ApiAuthDialog onSubmit={onSubmit} onCancel={onCancel} />,
     );
     // Call 0 is ApiAuthDialog (isActive: true)

packages/cli/src/ui/components/AnsiOutput.tsx

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type React from 'react';
+import React from 'react';
 import { Box, Text } from 'ink';
 import type { AnsiLine, AnsiOutput, AnsiToken } from '@google/gemini-cli-core';
 
@@ -53,23 +53,26 @@ export const AnsiOutputText: React.FC<AnsiOutputProps> = ({
   );
 };
 
-export const AnsiLineText: React.FC<{ line: AnsiLine }> = ({ line }) => (
-  <Text>
-    {line.length > 0
-      ? line.map((token: AnsiToken, tokenIndex: number) => (
-          <Text
-            key={tokenIndex}
-            color={token.fg}
-            backgroundColor={token.bg}
-            inverse={token.inverse}
-            dimColor={token.dim}
-            bold={token.bold}
-            italic={token.italic}
-            underline={token.underline}
-          >
-            {token.text}
-          </Text>
-        ))
-      : null}
-  </Text>
+export const AnsiLineText = React.memo<{ line: AnsiLine }>(
+  ({ line }: { line: AnsiLine }) => (
+    <Text>
+      {line.length > 0
+        ? line.map((token: AnsiToken, tokenIndex: number) => (
+            <Text
+              key={tokenIndex}
+              color={token.fg}
+              backgroundColor={token.bg}
+              inverse={token.inverse}
+              dimColor={token.dim}
+              bold={token.bold}
+              italic={token.italic}
+              underline={token.underline}
+            >
+              {token.text}
+            </Text>
+          ))
+        : null}
+    </Text>
+  ),
 );
+AnsiLineText.displayName = 'AnsiLineText';

packages/cli/src/ui/components/AskUserDialog.tsx

@@ -13,7 +13,8 @@ import {
   useReducer,
   useContext,
 } from 'react';
-import { Box, Text } from 'ink';
+import { Box, Text, type DOMElement } from 'ink';
+import { useMouseClick } from '../hooks/useMouseClick.js';
 import { theme } from '../semantic-colors.js';
 import { checkExhaustive, type Question } from '@google/gemini-cli-core';
 import { BaseSelectionList } from './shared/BaseSelectionList.js';
@@ -85,6 +86,24 @@ function autoBoldIfPlain(text: string): string {
   return text;
 }
 
+const ClickableCheckbox: React.FC<{
+  isChecked: boolean;
+  onClick: () => void;
+}> = ({ isChecked, onClick }) => {
+  const ref = useRef<DOMElement>(null);
+  useMouseClick(ref, () => {
+    onClick();
+  });
+
+  return (
+    <Box ref={ref}>
+      <Text color={isChecked ? theme.status.success : theme.text.secondary}>
+        [{isChecked ? 'x' : ' '}]
+      </Text>
+    </Box>
+  );
+};
+
 interface AskUserDialogState {
   answers: { [key: string]: string };
   isEditingCustomOption: boolean;
@@ -919,13 +938,14 @@ const ChoiceQuestionView: React.FC<ChoiceQuestionViewProps> = ({
             return (
               <Box flexDirection="row">
                 {showCheck && (
-                  <Text
-                    color={
-                      isChecked ? theme.status.success : theme.text.secondary
-                    }
-                  >
-                    [{isChecked ? 'x' : ' '}]
-                  </Text>
+                  <ClickableCheckbox
+                    isChecked={isChecked}
+                    onClick={() => {
+                      if (!context.isSelected) {
+                        handleSelect(optionItem);
+                      }
+                    }}
+                  />
                 )}
                 <Text color={theme.text.primary}> </Text>
                 <TextInput
@@ -966,13 +986,14 @@ const ChoiceQuestionView: React.FC<ChoiceQuestionViewProps> = ({
             <Box flexDirection="column">
               <Box flexDirection="row">
                 {showCheck && (
-                  <Text
-                    color={
-                      isChecked ? theme.status.success : theme.text.secondary
-                    }
-                  >
-                    [{isChecked ? 'x' : ' '}]
-                  </Text>
+                  <ClickableCheckbox
+                    isChecked={isChecked}
+                    onClick={() => {
+                      if (!context.isSelected) {
+                        handleSelect(optionItem);
+                      }
+                    }}
+                  />
                 )}
                 <Text color={labelColor} bold={optionItem.type === 'done'}>
                   {' '}

packages/cli/src/ui/components/InputPrompt.test.tsx

@@ -3877,8 +3877,9 @@ describe('InputPrompt', () => {
 
       // 1. Verify initial placeholder
       await waitFor(() => {
-        expect(stdout.lastFrame()).toMatchSnapshot();
+        expect(stdout.lastFrame()).toContain('[Pasted Text: 10 lines]');
       });
+      expect(stdout.lastFrame()).toMatchSnapshot();
 
       // Simulate double-click to expand
       await simulateClick(5, 2);
@@ -3886,8 +3887,9 @@ describe('InputPrompt', () => {
 
       // 2. Verify expanded content is visible
       await waitFor(() => {
-        expect(stdout.lastFrame()).toMatchSnapshot();
+        expect(stdout.lastFrame()).toContain('line10');
       });
+      expect(stdout.lastFrame()).toMatchSnapshot();
 
       // Simulate double-click to collapse
       await simulateClick(5, 2);
@@ -3895,8 +3897,9 @@ describe('InputPrompt', () => {
 
       // 3. Verify placeholder is restored
       await waitFor(() => {
-        expect(stdout.lastFrame()).toMatchSnapshot();
+        expect(stdout.lastFrame()).toContain('[Pasted Text: 10 lines]');
       });
+      expect(stdout.lastFrame()).toMatchSnapshot();
 
       unmount();
     });

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

@@ -156,7 +156,16 @@ exports[`InputPrompt > mouse interaction > should toggle paste expansion on doub
 
 exports[`InputPrompt > mouse interaction > should toggle paste expansion on double-click 2`] = `
 "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
- > [Pasted Text: 10 lines]                                                                          
+ > line1                                                                                            
+   line2                                                                                            
+   line3                                                                                            
+   line4                                                                                            
+   line5                                                                                            
+   line6                                                                                            
+   line7                                                                                            
+   line8                                                                                            
+   line9                                                                                            
+   line10                                                                                           
 ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
 "
 `;

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

@@ -11,12 +11,12 @@ exports[`Initial Theme Selection > should default to a dark theme when terminal
 │ ●  4. Default Dark (Matches terminal)        │ 3     a, b = 0, 1                               │ │
 │    5. Dracula Dark                           │ 4     for _ in range(n):                        │ │
 │    6. GitHub Dark                            │ 5         a, b = b, a + b                       │ │
-│    7. Holiday Dark                           │ 6     return a                                  │ │
-│    8. Shades Of Purple Dark                  │                                                 │ │
-│    9. Solarized Dark                         │ 1 - print("Hello, " + name)                     │ │
-│   10. Tokyo Night Dark                       │ 1 + print(f"Hello, {name}!")                    │ │
-│   11. ANSI Light                             │                                                 │ │
-│   12. Ayu Light                              └─────────────────────────────────────────────────┘ │
+│    7. GitHub Dark Colorblind Dark            │ 6     return a                                  │ │
+│    8. Holiday Dark                           │                                                 │ │
+│    9. Shades Of Purple Dark                  │ 1 - print("Hello, " + name)                     │ │
+│   10. Solarized Dark                         │ 1 + print(f"Hello, {name}!")                    │ │
+│   11. Tokyo Night Dark                       │                                                 │ │
+│   12. ANSI Light                             └─────────────────────────────────────────────────┘ │
 │ ▼                                                                                                │
 │                                                                                                  │
 │ (Use Enter to select, Tab to configure scope, Esc to close)                                      │
@@ -34,14 +34,14 @@ exports[`Initial Theme Selection > should default to a light theme when terminal
 │    2. Ayu Light                              │ 1 # function                                    │ │
 │ ●  3. Default Light                          │ 2 def fibonacci(n):                             │ │
 │    4. GitHub Light                           │ 3     a, b = 0, 1                               │ │
-│    5. Google Code Light                      │ 4     for _ in range(n):                        │ │
-│    6. Solarized Light                        │ 5         a, b = b, a + b                       │ │
-│    7. Xcode Light                            │ 6     return a                                  │ │
-│    8. ANSI Dark (Incompatible)               │                                                 │ │
-│    9. Atom One Dark (Incompatible)           │ 1 - print("Hello, " + name)                     │ │
-│   10. Ayu Dark (Incompatible)                │ 1 + print(f"Hello, {name}!")                    │ │
-│   11. Default Dark (Incompatible)            │                                                 │ │
-│   12. Dracula Dark (Incompatible)            └─────────────────────────────────────────────────┘ │
+│    5. GitHub Light Colorblind Light (Mat…    │ 4     for _ in range(n):                        │ │
+│    6. Google Code Light                      │ 5         a, b = b, a + b                       │ │
+│    7. Solarized Light                        │ 6     return a                                  │ │
+│    8. Xcode Light                            │                                                 │ │
+│    9. ANSI Dark (Incompatible)               │ 1 - print("Hello, " + name)                     │ │
+│   10. Atom One Dark (Incompatible)           │ 1 + print(f"Hello, {name}!")                    │ │
+│   11. Ayu Dark (Incompatible)                │                                                 │ │
+│   12. Default Dark (Incompatible)            └─────────────────────────────────────────────────┘ │
 │ ▼                                                                                                │
 │                                                                                                  │
 │ (Use Enter to select, Tab to configure scope, Esc to close)                                      │
@@ -61,12 +61,12 @@ exports[`Initial Theme Selection > should use the theme from settings even if te
 │    4. Default Dark (Matches terminal)        │ 3     a, b = 0, 1                               │ │
 │    5. Dracula Dark                           │ 4     for _ in range(n):                        │ │
 │    6. GitHub Dark                            │ 5         a, b = b, a + b                       │ │
-│    7. Holiday Dark                           │ 6     return a                                  │ │
-│    8. Shades Of Purple Dark                  │                                                 │ │
-│    9. Solarized Dark                         │ 1 - print("Hello, " + name)                     │ │
-│   10. Tokyo Night Dark                       │ 1 + print(f"Hello, {name}!")                    │ │
-│   11. ANSI Light                             │                                                 │ │
-│   12. Ayu Light                              └─────────────────────────────────────────────────┘ │
+│    7. GitHub Dark Colorblind Dark            │ 6     return a                                  │ │
+│    8. Holiday Dark                           │                                                 │ │
+│    9. Shades Of Purple Dark                  │ 1 - print("Hello, " + name)                     │ │
+│   10. Solarized Dark                         │ 1 + print(f"Hello, {name}!")                    │ │
+│   11. Tokyo Night Dark                       │                                                 │ │
+│   12. ANSI Light                             └─────────────────────────────────────────────────┘ │
 │ ▼                                                                                                │
 │                                                                                                  │
 │ (Use Enter to select, Tab to configure scope, Esc to close)                                      │
@@ -100,12 +100,12 @@ exports[`ThemeDialog Snapshots > should render correctly in theme selection mode
 │    4. Default Dark                           │ 3     a, b = 0, 1                               │ │
 │    5. Dracula Dark                           │ 4     for _ in range(n):                        │ │
 │    6. GitHub Dark                            │ 5         a, b = b, a + b                       │ │
-│    7. Holiday Dark                           │ 6     return a                                  │ │
-│    8. Shades Of Purple Dark                  │                                                 │ │
-│    9. Solarized Dark                         │ 1 - print("Hello, " + name)                     │ │
-│   10. Tokyo Night Dark                       │ 1 + print(f"Hello, {name}!")                    │ │
-│   11. ANSI Light                             │                                                 │ │
-│   12. Ayu Light                              └─────────────────────────────────────────────────┘ │
+│    7. GitHub Dark Colorblind Dark            │ 6     return a                                  │ │
+│    8. Holiday Dark                           │                                                 │ │
+│    9. Shades Of Purple Dark                  │ 1 - print("Hello, " + name)                     │ │
+│   10. Solarized Dark                         │ 1 + print(f"Hello, {name}!")                    │ │
+│   11. Tokyo Night Dark                       │                                                 │ │
+│   12. ANSI Light                             └─────────────────────────────────────────────────┘ │
 │ ▼                                                                                                │
 │                                                                                                  │
 │ (Use Enter to select, Tab to configure scope, Esc to close)                                      │
@@ -125,12 +125,12 @@ exports[`ThemeDialog Snapshots > should render correctly in theme selection mode
 │    4. Default Dark                           │ 3     a, b = 0, 1                               │ │
 │    5. Dracula Dark                           │ 4     for _ in range(n):                        │ │
 │    6. GitHub Dark                            │ 5         a, b = b, a + b                       │ │
-│    7. Holiday Dark                           │ 6     return a                                  │ │
-│    8. Shades Of Purple Dark                  │                                                 │ │
-│    9. Solarized Dark                         │ 1 - print("Hello, " + name)                     │ │
-│   10. Tokyo Night Dark                       │ 1 + print(f"Hello, {name}!")                    │ │
-│   11. ANSI Light                             │                                                 │ │
-│   12. Ayu Light                              └─────────────────────────────────────────────────┘ │
+│    7. GitHub Dark Colorblind Dark            │ 6     return a                                  │ │
+│    8. Holiday Dark                           │                                                 │ │
+│    9. Shades Of Purple Dark                  │ 1 - print("Hello, " + name)                     │ │
+│   10. Solarized Dark                         │ 1 + print(f"Hello, {name}!")                    │ │
+│   11. Tokyo Night Dark                       │                                                 │ │
+│   12. ANSI Light                             └─────────────────────────────────────────────────┘ │
 │ ▼                                                                                                │
 │                                              ╭─────────────────────────────────────────────────╮ │
 │                                              │ DEVELOPER TOOLS (Not visible to users)          │ │

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

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { act } from 'react';
 import { renderWithProviders } from '../../../test-utils/render.js';
 import {
   BaseSelectionList,
@@ -14,8 +15,10 @@ import {
 import { useSelectionList } from '../../hooks/useSelectionList.js';
 import { Text } from 'ink';
 import type { theme } from '../../semantic-colors.js';
+import { useMouseClick } from '../../hooks/useMouseClick.js';
 
 vi.mock('../../hooks/useSelectionList.js');
+vi.mock('../../hooks/useMouseClick.js');
 
 const mockTheme = {
   text: { primary: 'COLOR_PRIMARY', secondary: 'COLOR_SECONDARY' },
@@ -35,6 +38,7 @@ describe('BaseSelectionList', () => {
   const mockOnSelect = vi.fn();
   const mockOnHighlight = vi.fn();
   const mockRenderItem = vi.fn();
+  const mockSetActiveIndex = vi.fn();
 
   const items = [
     { value: 'A', label: 'Item A', key: 'A' },
@@ -54,7 +58,7 @@ describe('BaseSelectionList', () => {
   ) => {
     vi.mocked(useSelectionList).mockReturnValue({
       activeIndex,
-      setActiveIndex: vi.fn(),
+      setActiveIndex: mockSetActiveIndex,
     });
 
     mockRenderItem.mockImplementation(
@@ -484,6 +488,79 @@ describe('BaseSelectionList', () => {
     });
   });
 
+  describe('Mouse Interaction', () => {
+    it('should register mouse click handler for each item', async () => {
+      const { unmount } = await renderComponent();
+
+      // items are A, B (disabled), C
+      expect(useMouseClick).toHaveBeenCalledTimes(3);
+      unmount();
+    });
+
+    it('should update activeIndex on first click and call onSelect on second click', async () => {
+      const { unmount, waitUntilReady } = await renderComponent();
+      await waitUntilReady();
+
+      // items[0] is 'A' (enabled)
+      // items[1] is 'B' (disabled)
+      // items[2] is 'C' (enabled)
+
+      // Get the mouse click handler for the third item (index 2)
+      const mouseClickHandler = (useMouseClick as Mock).mock.calls[2][1];
+
+      // First click on item C
+      act(() => {
+        mouseClickHandler();
+      });
+
+      expect(mockSetActiveIndex).toHaveBeenCalledWith(2);
+      expect(mockOnSelect).not.toHaveBeenCalled();
+
+      // Now simulate being on item C (isSelected = true)
+      // Rerender or update mocks for the next check
+      await renderComponent({}, 2);
+
+      // Get the updated mouse click handler for item C
+      // useMouseClick is called 3 more times on rerender
+      const updatedMouseClickHandler = (useMouseClick as Mock).mock.calls[5][1];
+
+      // Second click on item C
+      act(() => {
+        updatedMouseClickHandler();
+      });
+
+      expect(mockOnSelect).toHaveBeenCalledWith('C');
+      unmount();
+    });
+
+    it('should not call onSelect when a disabled item is clicked', async () => {
+      const { unmount, waitUntilReady } = await renderComponent();
+      await waitUntilReady();
+
+      // items[1] is 'B' (disabled)
+      const mouseClickHandler = (useMouseClick as Mock).mock.calls[1][1];
+
+      act(() => {
+        mouseClickHandler();
+      });
+
+      expect(mockSetActiveIndex).not.toHaveBeenCalled();
+      expect(mockOnSelect).not.toHaveBeenCalled();
+      unmount();
+    });
+
+    it('should pass isActive: isFocused to useMouseClick', async () => {
+      const { unmount } = await renderComponent({ isFocused: false });
+
+      expect(useMouseClick).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.any(Function),
+        { isActive: false },
+      );
+      unmount();
+    });
+  });
+
   describe('Scroll Arrows (showScrollArrows)', () => {
     const longList = Array.from({ length: 10 }, (_, i) => ({
       value: `Item ${i + 1}`,

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

@@ -5,13 +5,14 @@
  */
 
 import type React from 'react';
-import { useState } from 'react';
-import { Text, Box } from 'ink';
+import { useState, useRef } from 'react';
+import { Text, Box, type DOMElement } from 'ink';
 import { theme } from '../../semantic-colors.js';
 import {
   useSelectionList,
   type SelectionListItem,
 } from '../../hooks/useSelectionList.js';
+import { useMouseClick } from '../../hooks/useMouseClick.js';
 
 export interface RenderItemContext {
   isSelected: boolean;
@@ -38,6 +39,119 @@ export interface BaseSelectionListProps<
   renderItem: (item: TItem, context: RenderItemContext) => React.ReactNode;
 }
 
+interface SelectionListItemRowProps<
+  T,
+  TItem extends SelectionListItem<T> = SelectionListItem<T>,
+> {
+  item: TItem;
+  itemIndex: number;
+  isSelected: boolean;
+  isFocused: boolean;
+  showNumbers: boolean;
+  selectedIndicator: string;
+  numberColumnWidth: number;
+  onSelect: (value: T) => void;
+  setActiveIndex: (index: number) => void;
+  renderItem: (item: TItem, context: RenderItemContext) => React.ReactNode;
+}
+
+function SelectionListItemRow<
+  T,
+  TItem extends SelectionListItem<T> = SelectionListItem<T>,
+>({
+  item,
+  itemIndex,
+  isSelected,
+  isFocused,
+  showNumbers,
+  selectedIndicator,
+  numberColumnWidth,
+  onSelect,
+  setActiveIndex,
+  renderItem,
+}: SelectionListItemRowProps<T, TItem>) {
+  const containerRef = useRef<DOMElement>(null);
+
+  useMouseClick(
+    containerRef,
+    () => {
+      if (!item.disabled) {
+        if (isSelected) {
+          // Second click on the same item triggers submission
+          onSelect(item.value);
+        } else {
+          // First click highlights the item
+          setActiveIndex(itemIndex);
+        }
+      }
+    },
+    { isActive: isFocused },
+  );
+
+  let titleColor = theme.text.primary;
+  let numberColor = theme.text.primary;
+
+  if (isSelected) {
+    titleColor = theme.ui.focus;
+    numberColor = theme.ui.focus;
+  } else if (item.disabled) {
+    titleColor = theme.text.secondary;
+    numberColor = theme.text.secondary;
+  }
+
+  if (!isFocused && !item.disabled) {
+    numberColor = theme.text.secondary;
+  }
+
+  if (!showNumbers) {
+    numberColor = theme.text.secondary;
+  }
+
+  const itemNumberText = `${String(itemIndex + 1).padStart(
+    numberColumnWidth,
+  )}.`;
+
+  return (
+    <Box
+      ref={containerRef}
+      key={item.key}
+      alignItems="flex-start"
+      backgroundColor={isSelected ? theme.background.focus : undefined}
+    >
+      {/* Radio button indicator */}
+      <Box minWidth={2} flexShrink={0}>
+        <Text
+          color={isSelected ? theme.ui.focus : theme.text.primary}
+          aria-hidden
+        >
+          {isSelected ? selectedIndicator : ' '}
+        </Text>
+      </Box>
+
+      {/* Item number */}
+      {showNumbers && !item.hideNumber && (
+        <Box
+          marginRight={1}
+          flexShrink={0}
+          minWidth={itemNumberText.length}
+          aria-state={{ checked: isSelected }}
+        >
+          <Text color={numberColor}>{itemNumberText}</Text>
+        </Box>
+      )}
+
+      {/* Custom content via render prop */}
+      <Box flexGrow={1}>
+        {renderItem(item, {
+          isSelected,
+          titleColor,
+          numberColor,
+        })}
+      </Box>
+    </Box>
+  );
+}
+
 /**
  * Base component for selection lists that provides common UI structure
  * and keyboard navigation logic via the useSelectionList hook.
@@ -70,7 +184,7 @@ export function BaseSelectionList<
   selectedIndicator = '●',
   renderItem,
 }: BaseSelectionListProps<T, TItem>): React.JSX.Element {
-  const { activeIndex } = useSelectionList({
+  const { activeIndex, setActiveIndex } = useSelectionList({
     items,
     initialIndex,
     onSelect,
@@ -107,10 +221,12 @@ export function BaseSelectionList<
   );
   const numberColumnWidth = String(items.length).length;
 
+  const showArrows = showScrollArrows && items.length > maxItemsToShow;
+
   return (
     <Box flexDirection="column">
       {/* Use conditional coloring instead of conditional rendering */}
-      {showScrollArrows && items.length > maxItemsToShow && (
+      {showArrows && (
         <Text
           color={
             effectiveScrollOffset > 0
@@ -126,71 +242,24 @@ export function BaseSelectionList<
         const itemIndex = effectiveScrollOffset + index;
         const isSelected = activeIndex === itemIndex;
 
-        // Determine colors based on selection and disabled state
-        let titleColor = theme.text.primary;
-        let numberColor = theme.text.primary;
-
-        if (isSelected) {
-          titleColor = theme.ui.focus;
-          numberColor = theme.ui.focus;
-        } else if (item.disabled) {
-          titleColor = theme.text.secondary;
-          numberColor = theme.text.secondary;
-        }
-
-        if (!isFocused && !item.disabled) {
-          numberColor = theme.text.secondary;
-        }
-
-        if (!showNumbers) {
-          numberColor = theme.text.secondary;
-        }
-
-        const itemNumberText = `${String(itemIndex + 1).padStart(
-          numberColumnWidth,
-        )}.`;
-
         return (
-          <Box
+          <SelectionListItemRow
             key={item.key}
-            alignItems="flex-start"
-            backgroundColor={isSelected ? theme.background.focus : undefined}
-          >
-            {/* Radio button indicator */}
-            <Box minWidth={2} flexShrink={0}>
-              <Text
-                color={isSelected ? theme.ui.focus : theme.text.primary}
-                aria-hidden
-              >
-                {isSelected ? selectedIndicator : ' '}
-              </Text>
-            </Box>
-
-            {/* Item number */}
-            {showNumbers && !item.hideNumber && (
-              <Box
-                marginRight={1}
-                flexShrink={0}
-                minWidth={itemNumberText.length}
-                aria-state={{ checked: isSelected }}
-              >
-                <Text color={numberColor}>{itemNumberText}</Text>
-              </Box>
-            )}
-
-            {/* Custom content via render prop */}
-            <Box flexGrow={1}>
-              {renderItem(item, {
-                isSelected,
-                titleColor,
-                numberColor,
-              })}
-            </Box>
-          </Box>
+            item={item}
+            itemIndex={itemIndex}
+            isSelected={isSelected}
+            isFocused={isFocused}
+            showNumbers={showNumbers}
+            selectedIndicator={selectedIndicator}
+            numberColumnWidth={numberColumnWidth}
+            onSelect={onSelect}
+            setActiveIndex={setActiveIndex}
+            renderItem={renderItem}
+          />
         );
       })}
 
-      {showScrollArrows && items.length > maxItemsToShow && (
+      {showArrows && (
         <Text
           color={
             effectiveScrollOffset + maxItemsToShow < items.length

packages/cli/src/ui/components/shared/TextInput.test.tsx

@@ -11,12 +11,17 @@ import { act } from 'react';
 import { TextInput } from './TextInput.js';
 import { useKeypress } from '../../hooks/useKeypress.js';
 import { useTextBuffer, type TextBuffer } from './text-buffer.js';
+import { useMouseClick } from '../../hooks/useMouseClick.js';
 
 // Mocks
 vi.mock('../../hooks/useKeypress.js', () => ({
   useKeypress: vi.fn(),
 }));
 
+vi.mock('../../hooks/useMouseClick.js', () => ({
+  useMouseClick: vi.fn(),
+}));
+
 vi.mock('./text-buffer.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('./text-buffer.js')>();
   const mockTextBuffer = {
@@ -69,6 +74,7 @@ vi.mock('./text-buffer.js', async (importOriginal) => {
 
 const mockedUseKeypress = useKeypress as Mock;
 const mockedUseTextBuffer = useTextBuffer as Mock;
+const mockedUseMouseClick = useMouseClick as Mock;
 
 describe('TextInput', () => {
   const onCancel = vi.fn();
@@ -84,6 +90,7 @@ describe('TextInput', () => {
       cursor: [0, 0],
       visualCursor: [0, 0],
       viewportVisualLines: [''],
+      visualScrollRow: 0,
       pastedContent: {} as Record<string, string>,
       handleInput: vi.fn((key) => {
         if (key.sequence) {
@@ -408,4 +415,36 @@ describe('TextInput', () => {
     expect(lastFrame()).toContain('line2');
     unmount();
   });
+
+  it('registers mouse click handler for free-form text input', async () => {
+    const { unmount } = await render(
+      <TextInput buffer={mockBuffer} onSubmit={onSubmit} onCancel={onCancel} />,
+    );
+
+    expect(mockedUseMouseClick).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.any(Function),
+      expect.objectContaining({ isActive: true, name: 'left-press' }),
+    );
+    unmount();
+  });
+
+  it('registers mouse click handler for placeholder view', async () => {
+    mockBuffer.text = '';
+    const { unmount } = await render(
+      <TextInput
+        buffer={mockBuffer}
+        placeholder="test"
+        onSubmit={onSubmit}
+        onCancel={onCancel}
+      />,
+    );
+
+    expect(mockedUseMouseClick).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.any(Function),
+      expect.objectContaining({ isActive: true, name: 'left-press' }),
+    );
+    unmount();
+  });
 });

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

@@ -5,8 +5,8 @@
  */
 
 import type React from 'react';
-import { useCallback } from 'react';
-import { Text, Box } from 'ink';
+import { useCallback, useRef } from 'react';
+import { Text, Box, type DOMElement } from 'ink';
 import { useKeypress, type Key } from '../../hooks/useKeypress.js';
 import chalk from 'chalk';
 import { theme } from '../../semantic-colors.js';
@@ -14,6 +14,7 @@ import { expandPastePlaceholders, type TextBuffer } from './text-buffer.js';
 import { cpSlice, cpIndexToOffset } from '../../utils/textUtils.js';
 import { Command } from '../../key/keyMatchers.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
+import { useMouseClick } from '../../hooks/useMouseClick.js';
 
 export interface TextInputProps {
   buffer: TextBuffer;
@@ -31,6 +32,8 @@ export function TextInput({
   focus = true,
 }: TextInputProps): React.JSX.Element {
   const keyMatchers = useKeyMatchers();
+  const containerRef = useRef<DOMElement>(null);
+
   const {
     text,
     handleInput,
@@ -40,6 +43,17 @@ export function TextInput({
   } = buffer;
   const [cursorVisualRowAbsolute, cursorVisualColAbsolute] = visualCursor;
 
+  useMouseClick(
+    containerRef,
+    (_event, relativeX, relativeY) => {
+      if (focus) {
+        const visRowAbsolute = visualScrollRow + relativeY;
+        buffer.moveToVisualPosition(visRowAbsolute, relativeX);
+      }
+    },
+    { isActive: focus, name: 'left-press' },
+  );
+
   const handleKeyPress = useCallback(
     (key: Key) => {
       if (key.name === 'escape' && onCancel) {
@@ -64,7 +78,7 @@ export function TextInput({
 
   if (showPlaceholder) {
     return (
-      <Box>
+      <Box ref={containerRef}>
         {focus ? (
           <Text terminalCursorFocus={focus} terminalCursorPosition={0}>
             {chalk.inverse(placeholder[0] || ' ')}
@@ -78,7 +92,7 @@ export function TextInput({
   }
 
   return (
-    <Box flexDirection="column">
+    <Box ref={containerRef} flexDirection="column">
       {viewportVisualLines.map((lineText, idx) => {
         const currentVisualRow = visualScrollRow + idx;
         const isCursorLine =

packages/cli/src/ui/hooks/slashCommandProcessor.test.tsx

@@ -858,11 +858,81 @@ describe('useSlashCommandProcessor', () => {
   });
 
   describe('Lifecycle', () => {
+    it('removes the IDE status listener on unmount after async initialization', async () => {
+      let resolveIdeClient:
+        | ((client: {
+            addStatusChangeListener: (listener: () => void) => void;
+            removeStatusChangeListener: (listener: () => void) => void;
+          }) => void)
+        | undefined;
+      const addStatusChangeListener = vi.fn();
+      const removeStatusChangeListener = vi.fn();
+
+      mockIdeClientGetInstance.mockImplementation(
+        () =>
+          new Promise((resolve) => {
+            resolveIdeClient = resolve;
+          }),
+      );
+
+      const result = await setupProcessorHook();
+
+      await act(async () => {
+        resolveIdeClient?.({
+          addStatusChangeListener,
+          removeStatusChangeListener,
+        });
+      });
+
+      result.unmount();
+      unmountHook = undefined;
+
+      expect(addStatusChangeListener).toHaveBeenCalledTimes(1);
+      expect(removeStatusChangeListener).toHaveBeenCalledTimes(1);
+      expect(removeStatusChangeListener).toHaveBeenCalledWith(
+        addStatusChangeListener.mock.calls[0]?.[0],
+      );
+    });
+
+    it('does not register an IDE status listener if unmounted before async initialization resolves', async () => {
+      let resolveIdeClient:
+        | ((client: {
+            addStatusChangeListener: (listener: () => void) => void;
+            removeStatusChangeListener: (listener: () => void) => void;
+          }) => void)
+        | undefined;
+      const addStatusChangeListener = vi.fn();
+      const removeStatusChangeListener = vi.fn();
+
+      mockIdeClientGetInstance.mockImplementation(
+        () =>
+          new Promise((resolve) => {
+            resolveIdeClient = resolve;
+          }),
+      );
+
+      const result = await setupProcessorHook();
+
+      result.unmount();
+      unmountHook = undefined;
+
+      await act(async () => {
+        resolveIdeClient?.({
+          addStatusChangeListener,
+          removeStatusChangeListener,
+        });
+      });
+
+      expect(addStatusChangeListener).not.toHaveBeenCalled();
+      expect(removeStatusChangeListener).not.toHaveBeenCalled();
+    });
+
     it('should abort command loading when the hook unmounts', async () => {
       const abortSpy = vi.spyOn(AbortController.prototype, 'abort');
       const { unmount } = await setupProcessorHook();
 
       unmount();
+      unmountHook = undefined;
 
       expect(abortSpy).toHaveBeenCalledTimes(1);
     });

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

@@ -281,10 +281,16 @@ export const useSlashCommandProcessor = (
     const listener = () => {
       reloadCommands();
     };
+    let isActive = true;
+    let activeIdeClient: IdeClient | undefined;
 
     // eslint-disable-next-line @typescript-eslint/no-floating-promises
     (async () => {
       const ideClient = await IdeClient.getInstance();
+      if (!isActive) {
+        return;
+      }
+      activeIdeClient = ideClient;
       ideClient.addStatusChangeListener(listener);
     })();
 
@@ -307,11 +313,8 @@ export const useSlashCommandProcessor = (
     coreEvents.on('extensionsStopping', extensionEventListener);
 
     return () => {
-      // eslint-disable-next-line @typescript-eslint/no-floating-promises
-      (async () => {
-        const ideClient = await IdeClient.getInstance();
-        ideClient.removeStatusChangeListener(listener);
-      })();
+      isActive = false;
+      activeIdeClient?.removeStatusChangeListener(listener);
       removeMCPStatusChangeListener(listener);
       coreEvents.off('extensionsStarting', extensionEventListener);
       coreEvents.off('extensionsStopping', extensionEventListener);

packages/cli/src/ui/hooks/useExecutionLifecycle.test.tsx

@@ -76,7 +76,23 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
     isBinary: mockIsBinary,
   };
 });
-vi.mock('node:fs');
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  const mocked = {
+    ...actual,
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+    createWriteStream: vi.fn(),
+    promises: {
+      ...actual.promises,
+      unlink: vi.fn().mockResolvedValue(undefined),
+    },
+  };
+  return {
+    ...mocked,
+    default: mocked,
+  };
+});
 vi.mock('node:os', async (importOriginal) => {
   const actual = await importOriginal<typeof import('node:os')>();
   const mocked = {
@@ -144,6 +160,10 @@ describe('useExecutionLifecycle', () => {
           enableEnvironmentVariableRedaction: false,
         },
       }),
+      getTruncateToolOutputThreshold: () => 40000,
+      storage: {
+        getProjectTempDir: () => '/tmp/project',
+      },
     } as unknown as Config;
     mockGeminiClient = { addHistory: vi.fn() } as unknown as GeminiClient;
 
@@ -155,6 +175,16 @@ describe('useExecutionLifecycle', () => {
     mockIsBinary.mockReturnValue(false);
     vi.mocked(fs.existsSync).mockReturnValue(false);
 
+    vi.mocked(fs.createWriteStream).mockReturnValue({
+      write: vi.fn(),
+      end: vi.fn().mockImplementation((cb: () => void) => {
+        if (cb) cb();
+      }),
+      destroy: vi.fn(),
+      bytesWritten: 0,
+      closed: false,
+    } as unknown as fs.WriteStream);
+
     mockShellExecutionService.mockImplementation((_cmd, _cwd, callback) => {
       mockShellOutputCallback = callback;
       return Promise.resolve({
@@ -646,7 +676,7 @@ describe('useExecutionLifecycle', () => {
     });
     const tmpFile = path.join(os.tmpdir(), 'shell_pwd_abcdef.tmp');
     // Verify that the temporary file was cleaned up
-    expect(vi.mocked(fs.unlinkSync)).toHaveBeenCalledWith(tmpFile);
+    expect(vi.mocked(fs.promises.unlink)).toHaveBeenCalledWith(tmpFile);
     expect(setShellInputFocusedMock).toHaveBeenCalledWith(false);
   });
 
@@ -674,7 +704,7 @@ describe('useExecutionLifecycle', () => {
       expect(finalHistoryItem.tools[0].resultDisplay).toContain(
         "WARNING: shell mode is stateless; the directory change to '/test/dir/new' will not persist.",
       );
-      expect(vi.mocked(fs.unlinkSync)).toHaveBeenCalledWith(tmpFile);
+      expect(vi.mocked(fs.promises.unlink)).toHaveBeenCalledWith(tmpFile);
     });
 
     it('should NOT show a warning if the directory does not change', async () => {

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

@@ -20,6 +20,8 @@ import {
   ShellExecutionService,
   ExecutionLifecycleService,
   CoreToolCallStatus,
+  moveToolOutputToFile,
+  debugLogger,
 } from '@google/gemini-cli-core';
 import { type PartListUnion } from '@google/genai';
 import type { UseHistoryManagerReturn } from './useHistoryManager.js';
@@ -39,16 +41,15 @@ export { type BackgroundTask };
 
 export const OUTPUT_UPDATE_INTERVAL_MS = 1000;
 const RESTORE_VISIBILITY_DELAY_MS = 300;
-const MAX_OUTPUT_LENGTH = 10000;
-
 function addShellCommandToGeminiHistory(
   geminiClient: GeminiClient,
   rawQuery: string,
   resultText: string,
+  maxOutputLength: number,
 ) {
   const modelContent =
-    resultText.length > MAX_OUTPUT_LENGTH
-      ? resultText.substring(0, MAX_OUTPUT_LENGTH) + '\n... (truncated)'
+    maxOutputLength > 0 && resultText.length > maxOutputLength
+      ? resultText.substring(0, maxOutputLength) + '\n... (truncated)'
       : resultText;
 
   // Escape backticks to prevent prompt injection breakouts
@@ -424,6 +425,9 @@ export const useExecutionLifecycle = (
                 let shouldUpdate = false;
 
                 switch (event.type) {
+                  case 'raw_data':
+                  case 'file_data':
+                    break;
                   case 'data':
                     if (isBinaryStream) break;
                     if (typeof event.chunk === 'string') {
@@ -533,6 +537,24 @@ export const useExecutionLifecycle = (
           } else {
             mainContent =
               result.output.trim() || '(Command produced no output)';
+            if (result.fullOutputFilePath) {
+              const { outputFile: savedPath } = await moveToolOutputToFile(
+                result.fullOutputFilePath,
+                SHELL_COMMAND_NAME,
+                callId,
+                config.storage.getProjectTempDir(),
+                config.getSessionId(),
+              );
+              const warning = `[Full command output saved to: ${savedPath}]`;
+              mainContent = mainContent.includes(
+                '[GEMINI_CLI_WARNING: Output truncated.',
+              )
+                ? mainContent.replace(
+                    /\[GEMINI_CLI_WARNING: Output truncated\..*?\]/,
+                    warning,
+                  )
+                : `${mainContent}\n\n${warning}`;
+            }
           }
 
           let finalOutput: string | AnsiOutput =
@@ -617,7 +639,12 @@ export const useExecutionLifecycle = (
             );
           }
 
-          addShellCommandToGeminiHistory(geminiClient, rawQuery, mainContent);
+          addShellCommandToGeminiHistory(
+            geminiClient,
+            rawQuery,
+            mainContent,
+            config.getTruncateToolOutputThreshold(),
+          );
         } catch (err) {
           setPendingHistoryItem(null);
           const errorMessage = err instanceof Error ? err.message : String(err);
@@ -630,8 +657,13 @@ export const useExecutionLifecycle = (
           );
         } finally {
           abortSignal.removeEventListener('abort', abortHandler);
-          if (pwdFilePath && fs.existsSync(pwdFilePath)) {
-            fs.unlinkSync(pwdFilePath);
+          if (pwdFilePath) {
+            fs.promises.unlink(pwdFilePath).catch((err) => {
+              debugLogger.warn(
+                `Failed to cleanup pwd file: ${pwdFilePath}`,
+                err,
+              );
+            });
           }
 
           dispatch({ type: 'SET_ACTIVE_PTY', pid: null });

packages/cli/src/ui/themes/builtin/dark/github-dark-colorblind.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type ColorsTheme, Theme } from '../../theme.js';
+import { interpolateColor } from '../../color-utils.js';
+
+const githubDarkColorblindColors: ColorsTheme = {
+  type: 'dark',
+  Background: '#0d1117',
+  Foreground: '#e6edf3',
+  LightBlue: '#a5d6ff',
+  AccentBlue: '#79c0ff',
+  AccentPurple: '#d2a8ff',
+  AccentCyan: '#a5d6ff',
+  AccentGreen: '#a5d6ff',
+  AccentYellow: '#d29922',
+  AccentRed: '#f0883e',
+  DiffAdded: '#0d161f',
+  DiffRemoved: '#1d150e',
+  Comment: '#7d8590',
+  Gray: '#7d8590',
+  DarkGray: interpolateColor('#7d8590', '#0d1117', 0.5),
+  GradientColors: ['#58a6ff', '#f0883e'],
+};
+
+export const GitHubDarkColorblind: Theme = new Theme(
+  'GitHub Dark Colorblind',
+  'dark',
+  {
+    hljs: {
+      display: 'block',
+      overflowX: 'auto',
+      padding: '0.5em',
+      color: githubDarkColorblindColors.Foreground,
+      background: githubDarkColorblindColors.Background,
+    },
+    'hljs-comment': {
+      color: githubDarkColorblindColors.Comment,
+      fontStyle: 'italic',
+    },
+    'hljs-quote': {
+      color: githubDarkColorblindColors.Comment,
+      fontStyle: 'italic',
+    },
+    'hljs-keyword': {
+      color: githubDarkColorblindColors.AccentRed,
+      fontWeight: 'bold',
+    },
+    'hljs-selector-tag': {
+      color: githubDarkColorblindColors.AccentRed,
+      fontWeight: 'bold',
+    },
+    'hljs-subst': {
+      color: githubDarkColorblindColors.Foreground,
+    },
+    'hljs-number': {
+      color: githubDarkColorblindColors.LightBlue,
+    },
+    'hljs-literal': {
+      color: githubDarkColorblindColors.LightBlue,
+    },
+    'hljs-variable': {
+      color: githubDarkColorblindColors.Foreground,
+    },
+    'hljs-template-variable': {
+      color: githubDarkColorblindColors.Foreground,
+    },
+    'hljs-tag .hljs-attr': {
+      color: githubDarkColorblindColors.AccentYellow,
+    },
+    'hljs-string': {
+      color: githubDarkColorblindColors.AccentCyan,
+    },
+    'hljs-doctag': {
+      color: githubDarkColorblindColors.AccentCyan,
+    },
+    'hljs-title': {
+      color: githubDarkColorblindColors.AccentPurple,
+      fontWeight: 'bold',
+    },
+    'hljs-section': {
+      color: githubDarkColorblindColors.AccentPurple,
+      fontWeight: 'bold',
+    },
+    'hljs-selector-id': {
+      color: githubDarkColorblindColors.AccentPurple,
+      fontWeight: 'bold',
+    },
+    'hljs-type': {
+      color: githubDarkColorblindColors.AccentGreen,
+      fontWeight: 'bold',
+    },
+    'hljs-class .hljs-title': {
+      color: githubDarkColorblindColors.AccentGreen,
+      fontWeight: 'bold',
+    },
+    'hljs-tag': {
+      color: githubDarkColorblindColors.AccentGreen,
+    },
+    'hljs-name': {
+      color: githubDarkColorblindColors.AccentGreen,
+    },
+    'hljs-attribute': {
+      color: githubDarkColorblindColors.LightBlue,
+    },
+    'hljs-regexp': {
+      color: githubDarkColorblindColors.AccentCyan,
+    },
+    'hljs-link': {
+      color: githubDarkColorblindColors.AccentCyan,
+    },
+    'hljs-symbol': {
+      color: githubDarkColorblindColors.AccentPurple,
+    },
+    'hljs-bullet': {
+      color: githubDarkColorblindColors.AccentPurple,
+    },
+    'hljs-built_in': {
+      color: githubDarkColorblindColors.LightBlue,
+    },
+    'hljs-builtin-name': {
+      color: githubDarkColorblindColors.LightBlue,
+    },
+    'hljs-meta': {
+      color: githubDarkColorblindColors.LightBlue,
+      fontWeight: 'bold',
+    },
+    'hljs-deletion': {
+      background: '#682d0f',
+      color: githubDarkColorblindColors.AccentRed,
+    },
+    'hljs-addition': {
+      background: '#0c2d6b',
+      color: githubDarkColorblindColors.AccentGreen,
+    },
+    'hljs-emphasis': {
+      fontStyle: 'italic',
+    },
+    'hljs-strong': {
+      fontWeight: 'bold',
+    },
+  },
+  githubDarkColorblindColors,
+);

packages/cli/src/ui/themes/builtin/light/github-light-colorblind.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type ColorsTheme, Theme } from '../../theme.js';
+import { interpolateColor } from '../../color-utils.js';
+
+const githubLightColorblindColors: ColorsTheme = {
+  type: 'light',
+  Background: '#ffffff',
+  Foreground: '#1f2328',
+  LightBlue: '#0a3069',
+  AccentBlue: '#0550ae',
+  AccentPurple: '#8250df',
+  AccentCyan: '#0a3069',
+  AccentGreen: '#0969da',
+  AccentYellow: '#9a6700',
+  AccentRed: '#bc4c00',
+  DiffAdded: '#ddf4ff',
+  DiffRemoved: '#fff1e5',
+  Comment: '#656d76',
+  Gray: '#656d76',
+  DarkGray: interpolateColor('#656d76', '#ffffff', 0.5),
+  GradientColors: ['#0969da', '#bc4c00'],
+};
+
+export const GitHubLightColorblind: Theme = new Theme(
+  'GitHub Light Colorblind',
+  'light',
+  {
+    hljs: {
+      display: 'block',
+      overflowX: 'auto',
+      padding: '0.5em',
+      color: githubLightColorblindColors.Foreground,
+      background: githubLightColorblindColors.Background,
+    },
+    'hljs-comment': {
+      color: githubLightColorblindColors.Comment,
+      fontStyle: 'italic',
+    },
+    'hljs-quote': {
+      color: githubLightColorblindColors.Comment,
+      fontStyle: 'italic',
+    },
+    'hljs-keyword': {
+      color: githubLightColorblindColors.AccentRed,
+      fontWeight: 'bold',
+    },
+    'hljs-selector-tag': {
+      color: githubLightColorblindColors.AccentRed,
+      fontWeight: 'bold',
+    },
+    'hljs-subst': {
+      color: githubLightColorblindColors.Foreground,
+    },
+    'hljs-number': {
+      color: githubLightColorblindColors.LightBlue,
+    },
+    'hljs-literal': {
+      color: githubLightColorblindColors.LightBlue,
+    },
+    'hljs-variable': {
+      color: githubLightColorblindColors.Foreground,
+    },
+    'hljs-template-variable': {
+      color: githubLightColorblindColors.Foreground,
+    },
+    'hljs-tag .hljs-attr': {
+      color: githubLightColorblindColors.AccentYellow,
+    },
+    'hljs-string': {
+      color: githubLightColorblindColors.AccentCyan,
+    },
+    'hljs-doctag': {
+      color: githubLightColorblindColors.AccentCyan,
+    },
+    'hljs-title': {
+      color: githubLightColorblindColors.AccentPurple,
+      fontWeight: 'bold',
+    },
+    'hljs-section': {
+      color: githubLightColorblindColors.AccentPurple,
+      fontWeight: 'bold',
+    },
+    'hljs-selector-id': {
+      color: githubLightColorblindColors.AccentPurple,
+      fontWeight: 'bold',
+    },
+    'hljs-type': {
+      color: githubLightColorblindColors.AccentGreen,
+      fontWeight: 'bold',
+    },
+    'hljs-class .hljs-title': {
+      color: githubLightColorblindColors.AccentGreen,
+      fontWeight: 'bold',
+    },
+    'hljs-tag': {
+      color: githubLightColorblindColors.AccentGreen,
+    },
+    'hljs-name': {
+      color: githubLightColorblindColors.AccentGreen,
+    },
+    'hljs-attribute': {
+      color: githubLightColorblindColors.LightBlue,
+    },
+    'hljs-regexp': {
+      color: githubLightColorblindColors.AccentCyan,
+    },
+    'hljs-link': {
+      color: githubLightColorblindColors.AccentCyan,
+    },
+    'hljs-symbol': {
+      color: githubLightColorblindColors.AccentPurple,
+    },
+    'hljs-bullet': {
+      color: githubLightColorblindColors.AccentPurple,
+    },
+    'hljs-built_in': {
+      color: githubLightColorblindColors.LightBlue,
+    },
+    'hljs-builtin-name': {
+      color: githubLightColorblindColors.LightBlue,
+    },
+    'hljs-meta': {
+      color: githubLightColorblindColors.LightBlue,
+      fontWeight: 'bold',
+    },
+    'hljs-deletion': {
+      background: '#fff1e5',
+      color: githubLightColorblindColors.AccentRed,
+    },
+    'hljs-addition': {
+      background: '#ddf4ff',
+      color: githubLightColorblindColors.AccentGreen,
+    },
+    'hljs-emphasis': {
+      fontStyle: 'italic',
+    },
+    'hljs-strong': {
+      fontWeight: 'bold',
+    },
+  },
+  githubLightColorblindColors,
+);

packages/cli/src/ui/themes/theme-manager.ts

@@ -10,6 +10,8 @@ import { AtomOneDark } from './builtin/dark/atom-one-dark.js';
 import { Dracula } from './builtin/dark/dracula-dark.js';
 import { GitHubDark } from './builtin/dark/github-dark.js';
 import { GitHubLight } from './builtin/light/github-light.js';
+import { GitHubDarkColorblind } from './builtin/dark/github-dark-colorblind.js';
+import { GitHubLightColorblind } from './builtin/light/github-light-colorblind.js';
 import { GoogleCode } from './builtin/light/googlecode-light.js';
 import { Holiday } from './builtin/dark/holiday-dark.js';
 import { DefaultLight } from './builtin/light/default-light.js';
@@ -79,6 +81,8 @@ class ThemeManager {
       DefaultDark,
       GitHubDark,
       GitHubLight,
+      GitHubDarkColorblind,
+      GitHubLightColorblind,
       GoogleCode,
       Holiday,
       ShadesOfPurple,

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/gemini-cli-core",
-  "version": "0.39.0-nightly.20260408.e77b22e63",
+  "version": "0.40.0-nightly.20260414.g5b1f7375a",
   "description": "Gemini CLI Core",
   "license": "Apache-2.0",
   "repository": {
@@ -20,7 +20,8 @@
     "typecheck": "tsc --noEmit"
   },
   "files": [
-    "dist"
+    "dist",
+    "vendor"
   ],
   "dependencies": {
     "@a2a-js/sdk": "0.3.11",
@@ -31,7 +32,6 @@
     "@google/genai": "1.30.0",
     "@grpc/grpc-js": "^1.14.3",
     "@iarna/toml": "^2.2.5",
-    "@joshua.litt/get-ripgrep": "^0.0.3",
     "@modelcontextprotocol/sdk": "^1.23.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.211.0",
@@ -59,6 +59,7 @@
     "diff": "^8.0.3",
     "dotenv": "^17.2.4",
     "dotenv-expand": "^12.0.3",
+    "execa": "^9.6.1",
     "fast-levenshtein": "^2.0.6",
     "fdir": "^6.4.6",
     "fzf": "^0.5.2",

packages/core/src/agents/skill-extraction-agent.test.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { SkillExtractionAgent } from './skill-extraction-agent.js';
+import {
+  EDIT_TOOL_NAME,
+  GLOB_TOOL_NAME,
+  GREP_TOOL_NAME,
+  LS_TOOL_NAME,
+  READ_FILE_TOOL_NAME,
+  WRITE_FILE_TOOL_NAME,
+} from '../tools/tool-names.js';
+import { PREVIEW_GEMINI_FLASH_MODEL } from '../config/models.js';
+
+describe('SkillExtractionAgent', () => {
+  const skillsDir = '/tmp/skills';
+  const sessionIndex =
+    '[NEW] Debug login flow (12 user msgs) — /tmp/chats/session-1.json';
+  const existingSkillsSummary =
+    '## Workspace Skills (.gemini/skills — do NOT duplicate)\n- **existing-skill**: Existing description';
+
+  const agent = SkillExtractionAgent(
+    skillsDir,
+    sessionIndex,
+    existingSkillsSummary,
+  );
+
+  it('should expose expected metadata, model, and tools', () => {
+    expect(agent.kind).toBe('local');
+    expect(agent.name).toBe('confucius');
+    expect(agent.displayName).toBe('Skill Extractor');
+    expect(agent.modelConfig.model).toBe(PREVIEW_GEMINI_FLASH_MODEL);
+    expect(agent.toolConfig?.tools).toEqual(
+      expect.arrayContaining([
+        READ_FILE_TOOL_NAME,
+        WRITE_FILE_TOOL_NAME,
+        EDIT_TOOL_NAME,
+        LS_TOOL_NAME,
+        GLOB_TOOL_NAME,
+        GREP_TOOL_NAME,
+      ]),
+    );
+  });
+
+  it('should default to no skill unless recurrence and durability are proven', () => {
+    const prompt = agent.promptConfig.systemPrompt;
+
+    expect(prompt).toContain('Default to NO SKILL.');
+    expect(prompt).toContain(
+      'strong evidence this will recur for future agents in this repo/workflow',
+    );
+    expect(prompt).toContain('broader than a single incident');
+    expect(prompt).toContain('A skill MUST meet ALL of these criteria:');
+    expect(prompt).toContain(
+      'Future agents in this repo/workflow are likely to need it',
+    );
+  });
+
+  it('should explicitly reject one-off incidents and single-session preferences', () => {
+    const prompt = agent.promptConfig.systemPrompt;
+
+    expect(prompt).toContain('Single-session preferences');
+    expect(prompt).toContain('One-off incidents');
+    expect(prompt).toContain('Output-style preferences');
+    expect(prompt).toContain('cannot survive renaming the specific');
+  });
+
+  it('should warn that session summaries are user-intent summaries, not workflow evidence', () => {
+    const query = agent.promptConfig.query ?? '';
+
+    expect(query).toContain(existingSkillsSummary);
+    expect(query).toContain(sessionIndex);
+    expect(query).toContain(
+      'The summary is a user-intent summary, not a workflow summary.',
+    );
+    expect(query).toContain(
+      'The session summaries describe user intent, not workflow details.',
+    );
+    expect(query).toContain(
+      'Only write a skill if the evidence shows a durable, recurring workflow',
+    );
+    expect(query).toContain(
+      'If recurrence or future reuse is unclear, create no skill and explain why.',
+    );
+  });
+});

packages/core/src/agents/skill-extraction-agent.ts

@@ -7,11 +7,13 @@
 import { z } from 'zod';
 import type { LocalAgentDefinition } from './types.js';
 import {
+  ACTIVATE_SKILL_TOOL_NAME,
   EDIT_TOOL_NAME,
   GLOB_TOOL_NAME,
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
+  SHELL_TOOL_NAME,
   WRITE_FILE_TOOL_NAME,
 } from '../tools/tool-names.js';
 import { PREVIEW_GEMINI_FLASH_MODEL } from '../config/models.js';
@@ -36,7 +38,7 @@ function buildSystemPrompt(skillsDir: string): string {
     '- solve similar tasks with fewer tool calls and fewer reasoning tokens',
     '- reuse proven workflows and verification checklists',
     '- avoid known failure modes and landmines',
-    '- anticipate user preferences without being reminded',
+    '- capture durable workflow constraints that future agents are likely to encounter again',
     '',
     '============================================================',
     'SAFETY AND HYGIENE (STRICT)',
@@ -59,6 +61,10 @@ function buildSystemPrompt(skillsDir: string): string {
     '1. "Is this something a competent agent would NOT already know?" If no, STOP.',
     '2. "Does an existing skill (listed below) already cover this?" If yes, STOP.',
     '3. "Can I write a concrete, step-by-step procedure?" If no, STOP.',
+    '4. "Is there strong evidence this will recur for future agents in this repo/workflow?" If no, STOP.',
+    '5. "Is this broader than a single incident (one bug, one ticket, one branch, one date, one exact error)?" If no, STOP.',
+    '',
+    'Default to NO SKILL.',
     '',
     'Do NOT create skills for:',
     '',
@@ -67,6 +73,10 @@ function buildSystemPrompt(skillsDir: string): string {
     '- **Pure Q&A**: The user asked "how does X work?" and got an answer. No procedure.',
     '- **Brainstorming/design**: Discussion of how to build something, without a validated',
     '  implementation that produced a reusable procedure.',
+    '- **Single-session preferences**: User-specific style/output preferences or workflow',
+    '  preferences mentioned only once.',
+    '- **One-off incidents**: Debugging or incident response tied to a single bug, ticket,',
+    '  branch, date, or exact error string.',
     '- **Anything already covered by an existing skill** (global, workspace, builtin, or',
     '  previously extracted). Check the "Existing Skills" section carefully.',
     '',
@@ -74,31 +84,40 @@ function buildSystemPrompt(skillsDir: string): string {
     'WHAT COUNTS AS A SKILL',
     '============================================================',
     '',
-    'A skill MUST meet BOTH of these criteria:',
+    'A skill MUST meet ALL of these criteria:',
     '',
     '1. **Procedural and concrete**: It can be expressed as numbered steps with specific',
     '   commands, paths, or code patterns. If you can only write vague guidance, it is NOT',
     '   a skill. "Be careful with X" is advice, not a skill.',
     '',
-    '2. **Non-obvious and project-specific**: A competent agent would NOT already know this.',
-    '   It encodes project-specific knowledge, non-obvious ordering constraints, or',
-    '   hard-won failure shields that cannot be inferred from the codebase alone.',
+    '2. **Durable and reusable**: Future agents in this repo/workflow are likely to need it',
+    '   again. If it only solved one incident, it is NOT a skill.',
     '',
-    'Confidence tiers (prefer higher tiers):',
+    '3. **Evidence-backed and project-specific**: It encodes project-specific knowledge,',
+    '   repeated operational constraints, or hard-won failure shields supported by session',
+    '   evidence. Do not assume something is non-obvious just because it sounds detailed.',
     '',
-    '**High confidence** — create the skill:',
-    '- The same workflow appeared in multiple sessions (cross-session repetition)',
-    '- A multi-step procedure was validated (tests passed, user confirmed success)',
+    'Confidence tiers:',
     '',
-    '**Medium confidence** — create the skill if it is clearly project-specific:',
-    '- A project-specific build/test/deploy/release procedure was established',
-    '- A non-obvious ordering constraint or prerequisite was discovered',
-    '- A failure mode was hit and a concrete fix was found and verified',
+    '**High confidence** — create the skill only when recurrence/durability is clear:',
+    '- The same workflow appeared in multiple sessions (cross-session repetition), OR it is',
+    '  a stable recurring repo workflow (for example setup/build/test/deploy/release) with a',
+    '  clear future trigger',
+    '- The workflow was validated (tests passed, user confirmed success, or the same fix',
+    '  worked repeatedly)',
+    '- The skill can be named without referencing a specific incident, bug, branch, or date',
+    '',
+    '**Medium confidence** — usually do NOT create the skill yet:',
+    '- A project-specific procedure appeared once and seems useful, but recurrence is not yet',
+    '  clear',
+    '- A verified fix exists, but it is still tied to one incident',
+    '- A user correction changed the approach once, but durability is uncertain',
     '',
     '**Low confidence** — do NOT create the skill:',
     '- A one-off debugging session with no reusable procedure',
     '- Generic workflows any agent could figure out from the codebase',
     '- A code review or investigation with no durable takeaway',
+    '- Output-style preferences that do not materially change procedure',
     '',
     'Aim for 0-2 skills per run. Quality over quantity.',
     '',
@@ -117,8 +136,10 @@ function buildSystemPrompt(skillsDir: string): string {
     '',
     'What to look for:',
     '',
-    '- User corrections: "No, do it this way" -> preference signal',
+    '- User corrections that change procedure in a durable way, especially when repeated',
+    '  across sessions',
     '- Repeated patterns across sessions: same commands, same file paths, same workflow',
+    '- Stable recurring repo lifecycle workflows with clear future triggers',
     '- Failed attempts followed by successful ones -> failure shield',
     '- Multi-step procedures that were validated (tests passed, user confirmed)',
     '- User interruptions: "Stop, you need to X first" -> ordering constraint',
@@ -129,45 +150,8 @@ function buildSystemPrompt(skillsDir: string): string {
     '- Tool outputs that are just data (file contents, search results)',
     '- Speculative plans that were never executed',
     "- Temporary context (current branch name, today's date, specific error IDs)",
-    '',
-    '============================================================',
-    'SKILL FORMAT',
-    '============================================================',
-    '',
-    'Each skill is a directory containing a SKILL.md file with YAML frontmatter',
-    'and optional supporting scripts.',
-    '',
-    'Directory structure:',
-    `  ${skillsDir}/<skill-name>/`,
-    '    SKILL.md            # Required entrypoint',
-    '    scripts/<tool>.*    # Optional helper scripts (Python stdlib-only or shell)',
-    '',
-    'SKILL.md structure:',
-    '',
-    '  ---',
-    '  name: <skill-name>',
-    '  description: <1-2 lines; include concrete triggers in user-like language>',
-    '  ---',
-    '',
-    '  ## When to Use',
-    '  <Clear trigger conditions and non-goals>',
-    '',
-    '  ## Procedure',
-    '  <Numbered steps with specific commands, paths, code patterns>',
-    '',
-    '  ## Pitfalls and Fixes',
-    '  <symptom -> likely cause -> fix; only include observed failures>',
-    '',
-    '  ## Verification',
-    '  <Concrete success checks>',
-    '',
-    'Supporting scripts (optional but recommended when applicable):',
-    '- Put helper scripts in scripts/ and reference them from SKILL.md',
-    '- Prefer Python (stdlib only) or small shell scripts',
-    '- Make scripts safe: no destructive actions, no secrets, deterministic output',
-    '- Include a usage example in SKILL.md',
-    '',
-    'Naming: kebab-case (e.g., fix-lint-errors, run-migrations).',
+    '- Similar session summaries without matching workflow evidence',
+    '- One-off artifact names: bug IDs, branch names, timestamps, exact incident strings',
     '',
     '============================================================',
     'UPDATING EXISTING SKILLS (PATCHES)',
@@ -214,7 +198,10 @@ function buildSystemPrompt(skillsDir: string): string {
     '- Keep scopes distinct. Avoid overlapping "do-everything" skills.',
     '- Every skill MUST have: triggers, procedure, at least one pitfall or verification step.',
     '- If you cannot write a reliable procedure (too many unknowns), do NOT create the skill.',
-    '- Do not create skills for generic advice that any competent agent would already know.',
+    '- If the candidate is tied to one incident or cannot survive renaming the specific',
+    '  bug/ticket, do NOT create it.',
+    '- Do not create skills for generic advice, output-style preferences, or ephemeral',
+    '  choices that any competent agent would already know or adapt to on the fly.',
     '- Prefer fewer, higher-quality skills. 0-2 skills per run is typical. 3+ is unusual.',
     '',
     '============================================================',
@@ -223,18 +210,32 @@ function buildSystemPrompt(skillsDir: string): string {
     '',
     `1. Use list_directory on ${skillsDir} to see existing skills.`,
     '2. If skills exist, read their SKILL.md files to understand what is already captured.',
-    '3. Scan the session index provided in the query. Look for [NEW] sessions whose summaries',
-    '   suggest workflows that ALSO appear in other sessions (either [NEW] or [old]).',
-    '4. Apply the minimum signal gate. If no repeated patterns are visible, report that and finish.',
-    '5. For promising patterns, use read_file on the session file paths to inspect the full',
-    '   conversation. Confirm the workflow was actually repeated and validated.',
-    '6. For each confirmed skill, verify it meets ALL criteria (repeatable, procedural, high-leverage).',
-    '7. Write new SKILL.md files or update existing ones in your directory using write_file.',
+    '3. Use activate_skill to load the "skill-creator" skill. Follow its design guidance',
+    '   (conciseness, progressive disclosure, frontmatter format, bundled resources) when',
+    '   writing SKILL.md files. You may also use its init_skill.cjs script to scaffold new',
+    '   skill directories and package_skill.cjs to validate finished skills.',
+    '   IMPORTANT: You are a background agent with no user interaction. Skip any interactive',
+    '   steps in the skill-creator guide (asking clarifying questions, requesting user feedback,',
+    '   installation prompts, iteration loops). Use only its format and quality guidance.',
+    '4. Scan the session index provided in the query. Look for [NEW] sessions whose summaries',
+    '   hint at workflows that ALSO appear in other sessions (either [NEW] or [old]) or at a',
+    '   stable recurring repo workflow. Remember: summary similarity alone is NOT enough.',
+    '5. Apply the minimum signal gate. If recurrence or durability is not visible, report that',
+    '   no skill should be created and finish.',
+    '6. For promising patterns, use read_file on the session file paths to inspect the full',
+    '   conversation. Confirm the workflow was actually repeated and validated. Read at least',
+    '   two sessions unless the candidate is clearly a stable recurring repo lifecycle workflow.',
+    '7. For each candidate, verify it meets ALL criteria. Before writing, make sure you can',
+    '   state: future trigger, evidence sessions, recurrence signal, validation signal, and',
+    '   why it is not generic.',
+    '8. Write new SKILL.md files or update existing ones in your directory.',
+    '   Use run_shell_command to run init_skill.cjs for scaffolding and package_skill.cjs for validation.',
     '   For skills that live OUTSIDE your directory, write a .patch file instead (see UPDATING EXISTING SKILLS).',
-    '8. Write COMPLETE files — never partially update a SKILL.md.',
+    '9. Write COMPLETE files — never partially update a SKILL.md.',
     '',
     'IMPORTANT: Do NOT read every session. Only read sessions whose summaries suggest a',
-    'repeated pattern worth investigating. Most runs should read 0-3 sessions and create 0 skills.',
+    'repeated pattern or a stable recurring repo workflow worth investigating. Most runs',
+    'should read 0-3 sessions and create 0 skills.',
     'Do not explore the codebase. Work only with the session index, session files, and the skills directory.',
   ].join('\n');
 }
@@ -244,8 +245,9 @@ function buildSystemPrompt(skillsDir: string): string {
  * writes reusable SKILL.md files to the project memory directory.
  *
  * This agent is designed to run in the background on session startup.
- * It has restricted tool access (file tools only, no shell or user interaction)
- * and is prompted to only operate within the skills memory directory.
+ * It has restricted tool access (file tools, shell, and skill activation — no
+ * user interaction) and is prompted to only operate within the skills memory
+ * directory.
  */
 export const SkillExtractionAgent = (
   skillsDir: string,
@@ -279,12 +281,14 @@ export const SkillExtractionAgent = (
   },
   toolConfig: {
     tools: [
+      ACTIVATE_SKILL_TOOL_NAME,
       READ_FILE_TOOL_NAME,
       WRITE_FILE_TOOL_NAME,
       EDIT_TOOL_NAME,
       LS_TOOL_NAME,
       GLOB_TOOL_NAME,
       GREP_TOOL_NAME,
+      SHELL_TOOL_NAME,
     ],
   },
   get promptConfig() {
@@ -301,6 +305,9 @@ export const SkillExtractionAgent = (
         'Below is an index of past conversation sessions. Each line shows:',
         '[NEW] or [old] status, a 1-line summary, message count, and the file path.',
         '',
+        'The summary is a user-intent summary, not a workflow summary.',
+        'Matching summary text alone is never enough evidence for a reusable skill.',
+        '',
         '[NEW] = not yet processed for skill extraction (focus on these)',
         '[old] = previously processed (read only if a [NEW] session hints at a repeated pattern)',
         '',
@@ -319,7 +326,7 @@ export const SkillExtractionAgent = (
 
     return {
       systemPrompt: buildSystemPrompt(skillsDir),
-      query: `${initialContext}\n\nAnalyze the session index above. Read sessions that suggest repeated workflows using read_file. Extract reusable skills to ${skillsDir}/.`,
+      query: `${initialContext}\n\nAnalyze the session index above. The session summaries describe user intent, not workflow details. Read sessions that suggest repeated workflows using read_file. Only write a skill if the evidence shows a durable, recurring workflow or a stable recurring repo procedure. If recurrence or future reuse is unclear, create no skill and explain why.`,
     };
   },
   runConfig: {

packages/core/src/config/config.ts

@@ -699,6 +699,7 @@ export interface ConfigParameters {
   experimentalJitContext?: boolean;
   autoDistillation?: boolean;
   experimentalMemoryManager?: boolean;
+  experimentalContextManagementConfig?: string;
   experimentalAgentHistoryTruncation?: boolean;
   experimentalAgentHistoryTruncationThreshold?: number;
   experimentalAgentHistoryRetainedMessages?: number;
@@ -939,6 +940,7 @@ export class Config implements McpContext, AgentLoopContext {
   private readonly adminSkillsEnabled: boolean;
   private readonly experimentalJitContext: boolean;
   private readonly experimentalMemoryManager: boolean;
+  private readonly experimentalContextManagementConfig?: string;
   private readonly memoryBoundaryMarkers: readonly string[];
   private readonly topicUpdateNarration: boolean;
   private readonly disableLLMCorrection: boolean;
@@ -1150,6 +1152,8 @@ export class Config implements McpContext, AgentLoopContext {
 
     this.experimentalJitContext = params.experimentalJitContext ?? false;
     this.experimentalMemoryManager = params.experimentalMemoryManager ?? false;
+    this.experimentalContextManagementConfig =
+      params.experimentalContextManagementConfig;
     this.memoryBoundaryMarkers = params.memoryBoundaryMarkers ?? ['.git'];
     this.contextManagement = {
       enabled: params.contextManagement?.enabled ?? false,
@@ -2434,6 +2438,10 @@ export class Config implements McpContext, AgentLoopContext {
     return this.experimentalMemoryManager;
   }
 
+  getExperimentalContextManagementConfig(): string | undefined {
+    return this.experimentalContextManagementConfig;
+  }
+
   getContextManagementConfig(): ContextManagementConfig {
     return this.contextManagement;
   }
@@ -3544,6 +3552,7 @@ export class Config implements McpContext, AgentLoopContext {
           registry.registerTool(new RipGrepTool(this, this.messageBus)),
         );
       } else {
+        debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);
         logRipgrepFallback(this, new RipgrepFallbackEvent(errorString));
         maybeRegister(GrepTool, () =>
           registry.registerTool(new GrepTool(this, this.messageBus)),

packages/core/src/context/config/configLoader.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadContextManagementConfig } from './configLoader.js';
+import { defaultContextProfile } from './profiles.js';
+import { ContextProcessorRegistry } from './registry.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { Config } from '../../config/config.js';
+import type { JSONSchemaType } from 'ajv';
+
+describe('SidecarLoader (Real FS)', () => {
+  let tmpDir: string;
+  let registry: ContextProcessorRegistry;
+  let sidecarPath: string;
+  let mockConfig: Config;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gemini-sidecar-test-'));
+    sidecarPath = path.join(tmpDir, 'sidecar.json');
+    registry = new ContextProcessorRegistry();
+    registry.registerProcessor({
+      id: 'NodeTruncation',
+      schema: {
+        type: 'object',
+        properties: { maxTokens: { type: 'number' } },
+        required: ['maxTokens'],
+      } as unknown as JSONSchemaType<{ maxTokens: number }>,
+    });
+
+    mockConfig = {
+      getExperimentalContextManagementConfig: () => sidecarPath,
+    } as unknown as Config;
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns default profile if file does not exist', async () => {
+    const result = await loadContextManagementConfig(mockConfig, registry);
+    expect(result).toBe(defaultContextProfile);
+  });
+
+  it('returns default profile if file exists but is 0 bytes', async () => {
+    await fs.writeFile(sidecarPath, '');
+    const result = await loadContextManagementConfig(mockConfig, registry);
+    expect(result).toBe(defaultContextProfile);
+  });
+
+  it('returns parsed config if file is valid', async () => {
+    const validConfig = {
+      budget: { retainedTokens: 1000, maxTokens: 2000 },
+      processorOptions: {
+        myTruncation: {
+          type: 'NodeTruncation',
+          options: { maxTokens: 500 },
+        },
+      },
+    };
+    await fs.writeFile(sidecarPath, JSON.stringify(validConfig));
+    const result = await loadContextManagementConfig(mockConfig, registry);
+    expect(result.config.budget?.maxTokens).toBe(2000);
+    expect(result.config.processorOptions?.['myTruncation']).toBeDefined();
+  });
+
+  it('throws validation error if processorOptions contains invalid data for the schema', async () => {
+    const invalidConfig = {
+      budget: { retainedTokens: 1000, maxTokens: 2000 },
+      processorOptions: {
+        myTruncation: {
+          type: 'NodeTruncation',
+          options: { maxTokens: 'this should be a number' },
+        },
+      },
+    };
+    await fs.writeFile(sidecarPath, JSON.stringify(invalidConfig));
+    await expect(
+      loadContextManagementConfig(mockConfig, registry),
+    ).rejects.toThrow('Validation error');
+  });
+
+  it('throws validation error if file is empty whitespace', async () => {
+    await fs.writeFile(sidecarPath, '   \n  ');
+    await expect(
+      loadContextManagementConfig(mockConfig, registry),
+    ).rejects.toThrow('Unexpected end of JSON input');
+  });
+});

packages/core/src/context/config/configLoader.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config } from '../../config/config.js';
+import * as fsSync from 'node:fs';
+import * as fs from 'node:fs/promises';
+import type { ContextManagementConfig } from './types.js';
+import { defaultContextProfile, type ContextProfile } from './profiles.js';
+import { SchemaValidator } from '../../utils/schemaValidator.js';
+import { getContextManagementConfigSchema } from './schema.js';
+import type { ContextProcessorRegistry } from './registry.js';
+import { getErrorMessage } from '../../utils/errors.js';
+
+/**
+ * Loads and validates a sidecar config from a specific file path.
+ * Throws an error if the file cannot be read, parsed, or fails schema validation.
+ */
+async function loadConfigFromFile(
+  sidecarPath: string,
+  registry: ContextProcessorRegistry,
+): Promise<ContextProfile> {
+  const fileContent = await fs.readFile(sidecarPath, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fileContent);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse Sidecar configuration file at ${sidecarPath}: ${getErrorMessage(
+        error,
+      )}`,
+    );
+  }
+
+  // Validate the complete structure, including deep options
+  const validationError = SchemaValidator.validate(
+    getContextManagementConfigSchema(registry),
+    parsed,
+  );
+
+  if (validationError) {
+    throw new Error(
+      `Invalid sidecar configuration in ${sidecarPath}. Validation error: ${validationError}`,
+    );
+  }
+
+  // Extract strictly what we need.
+  // Why this unsafe cast is acceptable:
+  // SchemaValidator just ran \`getSidecarConfigSchema(registry)\` against \`parsed\`.
+  // That function dynamically maps the \`processorOptions\` to strict JSON schema definitions,
+  // so we know with absolute certainty at runtime that \`parsed\` conforms to this shape.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const validConfig = parsed as ContextManagementConfig;
+  return {
+    ...defaultContextProfile,
+    config: {
+      ...defaultContextProfile.config,
+      ...(validConfig.budget ? { budget: validConfig.budget } : {}),
+      ...(validConfig.processorOptions
+        ? { processorOptions: validConfig.processorOptions }
+        : {}),
+    },
+  };
+}
+
+/**
+ * Generates a Sidecar JSON graph from the experimental config file path or defaults.
+ * If a config file is present but invalid, this will THROW to prevent silent misconfiguration.
+ */
+export async function loadContextManagementConfig(
+  config: Config,
+  registry: ContextProcessorRegistry,
+): Promise<ContextProfile> {
+  const sidecarPath = config.getExperimentalContextManagementConfig();
+
+  if (sidecarPath && fsSync.existsSync(sidecarPath)) {
+    const size = fsSync.statSync(sidecarPath).size;
+    // If the file exists but is completely empty (0 bytes), it's safe to fallback.
+    if (size === 0) {
+      return defaultContextProfile;
+    }
+
+    // If the file has content, enforce strict validation and throw on failure.
+    return loadConfigFromFile(sidecarPath, registry);
+  }
+
+  return defaultContextProfile;
+}

packages/core/src/context/config/profiles.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  AsyncPipelineDef,
+  ContextManagementConfig,
+  PipelineDef,
+} from './types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+
+// Import factories
+import { createToolMaskingProcessor } from '../processors/toolMaskingProcessor.js';
+import { createBlobDegradationProcessor } from '../processors/blobDegradationProcessor.js';
+import { createNodeTruncationProcessor } from '../processors/nodeTruncationProcessor.js';
+import { createNodeDistillationProcessor } from '../processors/nodeDistillationProcessor.js';
+import { createStateSnapshotProcessor } from '../processors/stateSnapshotProcessor.js';
+import { createStateSnapshotAsyncProcessor } from '../processors/stateSnapshotAsyncProcessor.js';
+
+/**
+ * Helper to safely merge static default options with dynamically loaded
+ * JSON overrides from the SidecarConfig.
+ *
+ * Why the unsafe cast is acceptable here:
+ * Before the \`config\` object ever reaches this function, \`SidecarLoader.ts\`
+ * passes the raw JSON through \`SchemaValidator\`. The schema dynamically generates
+ * a \`oneOf\` map linking every \`type\` discriminator to its corresponding processor
+ * schema definition. By the time we access \`options\` here, its shape has been
+ * strictly validated against the corresponding Zod/JSONSchema definition at runtime,
+ * making the generic cast to \`<T>\` structurally safe.
+ */
+function resolveProcessorOptions<T>(
+  config: ContextManagementConfig | undefined,
+  id: string,
+  defaultOptions: T,
+): T {
+  if (config?.processorOptions && config.processorOptions[id]) {
+    return {
+      ...defaultOptions,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      ...(config.processorOptions[id].options as T),
+    };
+  }
+  return defaultOptions;
+}
+
+export interface ContextProfile {
+  config: ContextManagementConfig;
+  buildPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ) => PipelineDef[];
+  buildAsyncPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ) => AsyncPipelineDef[];
+}
+
+/**
+ * The standard default context management profile.
+ * Optimized for safety, precision, and reliable summarization.
+ */
+export const defaultContextProfile: ContextProfile = {
+  config: {
+    budget: {
+      retainedTokens: 65000,
+      maxTokens: 150000,
+    },
+  },
+
+  buildPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ): PipelineDef[] =>
+    // Helper to merge default options with dynamically loaded processorOptions by ID
+    [
+      {
+        name: 'Immediate Sanitization',
+        triggers: ['new_message'],
+        processors: [
+          createToolMaskingProcessor(
+            'ToolMasking',
+            env,
+            resolveProcessorOptions(config, 'ToolMasking', {
+              stringLengthThresholdTokens: 8000,
+            }),
+          ),
+          createBlobDegradationProcessor('BlobDegradation', env), // No options
+        ],
+      },
+      {
+        name: 'Normalization',
+        triggers: ['retained_exceeded'],
+        processors: [
+          createNodeTruncationProcessor(
+            'NodeTruncation',
+            env,
+            resolveProcessorOptions(config, 'NodeTruncation', {
+              maxTokensPerNode: 3000,
+            }),
+          ),
+          createNodeDistillationProcessor(
+            'NodeDistillation',
+            env,
+            resolveProcessorOptions(config, 'NodeDistillation', {
+              nodeThresholdTokens: 5000,
+            }),
+          ),
+        ],
+      },
+      {
+        name: 'Emergency Backstop',
+        triggers: ['gc_backstop'],
+        processors: [
+          createStateSnapshotProcessor(
+            'StateSnapshotSync',
+            env,
+            resolveProcessorOptions(config, 'StateSnapshotSync', {
+              target: 'max',
+            }),
+          ),
+        ],
+      },
+    ],
+  buildAsyncPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ): AsyncPipelineDef[] => [
+    {
+      name: 'Async Background GC',
+      triggers: ['nodes_aged_out'],
+      processors: [
+        createStateSnapshotAsyncProcessor(
+          'StateSnapshotAsync',
+          env,
+          resolveProcessorOptions(config, 'StateSnapshotAsync', {
+            type: 'accumulate',
+          }),
+        ),
+      ],
+    },
+  ],
+};

packages/core/src/context/config/registry.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { JSONSchemaType } from 'ajv';
+
+export interface ContextProcessorDef<T = unknown> {
+  readonly id: string;
+  readonly schema: JSONSchemaType<T>;
+}
+
+/**
+ * Registry for validating declarative sidecar configuration schemas.
+ * (Dynamic instantiation has been replaced by static ContextProfiles)
+ */
+export class ContextProcessorRegistry {
+  private readonly processors = new Map<string, ContextProcessorDef>();
+
+  registerProcessor<T>(def: ContextProcessorDef<T>) {
+    // Erasing the type.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    this.processors.set(def.id, def as unknown as ContextProcessorDef<unknown>);
+  }
+
+  getSchema(id: string): object | undefined {
+    return this.processors.get(id)?.schema;
+  }
+
+  getSchemaDefs(): ContextProcessorDef[] {
+    const defs = [];
+    for (const def of this.processors.values()) {
+      if (def.schema) defs.push({ id: def.id, schema: def.schema });
+    }
+    return defs;
+  }
+
+  clear() {
+    this.processors.clear();
+  }
+}

packages/core/src/context/config/schema.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ContextProcessorRegistry } from './registry.js';
+
+export function getContextManagementConfigSchema(
+  registry: ContextProcessorRegistry,
+) {
+  // We use a registry to deeply validate processor overrides.
+  // We do this by generating a `oneOf` list that matches the `type` discriminator
+  // to the specific processor `options` schema.
+  const processorOptionSchemas = registry.getSchemaDefs().map((def) => ({
+    type: 'object',
+    required: ['type', 'options'],
+    properties: {
+      type: { const: def.id },
+      options: def.schema,
+    },
+  }));
+
+  return {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'ContextManagementConfig',
+    description: 'The Hyperparameter schema for a Context Profile.',
+    type: 'object',
+    properties: {
+      budget: {
+        type: 'object',
+        description: 'Defines the token ceilings and limits for the pipeline.',
+        required: ['retainedTokens', 'maxTokens'],
+        properties: {
+          retainedTokens: {
+            type: 'number',
+            description:
+              'The ideal token count the pipeline tries to shrink down to.',
+          },
+          maxTokens: {
+            type: 'number',
+            description:
+              'The absolute maximum token count allowed before synchronous truncation kicks in.',
+          },
+        },
+      },
+      processorOptions: {
+        type: 'object',
+        description:
+          'Named hyperparameter configurations for ContextProcessors and AsyncProcessors.',
+        additionalProperties: { oneOf: processorOptionSchemas },
+      },
+    },
+  };
+}

packages/core/src/context/config/types.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ContextProcessor, AsyncContextProcessor } from '../pipeline.js';
+
+export type PipelineTrigger =
+  | 'new_message'
+  | 'retained_exceeded'
+  | 'gc_backstop'
+  | 'nodes_added'
+  | 'nodes_aged_out'
+  | { type: 'timer'; intervalMs: number };
+
+export interface PipelineDef {
+  name: string;
+  triggers: PipelineTrigger[];
+  processors: ContextProcessor[];
+}
+
+export interface AsyncPipelineDef {
+  name: string;
+  triggers: PipelineTrigger[];
+  processors: AsyncContextProcessor[];
+}
+
+export interface ContextBudget {
+  retainedTokens: number;
+  maxTokens: number;
+}
+
+/**
+ * The Data-Driven Schema for the Context Manager.
+ */
+export interface ContextManagementConfig {
+  /** Defines the token ceilings and limits for the pipeline. */
+  budget: ContextBudget;
+
+  /**
+   * Dynamic hyperparameter overrides for individual ContextProcessors and AsyncProcessors.
+   * Keys are named identifiers (e.g. "gentleTruncation").
+   */
+  processorOptions?: Record<string, { type: string; options: unknown }>;
+}

packages/core/src/context/contextManager.barrier.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { testTruncateProfile } from './testing/testProfile.js';
+import {
+  createSyntheticHistory,
+  createMockContextConfig,
+  setupContextComponentTest,
+} from './testing/contextTestUtils.js';
+
+describe('ContextManager Sync Pressure Barrier Tests', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('should instantly truncate history when maxTokens is exceeded using truncate strategy', async () => {
+    // 1. Setup
+    const config = createMockContextConfig();
+    const { chatHistory, contextManager } = setupContextComponentTest(
+      config,
+      testTruncateProfile,
+    );
+
+    // 2. Add System Prompt (Episode 0 - Protected)
+    chatHistory.set([
+      { role: 'user', parts: [{ text: 'System prompt' }] },
+      { role: 'model', parts: [{ text: 'Understood.' }] },
+    ]);
+
+    // 3. Add massive history that blows past the 150k maxTokens limit
+    // 20 turns * 10,000 tokens/turn = ~200,000 tokens
+    const massiveHistory = createSyntheticHistory(20, 35000);
+    chatHistory.set([...chatHistory.get(), ...massiveHistory]);
+
+    // 4. Add the Latest Turn (Protected)
+    chatHistory.set([
+      ...chatHistory.get(),
+      { role: 'user', parts: [{ text: 'Final question.' }] },
+      { role: 'model', parts: [{ text: 'Final answer.' }] },
+    ]);
+
+    const rawHistoryLength = chatHistory.get().length;
+
+    // 5. Project History (Triggers Sync Barrier)
+    const projection = await contextManager.renderHistory();
+
+    // 6. Assertions
+    // The barrier should have dropped several older episodes to get under 150k.
+
+    expect(projection.length).toBeLessThan(rawHistoryLength);
+
+    // Verify Episode 0 (System) is perfectly preserved at the front
+
+    expect(projection[0].role).toBe('user');
+    expect(projection[0].parts![0].text).toBe('System prompt');
+
+    // Filter out synthetic Yield nodes (they are model responses without actual tool/text bodies)
+    const contentNodes = projection.filter(
+      (p) =>
+        p.parts && p.parts.some((part) => part.text && part.text !== 'Yield'),
+    );
+
+    // Verify the latest turn is perfectly preserved at the back
+    const lastUser = contentNodes[contentNodes.length - 2];
+    const lastModel = contentNodes[contentNodes.length - 1];
+
+    expect(lastUser.role).toBe('user');
+    expect(lastUser.parts![0].text).toBe('Final question.');
+
+    expect(lastModel.role).toBe('model');
+    expect(lastModel.parts![0].text).toBe('Final answer.');
+  });
+});

packages/core/src/context/contextManager.ts

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/genai';
+import type { AgentChatHistory } from '../core/agentChatHistory.js';
+import type { ConcreteNode } from './graph/types.js';
+import type { ContextEventBus } from './eventBus.js';
+import type { ContextTracer } from './tracer.js';
+import type { ContextEnvironment } from './pipeline/environment.js';
+import type { ContextProfile } from './config/profiles.js';
+import type { PipelineOrchestrator } from './pipeline/orchestrator.js';
+import { HistoryObserver } from './historyObserver.js';
+import { render } from './graph/render.js';
+import { ContextWorkingBufferImpl } from './pipeline/contextWorkingBuffer.js';
+
+export class ContextManager {
+  // The master state containing the pristine graph and current active graph.
+  private buffer: ContextWorkingBufferImpl =
+    ContextWorkingBufferImpl.initialize([]);
+
+  private readonly eventBus: ContextEventBus;
+
+  // Internal sub-components
+  private readonly orchestrator: PipelineOrchestrator;
+  private readonly historyObserver: HistoryObserver;
+
+  constructor(
+    private readonly sidecar: ContextProfile,
+    private readonly env: ContextEnvironment,
+    private readonly tracer: ContextTracer,
+    orchestrator: PipelineOrchestrator,
+    chatHistory: AgentChatHistory,
+  ) {
+    this.eventBus = env.eventBus;
+    this.orchestrator = orchestrator;
+
+    this.historyObserver = new HistoryObserver(
+      chatHistory,
+      this.env.eventBus,
+      this.tracer,
+      this.env.tokenCalculator,
+      this.env.graphMapper,
+    );
+    this.historyObserver.start();
+
+    this.eventBus.onPristineHistoryUpdated((event) => {
+      const existingIds = new Set(this.buffer.nodes.map((n) => n.id));
+      const newIds = new Set(event.nodes.map((n) => n.id));
+      const addedNodes = event.nodes.filter((n) => !existingIds.has(n.id));
+
+      // Prune any pristine nodes that were dropped from the upstream history
+      this.buffer = this.buffer.prunePristineNodes(newIds);
+
+      if (addedNodes.length > 0) {
+        this.buffer = this.buffer.appendPristineNodes(addedNodes);
+      }
+
+      this.evaluateTriggers(event.newNodes);
+    });
+  }
+
+  /**
+   * Safely stops background async pipelines and clears event listeners.
+   */
+  shutdown() {
+    this.orchestrator.shutdown();
+    this.historyObserver.stop();
+  }
+
+  /**
+   * Evaluates if the current working buffer exceeds configured budget thresholds,
+   * firing consolidation events if necessary.
+   */
+  private evaluateTriggers(newNodes: Set<string>) {
+    if (!this.sidecar.config.budget) return;
+
+    if (newNodes.size > 0) {
+      this.eventBus.emitChunkReceived({
+        nodes: this.buffer.nodes,
+        targetNodeIds: newNodes,
+      });
+    }
+
+    const currentTokens = this.env.tokenCalculator.calculateConcreteListTokens(
+      this.buffer.nodes,
+    );
+
+    if (currentTokens > this.sidecar.config.budget.retainedTokens) {
+      const agedOutNodes = new Set<string>();
+      let rollingTokens = 0;
+      // Walk backwards finding nodes that fall out of the retained budget
+      for (let i = this.buffer.nodes.length - 1; i >= 0; i--) {
+        const node = this.buffer.nodes[i];
+        rollingTokens += this.env.tokenCalculator.calculateConcreteListTokens([
+          node,
+        ]);
+        if (rollingTokens > this.sidecar.config.budget.retainedTokens) {
+          agedOutNodes.add(node.id);
+        }
+      }
+
+      if (agedOutNodes.size > 0) {
+        this.env.tokenCalculator.garbageCollectCache(
+          new Set(this.buffer.nodes.map((n) => n.id)),
+        );
+        this.eventBus.emitConsolidationNeeded({
+          nodes: this.buffer.nodes,
+          targetDeficit:
+            currentTokens - this.sidecar.config.budget.retainedTokens,
+          targetNodeIds: agedOutNodes,
+        });
+      }
+    }
+  }
+
+  /**
+   * Retrieves the raw, uncompressed Episodic Context Graph graph.
+   * Useful for internal tool rendering (like the trace viewer).
+   * Note: This is an expensive, deep clone operation.
+   */
+  getPristineGraph(): readonly ConcreteNode[] {
+    const pristineSet = new Map<string, ConcreteNode>();
+    for (const node of this.buffer.nodes) {
+      const roots = this.buffer.getPristineNodes(node.id);
+      for (const root of roots) {
+        pristineSet.set(root.id, root);
+      }
+    }
+    // We sort them by timestamp to ensure they are returned in chronological order
+    return Array.from(pristineSet.values()).sort(
+      (a, b) => a.timestamp - b.timestamp,
+    );
+  }
+
+  /**
+   * Generates a virtual view of the pristine graph, substituting in variants
+   * up to the configured token budget.
+   * This is the view that will eventually be projected back to the LLM.
+   */
+  getNodes(): readonly ConcreteNode[] {
+    return [...this.buffer.nodes];
+  }
+
+  /**
+   * Executes the final 'gc_backstop' pipeline if necessary, enforcing the token budget,
+   * and maps the Episodic Context Graph back into a raw Gemini Content[] array for transmission.
+   * This is the primary method called by the agent framework before sending a request.
+   */
+  async renderHistory(
+    activeTaskIds: Set<string> = new Set(),
+  ): Promise<Content[]> {
+    this.tracer.logEvent('ContextManager', 'Starting rendering of LLM context');
+    // Apply final GC Backstop pressure barrier synchronously before mapping
+    const finalHistory = await render(
+      this.buffer.nodes,
+      this.orchestrator,
+      this.sidecar,
+      this.tracer,
+      this.env,
+      activeTaskIds,
+    );
+
+    this.tracer.logEvent('ContextManager', 'Finished rendering');
+
+    return finalHistory;
+  }
+}

packages/core/src/context/eventBus.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { EventEmitter } from 'node:events';
+import type { ConcreteNode } from './graph/types.js';
+
+export interface PristineHistoryUpdatedEvent {
+  nodes: readonly ConcreteNode[];
+  newNodes: Set<string>;
+}
+
+export interface ContextConsolidationEvent {
+  nodes: readonly ConcreteNode[];
+  targetDeficit: number;
+  targetNodeIds: Set<string>;
+}
+
+export interface ChunkReceivedEvent {
+  nodes: readonly ConcreteNode[];
+  targetNodeIds: Set<string>;
+}
+
+export class ContextEventBus extends EventEmitter {
+  emitPristineHistoryUpdated(event: PristineHistoryUpdatedEvent) {
+    this.emit('PRISTINE_HISTORY_UPDATED', event);
+  }
+
+  onPristineHistoryUpdated(
+    listener: (event: PristineHistoryUpdatedEvent) => void,
+  ) {
+    this.on('PRISTINE_HISTORY_UPDATED', listener);
+  }
+
+  emitChunkReceived(event: ChunkReceivedEvent) {
+    this.emit('IR_CHUNK_RECEIVED', event);
+  }
+
+  onChunkReceived(listener: (event: ChunkReceivedEvent) => void) {
+    this.on('IR_CHUNK_RECEIVED', listener);
+  }
+
+  emitConsolidationNeeded(event: ContextConsolidationEvent) {
+    this.emit('BUDGET_RETAINED_CROSSED', event);
+  }
+
+  onConsolidationNeeded(listener: (event: ContextConsolidationEvent) => void) {
+    this.on('BUDGET_RETAINED_CROSSED', listener);
+  }
+}

packages/core/src/context/graph/behaviorRegistry.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content, Part } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+
+export interface NodeSerializationWriter {
+  appendContent(content: Content): void;
+  appendModelPart(part: Part): void;
+  appendUserPart(part: Part): void;
+  flushModelParts(): void;
+}
+
+export interface NodeBehavior<T extends ConcreteNode = ConcreteNode> {
+  readonly type: T['type'];
+
+  /** Serializes the node into the Gemini Content structure. */
+  serialize(node: T, writer: NodeSerializationWriter): void;
+
+  /**
+   * Generates a structural representation of the node for the purpose
+   * of estimating its token cost.
+   */
+  getEstimatableParts(node: T): Part[];
+}
+
+export class NodeBehaviorRegistry {
+  private readonly behaviors = new Map<string, NodeBehavior<ConcreteNode>>();
+
+  register<T extends ConcreteNode>(behavior: NodeBehavior<T>) {
+    this.behaviors.set(behavior.type, behavior);
+  }
+
+  get(type: string): NodeBehavior<ConcreteNode> {
+    const behavior = this.behaviors.get(type);
+    if (!behavior) {
+      throw new Error(`Unregistered Node type: ${type}`);
+    }
+    return behavior;
+  }
+}

packages/core/src/context/graph/builtinBehaviors.ts

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Part } from '@google/genai';
+import type { NodeBehavior, NodeBehaviorRegistry } from './behaviorRegistry.js';
+import type {
+  UserPrompt,
+  AgentThought,
+  ToolExecution,
+  MaskedTool,
+  AgentYield,
+  Snapshot,
+  RollingSummary,
+  SystemEvent,
+} from './types.js';
+
+export const UserPromptBehavior: NodeBehavior<UserPrompt> = {
+  type: 'USER_PROMPT',
+  getEstimatableParts(prompt) {
+    const parts: Part[] = [];
+    for (const sp of prompt.semanticParts) {
+      switch (sp.type) {
+        case 'text':
+          parts.push({ text: sp.text });
+          break;
+        case 'inline_data':
+          parts.push({ inlineData: { mimeType: sp.mimeType, data: sp.data } });
+          break;
+        case 'file_data':
+          parts.push({
+            fileData: { mimeType: sp.mimeType, fileUri: sp.fileUri },
+          });
+          break;
+        case 'raw_part':
+          parts.push(sp.part);
+          break;
+        default:
+          break;
+      }
+    }
+    return parts;
+  },
+  serialize(prompt, writer) {
+    const parts = this.getEstimatableParts(prompt);
+    if (parts.length > 0) {
+      writer.flushModelParts();
+      writer.appendContent({ role: 'user', parts });
+    }
+  },
+};
+
+export const AgentThoughtBehavior: NodeBehavior<AgentThought> = {
+  type: 'AGENT_THOUGHT',
+  getEstimatableParts(thought) {
+    return [{ text: thought.text }];
+  },
+  serialize(thought, writer) {
+    writer.appendModelPart({ text: thought.text });
+  },
+};
+
+export const ToolExecutionBehavior: NodeBehavior<ToolExecution> = {
+  type: 'TOOL_EXECUTION',
+  getEstimatableParts(tool) {
+    return [
+      { functionCall: { id: tool.id, name: tool.toolName, args: tool.intent } },
+      {
+        functionResponse: {
+          id: tool.id,
+          name: tool.toolName,
+          response:
+            typeof tool.observation === 'string'
+              ? { message: tool.observation }
+              : tool.observation,
+        },
+      },
+    ];
+  },
+  serialize(tool, writer) {
+    const parts = this.getEstimatableParts(tool);
+    writer.appendModelPart(parts[0]);
+    writer.flushModelParts();
+    writer.appendUserPart(parts[1]);
+  },
+};
+
+export const MaskedToolBehavior: NodeBehavior<MaskedTool> = {
+  type: 'MASKED_TOOL',
+  getEstimatableParts(tool) {
+    return [
+      {
+        functionCall: {
+          id: tool.id,
+          name: tool.toolName,
+          args: tool.intent ?? {},
+        },
+      },
+      {
+        functionResponse: {
+          id: tool.id,
+          name: tool.toolName,
+          response:
+            typeof tool.observation === 'string'
+              ? { message: tool.observation }
+              : (tool.observation ?? {}),
+        },
+      },
+    ];
+  },
+  serialize(tool, writer) {
+    const parts = this.getEstimatableParts(tool);
+    writer.appendModelPart(parts[0]);
+    writer.flushModelParts();
+    writer.appendUserPart(parts[1]);
+  },
+};
+
+export const AgentYieldBehavior: NodeBehavior<AgentYield> = {
+  type: 'AGENT_YIELD',
+  getEstimatableParts(yieldNode) {
+    return [{ text: yieldNode.text }];
+  },
+  serialize(yieldNode, writer) {
+    writer.appendModelPart({ text: yieldNode.text });
+    writer.flushModelParts();
+  },
+};
+
+export const SystemEventBehavior: NodeBehavior<SystemEvent> = {
+  type: 'SYSTEM_EVENT',
+  getEstimatableParts() {
+    return [];
+  },
+  serialize(node, writer) {
+    writer.flushModelParts();
+  },
+};
+
+export const SnapshotBehavior: NodeBehavior<Snapshot> = {
+  type: 'SNAPSHOT',
+  getEstimatableParts(node) {
+    return [{ text: node.text }];
+  },
+  serialize(node, writer) {
+    writer.flushModelParts();
+    writer.appendUserPart({ text: node.text });
+  },
+};
+
+export const RollingSummaryBehavior: NodeBehavior<RollingSummary> = {
+  type: 'ROLLING_SUMMARY',
+  getEstimatableParts(node) {
+    return [{ text: node.text }];
+  },
+  serialize(node, writer) {
+    writer.flushModelParts();
+    writer.appendUserPart({ text: node.text });
+  },
+};
+
+export function registerBuiltInBehaviors(registry: NodeBehaviorRegistry) {
+  registry.register(UserPromptBehavior);
+  registry.register(AgentThoughtBehavior);
+  registry.register(ToolExecutionBehavior);
+  registry.register(MaskedToolBehavior);
+  registry.register(AgentYieldBehavior);
+  registry.register(SystemEventBehavior);
+  registry.register(SnapshotBehavior);
+  registry.register(RollingSummaryBehavior);
+}

packages/core/src/context/graph/fromGraph.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content, Part } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+import type {
+  NodeSerializationWriter,
+  NodeBehaviorRegistry,
+} from './behaviorRegistry.js';
+
+class NodeSerializer implements NodeSerializationWriter {
+  private history: Content[] = [];
+  private currentModelParts: Part[] = [];
+
+  appendContent(content: Content) {
+    this.flushModelParts();
+    this.history.push(content);
+  }
+
+  appendModelPart(part: Part) {
+    this.currentModelParts.push(part);
+  }
+
+  appendUserPart(part: Part) {
+    this.flushModelParts();
+    this.history.push({ role: 'user', parts: [part] });
+  }
+
+  flushModelParts() {
+    if (this.currentModelParts.length > 0) {
+      this.history.push({ role: 'model', parts: [...this.currentModelParts] });
+      this.currentModelParts = [];
+    }
+  }
+
+  getContents(): Content[] {
+    this.flushModelParts();
+    return this.history;
+  }
+}
+
+export function fromGraph(
+  nodes: readonly ConcreteNode[],
+  registry: NodeBehaviorRegistry,
+): Content[] {
+  const writer = new NodeSerializer();
+  for (const node of nodes) {
+    const behavior = registry.get(node.type);
+    behavior.serialize(node, writer);
+  }
+  return writer.getContents();
+}

packages/core/src/context/graph/mapper.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content } from '@google/genai';
+import type { Episode, ConcreteNode } from './types.js';
+import { toGraph } from './toGraph.js';
+import { fromGraph } from './fromGraph.js';
+import type { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import type { NodeBehaviorRegistry } from './behaviorRegistry.js';
+
+export class ContextGraphMapper {
+  private readonly nodeIdentityMap = new WeakMap<object, string>();
+
+  constructor(private readonly registry: NodeBehaviorRegistry) {}
+
+  toGraph(
+    history: readonly Content[],
+    tokenCalculator: ContextTokenCalculator,
+  ): Episode[] {
+    return toGraph(history, tokenCalculator, this.nodeIdentityMap);
+  }
+
+  fromGraph(nodes: readonly ConcreteNode[]): Content[] {
+    return fromGraph(nodes, this.registry);
+  }
+}

packages/core/src/context/graph/render.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import type {
+  ContextEnvironment,
+  ContextTracer,
+} from '../pipeline/environment.js';
+import type { PipelineOrchestrator } from '../pipeline/orchestrator.js';
+import type { ContextProfile } from '../config/profiles.js';
+
+/**
+ * Orchestrates the final render: takes a working buffer view (The Nodes),
+ * applies the Immediate Sanitization pipeline, and enforces token boundaries.
+ */
+export async function render(
+  nodes: readonly ConcreteNode[],
+  orchestrator: PipelineOrchestrator,
+  sidecar: ContextProfile,
+  tracer: ContextTracer,
+  env: ContextEnvironment,
+  protectedIds: Set<string>,
+): Promise<Content[]> {
+  if (!sidecar.config.budget) {
+    const contents = env.graphMapper.fromGraph(nodes);
+    tracer.logEvent('Render', 'Render Context to LLM (No Budget)', {
+      renderedContext: contents,
+    });
+    return contents;
+  }
+
+  const maxTokens = sidecar.config.budget.maxTokens;
+  const currentTokens = env.tokenCalculator.calculateConcreteListTokens(nodes);
+
+  // V0: Always protect the first node (System Prompt) and the last turn
+  if (nodes.length > 0) {
+    protectedIds.add(nodes[0].id);
+    if (nodes[0].logicalParentId) protectedIds.add(nodes[0].logicalParentId);
+
+    const lastNode = nodes[nodes.length - 1];
+    protectedIds.add(lastNode.id);
+    if (lastNode.logicalParentId) protectedIds.add(lastNode.logicalParentId);
+  }
+
+  if (currentTokens <= maxTokens) {
+    tracer.logEvent(
+      'Render',
+      `View is within maxTokens (${currentTokens} <= ${maxTokens}). Returning view.`,
+    );
+    const contents = env.graphMapper.fromGraph(nodes);
+    tracer.logEvent('Render', 'Render Context for LLM', {
+      renderedContext: contents,
+    });
+    return contents;
+  }
+
+  tracer.logEvent(
+    'Render',
+    `View exceeds maxTokens (${currentTokens} > ${maxTokens}). Hitting Synchronous Pressure Barrier.`,
+  );
+  debugLogger.log(
+    `Context Manager Synchronous Barrier triggered: View at ${currentTokens} tokens (limit: ${maxTokens}).`,
+  );
+
+  // Calculate exactly which nodes aged out of the retainedTokens budget to form our target delta
+  const agedOutNodes = new Set<string>();
+  let rollingTokens = 0;
+  // Start from newest and count backwards
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const node = nodes[i];
+    const nodeTokens = env.tokenCalculator.calculateConcreteListTokens([node]);
+    rollingTokens += nodeTokens;
+    if (rollingTokens > sidecar.config.budget.retainedTokens) {
+      agedOutNodes.add(node.id);
+    }
+  }
+
+  const processedNodes = await orchestrator.executeTriggerSync(
+    'gc_backstop',
+    nodes,
+    agedOutNodes,
+    protectedIds,
+  );
+
+  const finalTokens =
+    env.tokenCalculator.calculateConcreteListTokens(processedNodes);
+  tracer.logEvent(
+    'Render',
+    `Finished rendering. Final token count: ${finalTokens}.`,
+  );
+  debugLogger.log(
+    `Context Manager finished. Final actual token count: ${finalTokens}.`,
+  );
+
+  // Apply skipList logic to abstract over summarized nodes
+  const skipList = new Set<string>();
+  for (const node of processedNodes) {
+    if (node.abstractsIds) {
+      for (const id of node.abstractsIds) skipList.add(id);
+    }
+  }
+
+  const visibleNodes = processedNodes.filter((n) => !skipList.has(n.id));
+
+  const contents = env.graphMapper.fromGraph(visibleNodes);
+  tracer.logEvent('Render', 'Render Sanitized Context for LLM', {
+    renderedContextSanitized: contents,
+  });
+  return contents;
+}

packages/core/src/context/graph/toGraph.ts

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content, Part } from '@google/genai';
+import type {
+  Episode,
+  SemanticPart,
+  ToolExecution,
+  AgentThought,
+  AgentYield,
+  UserPrompt,
+} from './types.js';
+import type { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import { randomUUID } from 'node:crypto';
+import { isRecord } from '../../utils/markdownUtils.js';
+
+// We remove the global nodeIdentityMap and instead rely on one passed from ContextGraphMapper
+export function getStableId(
+  obj: object,
+  nodeIdentityMap: WeakMap<object, string>,
+): string {
+  let id = nodeIdentityMap.get(obj);
+  if (!id) {
+    id = randomUUID();
+    nodeIdentityMap.set(obj, id);
+  }
+  return id;
+}
+
+function isCompleteEpisode(ep: Partial<Episode>): ep is Episode {
+  return (
+    typeof ep.id === 'string' &&
+    Array.isArray(ep.concreteNodes) &&
+    ep.concreteNodes.length > 0
+  );
+}
+
+export function toGraph(
+  history: readonly Content[],
+  tokenCalculator: ContextTokenCalculator,
+  nodeIdentityMap: WeakMap<object, string>,
+): Episode[] {
+  const episodes: Episode[] = [];
+  let currentEpisode: Partial<Episode> | null = null;
+  const pendingCallParts: Map<string, Part> = new Map();
+
+  const finalizeEpisode = () => {
+    if (currentEpisode && isCompleteEpisode(currentEpisode)) {
+      episodes.push(currentEpisode);
+    }
+    currentEpisode = null;
+  };
+
+  for (const msg of history) {
+    if (!msg.parts) continue;
+
+    if (msg.role === 'user') {
+      const hasToolResponses = msg.parts.some((p) => !!p.functionResponse);
+      const hasUserParts = msg.parts.some(
+        (p) => !!p.text || !!p.inlineData || !!p.fileData,
+      );
+
+      if (hasToolResponses) {
+        currentEpisode = parseToolResponses(
+          msg,
+          currentEpisode,
+          pendingCallParts,
+          tokenCalculator,
+          nodeIdentityMap,
+        );
+      }
+
+      if (hasUserParts) {
+        finalizeEpisode();
+        currentEpisode = parseUserParts(msg, nodeIdentityMap);
+      }
+    } else if (msg.role === 'model') {
+      currentEpisode = parseModelParts(
+        msg,
+        currentEpisode,
+        pendingCallParts,
+        nodeIdentityMap,
+      );
+    }
+  }
+
+  if (currentEpisode) {
+    finalizeYield(currentEpisode);
+    finalizeEpisode();
+  }
+
+  return episodes;
+}
+
+function parseToolResponses(
+  msg: Content,
+  currentEpisode: Partial<Episode> | null,
+  pendingCallParts: Map<string, Part>,
+  tokenCalculator: ContextTokenCalculator,
+  nodeIdentityMap: WeakMap<object, string>,
+): Partial<Episode> {
+  if (!currentEpisode) {
+    currentEpisode = {
+      id: getStableId(msg, nodeIdentityMap),
+
+      concreteNodes: [],
+    };
+  }
+
+  const parts = msg.parts || [];
+  for (const part of parts) {
+    if (part.functionResponse) {
+      const callId = part.functionResponse.id || '';
+      const matchingCall = pendingCallParts.get(callId);
+
+      const intentTokens = matchingCall
+        ? tokenCalculator.estimateTokensForParts([matchingCall])
+        : 0;
+      const obsTokens = tokenCalculator.estimateTokensForParts([part]);
+
+      const step: ToolExecution = {
+        id: getStableId(part, nodeIdentityMap),
+        timestamp: Date.now(),
+        type: 'TOOL_EXECUTION',
+        toolName: part.functionResponse.name || 'unknown',
+        intent: isRecord(matchingCall?.functionCall?.args)
+          ? matchingCall.functionCall.args
+          : {},
+        observation: isRecord(part.functionResponse.response)
+          ? part.functionResponse.response
+          : {},
+        tokens: {
+          intent: intentTokens,
+          observation: obsTokens,
+        },
+      };
+      currentEpisode.concreteNodes = [
+        ...(currentEpisode.concreteNodes || []),
+        step,
+      ];
+      if (callId) pendingCallParts.delete(callId);
+    }
+  }
+  return currentEpisode;
+}
+
+function parseUserParts(
+  msg: Content,
+  nodeIdentityMap: WeakMap<object, string>,
+): Partial<Episode> {
+  const semanticParts: SemanticPart[] = [];
+  const parts = msg.parts || [];
+  for (const p of parts) {
+    if (p.text !== undefined)
+      semanticParts.push({ type: 'text', text: p.text });
+    else if (p.inlineData)
+      semanticParts.push({
+        type: 'inline_data',
+        mimeType: p.inlineData.mimeType || '',
+        data: p.inlineData.data || '',
+      });
+    else if (p.fileData)
+      semanticParts.push({
+        type: 'file_data',
+        mimeType: p.fileData.mimeType || '',
+        fileUri: p.fileData.fileUri || '',
+      });
+    else if (!p.functionResponse)
+      semanticParts.push({ type: 'raw_part', part: p }); // Preserve unknowns
+  }
+
+  const baseObj = parts.length > 0 ? parts[0] : msg;
+  const trigger: UserPrompt = {
+    id: getStableId(baseObj, nodeIdentityMap),
+    timestamp: Date.now(),
+    type: 'USER_PROMPT',
+    semanticParts,
+  };
+  return {
+    id: getStableId(msg, nodeIdentityMap),
+
+    concreteNodes: [trigger],
+  };
+}
+
+function parseModelParts(
+  msg: Content,
+  currentEpisode: Partial<Episode> | null,
+  pendingCallParts: Map<string, Part>,
+  nodeIdentityMap: WeakMap<object, string>,
+): Partial<Episode> {
+  if (!currentEpisode) {
+    currentEpisode = {
+      id: getStableId(msg, nodeIdentityMap),
+
+      concreteNodes: [],
+    };
+  }
+
+  const parts = msg.parts || [];
+  for (const part of parts) {
+    if (part.functionCall) {
+      const callId = part.functionCall.id || '';
+      if (callId) pendingCallParts.set(callId, part);
+    } else if (part.text) {
+      const thought: AgentThought = {
+        id: getStableId(part, nodeIdentityMap),
+        timestamp: Date.now(),
+        type: 'AGENT_THOUGHT',
+        text: part.text,
+      };
+
+      currentEpisode.concreteNodes = [
+        ...(currentEpisode.concreteNodes || []),
+        thought,
+      ];
+    }
+  }
+  return currentEpisode;
+}
+
+function finalizeYield(currentEpisode: Partial<Episode>) {
+  if (currentEpisode.concreteNodes && currentEpisode.concreteNodes.length > 0) {
+    const yieldNode: AgentYield = {
+      id: randomUUID(),
+      timestamp: Date.now(),
+      type: 'AGENT_YIELD',
+      text: 'Yield', // Synthesized yield since we don't have the original concrete node
+    };
+    const existingNodes = currentEpisode.concreteNodes || [];
+    currentEpisode.concreteNodes = [...existingNodes, yieldNode];
+  }
+}

packages/core/src/context/graph/types.ts

@@ -0,0 +1,222 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Part } from '@google/genai';
+
+export type NodeType =
+  // Organic Concrete Nodes
+  | 'USER_PROMPT'
+  | 'SYSTEM_EVENT'
+  | 'AGENT_THOUGHT'
+  | 'TOOL_EXECUTION'
+  | 'AGENT_YIELD'
+
+  // Synthetic Concrete Nodes
+  | 'SNAPSHOT'
+  | 'ROLLING_SUMMARY'
+  | 'MASKED_TOOL'
+
+  // Logical Nodes
+  | 'TASK'
+  | 'EPISODE';
+
+/** Base interface for all nodes in the Episodic Context Graph */
+export interface Node {
+  readonly id: string;
+  readonly type: NodeType;
+}
+
+/**
+ * Concrete Nodes: The atomic, renderable pieces of data.
+ * These are the actual "planks" of the Nodes of Theseus.
+ */
+export interface BaseConcreteNode extends Node {
+  readonly timestamp: number;
+  /** The ID of the Logical Node (e.g., Episode) that structurally owns this node */
+  readonly logicalParentId?: string;
+
+  /** If this node replaced a single node 1:1 (e.g., masking), this points to the original */
+  readonly replacesId?: string;
+
+  /** If this node is a synthetic summary of N nodes, this points to the original IDs */
+  readonly abstractsIds?: readonly string[];
+}
+
+/**
+ * Semantic Parts for User Prompts
+ */
+export interface SemanticTextPart {
+  readonly type: 'text';
+  readonly text: string;
+}
+
+export interface SemanticInlineDataPart {
+  readonly type: 'inline_data';
+  readonly mimeType: string;
+  readonly data: string;
+}
+
+export interface SemanticFileDataPart {
+  readonly type: 'file_data';
+  readonly mimeType: string;
+  readonly fileUri: string;
+}
+
+export interface SemanticRawPart {
+  readonly type: 'raw_part';
+  readonly part: Part;
+}
+
+export type SemanticPart =
+  | SemanticTextPart
+  | SemanticInlineDataPart
+  | SemanticFileDataPart
+  | SemanticRawPart;
+
+/**
+ * Trigger Nodes
+ * Events that wake the agent up and initiate an Episode.
+ */
+export interface UserPrompt extends BaseConcreteNode {
+  readonly type: 'USER_PROMPT';
+  readonly semanticParts: readonly SemanticPart[];
+}
+
+export interface SystemEvent extends BaseConcreteNode {
+  readonly type: 'SYSTEM_EVENT';
+  readonly name: string;
+  readonly payload: Record<string, unknown>;
+}
+
+export type EpisodeTrigger = UserPrompt | SystemEvent;
+
+/**
+ * Step Nodes
+ * The internal autonomous actions taken by the agent during its loop.
+ */
+export interface AgentThought extends BaseConcreteNode {
+  readonly type: 'AGENT_THOUGHT';
+  readonly text: string;
+}
+
+export interface ToolExecution extends BaseConcreteNode {
+  readonly type: 'TOOL_EXECUTION';
+  readonly toolName: string;
+  readonly intent: Record<string, unknown>;
+  readonly observation: string | Record<string, unknown>;
+  readonly tokens: {
+    readonly intent: number;
+    readonly observation: number;
+  };
+}
+
+export interface MaskedTool extends BaseConcreteNode {
+  readonly type: 'MASKED_TOOL';
+  readonly toolName: string;
+  readonly intent?: Record<string, unknown>;
+  readonly observation?: string | Record<string, unknown>;
+  readonly tokens: {
+    readonly intent: number;
+    readonly observation: number;
+  };
+}
+
+export type EpisodeStep = AgentThought | ToolExecution | MaskedTool;
+
+/**
+ * Resolution Node
+ * The final message where the agent yields control back to the user.
+ */
+export interface AgentYield extends BaseConcreteNode {
+  readonly type: 'AGENT_YIELD';
+  readonly text: string;
+}
+
+/**
+ * Synthetic Leaf Interfaces
+ * Processors that generate summaries emit explicit synthetic nodes.
+ */
+export interface Snapshot extends BaseConcreteNode {
+  readonly type: 'SNAPSHOT';
+  readonly text: string;
+}
+
+export interface RollingSummary extends BaseConcreteNode {
+  readonly type: 'ROLLING_SUMMARY';
+  readonly text: string;
+}
+
+export type SyntheticLeaf = Snapshot | RollingSummary;
+
+export type ConcreteNode =
+  | UserPrompt
+  | SystemEvent
+  | AgentThought
+  | ToolExecution
+  | MaskedTool
+  | AgentYield
+  | Snapshot
+  | RollingSummary;
+
+/**
+ * Logical Nodes
+ * These define hierarchy and grouping. They do not directly render to Gemini.
+ */
+export interface Episode extends Node {
+  readonly type: 'EPISODE';
+  /** References to the Concrete Node IDs that conceptually belong to this Episode. */
+  concreteNodes: readonly ConcreteNode[];
+}
+
+export interface Task extends Node {
+  readonly type: 'TASK';
+  readonly goal: string;
+  readonly status: 'active' | 'completed' | 'failed';
+  /** References to the Episode IDs that belong to this task */
+  readonly episodeIds: readonly string[];
+}
+
+export type LogicalNode = Task | Episode;
+
+export function isEpisode(node: Node): node is Episode {
+  return node.type === 'EPISODE';
+}
+
+export function isTask(node: Node): node is Task {
+  return node.type === 'TASK';
+}
+
+export function isAgentThought(node: Node): node is AgentThought {
+  return node.type === 'AGENT_THOUGHT';
+}
+
+export function isAgentYield(node: Node): node is AgentYield {
+  return node.type === 'AGENT_YIELD';
+}
+
+export function isToolExecution(node: Node): node is ToolExecution {
+  return node.type === 'TOOL_EXECUTION';
+}
+
+export function isMaskedTool(node: Node): node is MaskedTool {
+  return node.type === 'MASKED_TOOL';
+}
+
+export function isUserPrompt(node: Node): node is UserPrompt {
+  return node.type === 'USER_PROMPT';
+}
+
+export function isSystemEvent(node: Node): node is SystemEvent {
+  return node.type === 'SYSTEM_EVENT';
+}
+
+export function isSnapshot(node: Node): node is Snapshot {
+  return node.type === 'SNAPSHOT';
+}
+
+export function isRollingSummary(node: Node): node is RollingSummary {
+  return node.type === 'ROLLING_SUMMARY';
+}

packages/core/src/context/historyObserver.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  AgentChatHistory,
+  HistoryEvent,
+} from '../core/agentChatHistory.js';
+import type { ContextGraphMapper } from './graph/mapper.js';
+import type { ContextTokenCalculator } from './utils/contextTokenCalculator.js';
+import type { ContextEventBus } from './eventBus.js';
+import type { ContextTracer } from './tracer.js';
+
+import type { ConcreteNode } from './graph/types.js';
+
+/**
+ * Connects the raw AgentChatHistory to the ContextManager.
+ * It maps raw messages into Episodic Intermediate Representation (Context Graph)
+ * and evaluates background triggers whenever history changes.
+ */
+export class HistoryObserver {
+  private unsubscribeHistory?: () => void;
+
+  private readonly seenNodeIds = new Set<string>();
+
+  constructor(
+    private readonly chatHistory: AgentChatHistory,
+    private readonly eventBus: ContextEventBus,
+    private readonly tracer: ContextTracer,
+    private readonly tokenCalculator: ContextTokenCalculator,
+    private readonly graphMapper: ContextGraphMapper,
+  ) {}
+
+  start() {
+    if (this.unsubscribeHistory) {
+      this.unsubscribeHistory();
+    }
+
+    this.unsubscribeHistory = this.chatHistory.subscribe(
+      (_event: HistoryEvent) => {
+        // Rebuild the pristine Context Graph graph from the full source history on every change.
+        // Wait, toGraph still returns an Episode[].
+        // We actually need to map the Episode[] to a flat ConcreteNode[] here to form the 'nodes'.
+        const pristineEpisodes = this.graphMapper.toGraph(
+          this.chatHistory.get(),
+          this.tokenCalculator,
+        );
+
+        const nodes: ConcreteNode[] = [];
+        for (const ep of pristineEpisodes) {
+          if (ep.concreteNodes) {
+            for (const child of ep.concreteNodes) {
+              nodes.push(child);
+            }
+          }
+        }
+
+        const newNodes = new Set<string>();
+        for (const node of nodes) {
+          if (!this.seenNodeIds.has(node.id)) {
+            newNodes.add(node.id);
+            this.seenNodeIds.add(node.id);
+          }
+        }
+
+        this.tracer.logEvent(
+          'HistoryObserver',
+          'Rebuilt pristine graph from chat history update',
+          { nodesSize: nodes.length, newNodesCount: newNodes.size },
+        );
+
+        this.eventBus.emitPristineHistoryUpdated({
+          nodes,
+          newNodes,
+        });
+      },
+    );
+  }
+
+  stop() {
+    if (this.unsubscribeHistory) {
+      this.unsubscribeHistory();
+      this.unsubscribeHistory = undefined;
+    }
+  }
+}

packages/core/src/context/pipeline.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ConcreteNode } from './graph/types.js';
+
+export interface InboxMessage<T = unknown> {
+  id: string;
+  topic: string;
+  payload: T;
+  timestamp: number;
+}
+
+export interface InboxSnapshot {
+  getMessages<T = unknown>(topic: string): ReadonlyArray<InboxMessage<T>>;
+  consume(messageId: string): void;
+}
+
+export interface GraphMutation {
+  readonly processorId: string;
+  readonly timestamp: number;
+  readonly removedIds: readonly string[];
+  readonly addedNodes: readonly ConcreteNode[];
+}
+
+export interface ContextWorkingBuffer {
+  readonly nodes: readonly ConcreteNode[];
+  getPristineNodes(id: string): readonly ConcreteNode[];
+  getLineage(id: string): readonly ConcreteNode[];
+  getAuditLog(): readonly GraphMutation[];
+}
+
+export interface ProcessArgs {
+  readonly buffer: ContextWorkingBuffer;
+  readonly targets: readonly ConcreteNode[];
+  readonly inbox: InboxSnapshot;
+}
+
+/**
+ * A ContextProcessor is a pure, closure-based object that returns a modified subset of nodes
+ * (or the original targets if no changes are needed).
+ * The Orchestrator will use this to generate a new graph delta.
+ */
+export interface ContextProcessor {
+  readonly id: string;
+  readonly name: string;
+  process(args: ProcessArgs): Promise<readonly ConcreteNode[]>;
+}
+
+export interface AsyncContextProcessor {
+  readonly id: string;
+  readonly name: string;
+  process(args: ProcessArgs): Promise<void>;
+}
+
+export interface BackstopTargetOptions {
+  target?: 'incremental' | 'freeNTokens' | 'max';
+  freeTokensTarget?: number;
+}

packages/core/src/context/pipeline/contextWorkingBuffer.test.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ContextWorkingBufferImpl } from './contextWorkingBuffer.js';
+import { createDummyNode } from '../testing/contextTestUtils.js';
+
+describe('ContextWorkingBufferImpl', () => {
+  it('should initialize with a pristine graph correctly', () => {
+    const pristine1 = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      undefined,
+      'p1',
+    );
+    const pristine2 = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      10,
+      undefined,
+      'p2',
+    );
+
+    const buffer = ContextWorkingBufferImpl.initialize([pristine1, pristine2]);
+
+    expect(buffer.nodes).toHaveLength(2);
+    expect(buffer.getAuditLog()).toHaveLength(0);
+
+    // Pristine nodes should point to themselves
+    expect(buffer.getPristineNodes('p1')).toEqual([pristine1]);
+    expect(buffer.getPristineNodes('p2')).toEqual([pristine2]);
+  });
+
+  it('should track 1:1 replacements (e.g., masking) and append to audit log', () => {
+    const pristine1 = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      undefined,
+      'p1',
+    );
+    let buffer = ContextWorkingBufferImpl.initialize([pristine1]);
+
+    const maskedNode = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      5,
+      undefined,
+      'm1',
+    );
+    // Simulate what a processor does
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (maskedNode as any).replacesId = 'p1';
+
+    buffer = buffer.applyProcessorResult(
+      'ToolMasking',
+      [pristine1],
+      [maskedNode],
+    );
+
+    expect(buffer.nodes).toHaveLength(1);
+    expect(buffer.nodes[0].id).toBe('m1');
+
+    const log = buffer.getAuditLog();
+    expect(log).toHaveLength(1);
+    expect(log[0].processorId).toBe('ToolMasking');
+    expect(log[0].removedIds).toEqual(['p1']);
+    expect(log[0].addedNodes[0].id).toBe('m1');
+
+    // Provenance lookup: the masked node should resolve back to the pristine root
+    expect(buffer.getPristineNodes('m1')).toEqual([pristine1]);
+  });
+
+  it('should track N:1 abstractions (e.g., rolling summaries)', () => {
+    const p1 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p1');
+    const p2 = createDummyNode('ep1', 'AGENT_THOUGHT', 10, undefined, 'p2');
+    const p3 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p3');
+
+    let buffer = ContextWorkingBufferImpl.initialize([p1, p2, p3]);
+
+    const summaryNode = createDummyNode(
+      'ep1',
+      'ROLLING_SUMMARY',
+      15,
+      undefined,
+      's1',
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (summaryNode as any).abstractsIds = ['p1', 'p2'];
+
+    buffer = buffer.applyProcessorResult('Summarizer', [p1, p2], [summaryNode]);
+
+    // p1 and p2 are removed, p3 remains, s1 is added
+    expect(buffer.nodes.map((n) => n.id)).toEqual(['p3', 's1']);
+
+    // Provenance lookup: The summary node should resolve to both p1 and p2!
+    const roots = buffer.getPristineNodes('s1');
+    expect(roots).toHaveLength(2);
+    expect(roots).toContain(p1);
+    expect(roots).toContain(p2);
+  });
+
+  it('should track multi-generation provenance correctly', () => {
+    const p1 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p1');
+    let buffer = ContextWorkingBufferImpl.initialize([p1]);
+
+    // Gen 1: Masked
+    const gen1 = createDummyNode('ep1', 'USER_PROMPT', 8, undefined, 'gen1');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (gen1 as any).replacesId = 'p1';
+    buffer = buffer.applyProcessorResult('Masking', [p1], [gen1]);
+
+    // Gen 2: Summarized
+    const gen2 = createDummyNode(
+      'ep1',
+      'ROLLING_SUMMARY',
+      5,
+      undefined,
+      'gen2',
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (gen2 as any).abstractsIds = ['gen1'];
+    buffer = buffer.applyProcessorResult('Summarizer', [gen1], [gen2]);
+
+    expect(buffer.nodes).toHaveLength(1);
+    expect(buffer.nodes[0].id).toBe('gen2');
+
+    // Audit log should show sequence
+    const log = buffer.getAuditLog();
+    expect(log).toHaveLength(2);
+    expect(log[0].processorId).toBe('Masking');
+    expect(log[1].processorId).toBe('Summarizer');
+
+    // Multi-gen Provenance lookup: gen2 -> gen1 -> p1
+    expect(buffer.getPristineNodes('gen2')).toEqual([p1]);
+  });
+
+  it('should handle net-new injected nodes without throwing', () => {
+    const p1 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p1');
+    let buffer = ContextWorkingBufferImpl.initialize([p1]);
+
+    const injected = createDummyNode(
+      'ep1',
+      'SYSTEM_EVENT',
+      5,
+      undefined,
+      'injected1',
+    );
+    // No replacesId or abstractsIds
+
+    buffer = buffer.applyProcessorResult('Injector', [], [injected]);
+
+    expect(buffer.nodes.map((n) => n.id)).toEqual(['p1', 'injected1']);
+
+    // It should root to itself
+    expect(buffer.getPristineNodes('injected1')).toEqual([injected]);
+  });
+});

packages/core/src/context/pipeline/contextWorkingBuffer.ts

@@ -0,0 +1,270 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ContextWorkingBuffer, GraphMutation } from '../pipeline.js';
+import type { ConcreteNode } from '../graph/types.js';
+
+export class ContextWorkingBufferImpl implements ContextWorkingBuffer {
+  // The current active graph
+  readonly nodes: readonly ConcreteNode[];
+
+  // The AOT pre-calculated provenance index (Current ID -> Pristine IDs)
+  private readonly provenanceMap: ReadonlyMap<string, ReadonlySet<string>>;
+
+  // The original immutable pristine nodes mapping
+  private readonly pristineNodesMap: ReadonlyMap<string, ConcreteNode>;
+
+  // The historical linked list of changes
+  private readonly history: readonly GraphMutation[];
+
+  private constructor(
+    nodes: readonly ConcreteNode[],
+    pristineNodesMap: ReadonlyMap<string, ConcreteNode>,
+    provenanceMap: ReadonlyMap<string, ReadonlySet<string>>,
+    history: readonly GraphMutation[],
+  ) {
+    this.nodes = nodes;
+    this.pristineNodesMap = pristineNodesMap;
+    this.provenanceMap = provenanceMap;
+    this.history = history;
+  }
+
+  /**
+   * Initializes a brand new ContextWorkingBuffer from a pristine graph.
+   * Every node's provenance points to itself.
+   */
+  static initialize(
+    pristineNodes: readonly ConcreteNode[],
+  ): ContextWorkingBufferImpl {
+    const pristineMap = new Map<string, ConcreteNode>();
+    const initialProvenance = new Map<string, ReadonlySet<string>>();
+
+    for (const node of pristineNodes) {
+      pristineMap.set(node.id, node);
+      initialProvenance.set(node.id, new Set([node.id]));
+    }
+
+    return new ContextWorkingBufferImpl(
+      pristineNodes,
+      pristineMap,
+      initialProvenance,
+      [], // Empty history
+    );
+  }
+
+  /**
+   * Appends newly observed pristine nodes (e.g. from a user message) to the working buffer.
+   * Ensures they are tracked in the pristine map and point to themselves in provenance.
+   */
+  appendPristineNodes(
+    newNodes: readonly ConcreteNode[],
+  ): ContextWorkingBufferImpl {
+    if (newNodes.length === 0) return this;
+
+    const newPristineMap = new Map<string, ConcreteNode>(this.pristineNodesMap);
+    const newProvenanceMap = new Map(this.provenanceMap);
+
+    for (const node of newNodes) {
+      newPristineMap.set(node.id, node);
+      newProvenanceMap.set(node.id, new Set([node.id]));
+    }
+
+    return new ContextWorkingBufferImpl(
+      [...this.nodes, ...newNodes],
+      newPristineMap,
+      newProvenanceMap,
+      [...this.history],
+    );
+  }
+
+  /**
+   * Generates an entirely new buffer instance by calculating the delta between the processor's input and output.
+   */
+  applyProcessorResult(
+    processorId: string,
+    inputTargets: readonly ConcreteNode[],
+    outputNodes: readonly ConcreteNode[],
+  ): ContextWorkingBufferImpl {
+    const outputIds = new Set(outputNodes.map((n) => n.id));
+    const inputIds = new Set(inputTargets.map((n) => n.id));
+
+    // Calculate diffs
+    const removedIds = inputTargets
+      .filter((n) => !outputIds.has(n.id))
+      .map((n) => n.id);
+    const addedNodes = outputNodes.filter((n) => !inputIds.has(n.id));
+
+    // Create mutation record
+    const mutation: GraphMutation = {
+      processorId,
+      timestamp: Date.now(),
+      removedIds,
+      addedNodes,
+    };
+
+    // Calculate new node array
+    const removedSet = new Set(removedIds);
+    const retainedNodes = this.nodes.filter((n) => !removedSet.has(n.id));
+    const newGraph = [...retainedNodes];
+
+    // We append the output nodes in the same general position if possible,
+    // but in a complex graph we just ensure they exist. V2 graph uses timestamps for order.
+    // For simplicity, we just push added nodes to the end of the retained array
+    newGraph.push(...addedNodes);
+
+    // Calculate new provenance map
+    const newProvenanceMap = new Map(this.provenanceMap);
+
+    let finalPristineMap = this.pristineNodesMap;
+
+    // Map the new synthetic nodes back to their pristine roots
+    for (const added of addedNodes) {
+      const roots = new Set<string>();
+
+      // 1:1 Replacement (e.g. Masked Node)
+      if (added.replacesId) {
+        const inheritedRoots = this.provenanceMap.get(added.replacesId);
+        if (inheritedRoots) {
+          for (const rootId of inheritedRoots) roots.add(rootId);
+        }
+      }
+
+      // N:1 Abstraction (e.g. Rolling Summary)
+      if (added.abstractsIds) {
+        for (const abstractId of added.abstractsIds) {
+          const inheritedRoots = this.provenanceMap.get(abstractId);
+          if (inheritedRoots) {
+            for (const rootId of inheritedRoots) roots.add(rootId);
+          }
+        }
+      }
+
+      // If it has no links back to the original graph, it is its own root
+      // (e.g., a system-injected instruction)
+      if (roots.size === 0) {
+        roots.add(added.id);
+        // It acts as a net-new pristine root.
+        if (!finalPristineMap.has(added.id)) {
+          const mutableMap = new Map<string, ConcreteNode>(finalPristineMap);
+          mutableMap.set(added.id, added);
+          finalPristineMap = mutableMap;
+        }
+      }
+
+      newProvenanceMap.set(added.id, roots);
+    }
+
+    // GC the Caches
+    // We only want to keep provenance and pristine entries that are reachable
+    // from the nodes in 'newGraph'.
+    const reachablePristineIds = new Set<string>();
+    const reachableCurrentIds = new Set<string>();
+
+    for (const node of newGraph) {
+      reachableCurrentIds.add(node.id);
+      const roots = newProvenanceMap.get(node.id);
+      if (roots) {
+        for (const root of roots) {
+          reachablePristineIds.add(root);
+        }
+      }
+    }
+
+    // Prune Provenance Map
+    for (const [id] of newProvenanceMap) {
+      if (!reachableCurrentIds.has(id)) {
+        newProvenanceMap.delete(id);
+      }
+    }
+
+    // Prune Pristine Map
+    const prunedPristineMap = new Map<string, ConcreteNode>();
+    for (const id of reachablePristineIds) {
+      const node = finalPristineMap.get(id);
+      if (node) prunedPristineMap.set(id, node);
+    }
+    finalPristineMap = prunedPristineMap;
+
+    return new ContextWorkingBufferImpl(
+      newGraph,
+      finalPristineMap,
+      newProvenanceMap,
+      [...this.history, mutation],
+    );
+  }
+
+  /** Removes nodes from the working buffer that were completely dropped from the upstream pristine history */
+  prunePristineNodes(
+    retainedIds: ReadonlySet<string>,
+  ): ContextWorkingBufferImpl {
+    const newGraph = this.nodes.filter(
+      (n) => retainedIds.has(n.id) || !this.pristineNodesMap.has(n.id),
+    );
+
+    const newProvenanceMap = new Map(this.provenanceMap);
+    const reachablePristineIds = new Set<string>();
+    const reachableCurrentIds = new Set<string>();
+
+    for (const node of newGraph) {
+      reachableCurrentIds.add(node.id);
+      const roots = newProvenanceMap.get(node.id);
+      if (roots) {
+        for (const root of roots) {
+          if (retainedIds.has(root) || !this.pristineNodesMap.has(root)) {
+            reachablePristineIds.add(root);
+          }
+        }
+      }
+    }
+
+    for (const [id] of newProvenanceMap) {
+      if (!reachableCurrentIds.has(id)) {
+        newProvenanceMap.delete(id);
+      }
+    }
+
+    const prunedPristineMap = new Map<string, ConcreteNode>();
+    for (const id of reachablePristineIds) {
+      const node = this.pristineNodesMap.get(id);
+      if (node) prunedPristineMap.set(id, node);
+    }
+
+    return new ContextWorkingBufferImpl(
+      newGraph,
+      prunedPristineMap,
+      newProvenanceMap,
+      [...this.history],
+    );
+  }
+
+  getPristineNodes(id: string): readonly ConcreteNode[] {
+    const pristineIds = this.provenanceMap.get(id);
+    if (!pristineIds) return [];
+    return Array.from(pristineIds).map(
+      (pid) => this.pristineNodesMap.get(pid)!,
+    );
+  }
+
+  getAuditLog(): readonly GraphMutation[] {
+    return this.history;
+  }
+
+  getLineage(id: string): readonly ConcreteNode[] {
+    const lineage: ConcreteNode[] = [];
+    const currentNodesMap = new Map(this.nodes.map((n) => [n.id, n]));
+
+    let current = currentNodesMap.get(id);
+    while (current) {
+      lineage.push(current);
+      if (current.logicalParentId && current.logicalParentId !== current.id) {
+        current = currentNodesMap.get(current.logicalParentId);
+      } else {
+        break;
+      }
+    }
+    return lineage;
+  }
+}

packages/core/src/context/pipeline/environment.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { ContextEventBus } from '../eventBus.js';
+import type { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import type { ContextTracer } from '../tracer.js';
+import type { LiveInbox } from './inbox.js';
+import type { NodeBehaviorRegistry } from '../graph/behaviorRegistry.js';
+import type { ContextGraphMapper } from '../graph/mapper.js';
+
+export type { ContextTracer, ContextEventBus };
+
+export interface ContextEnvironment {
+  readonly llmClient: BaseLlmClient;
+  readonly promptId: string;
+  readonly sessionId: string;
+  readonly traceDir: string;
+  readonly projectTempDir: string;
+  readonly tracer: ContextTracer;
+  readonly charsPerToken: number;
+  readonly tokenCalculator: ContextTokenCalculator;
+  readonly eventBus: ContextEventBus;
+  readonly inbox: LiveInbox;
+  readonly behaviorRegistry: NodeBehaviorRegistry;
+  readonly graphMapper: ContextGraphMapper;
+}

packages/core/src/context/pipeline/environmentImpl.test.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { ContextEnvironmentImpl } from './environmentImpl.js';
+import { ContextTracer } from '../tracer.js';
+import { ContextEventBus } from '../eventBus.js';
+import { createMockLlmClient } from '../testing/contextTestUtils.js';
+
+describe('ContextEnvironmentImpl', () => {
+  it('should initialize with defaults correctly', () => {
+    const tracer = new ContextTracer({ targetDir: '/tmp', sessionId: 'mock' });
+    const eventBus = new ContextEventBus();
+    const mockLlmClient = createMockLlmClient();
+
+    const env = new ContextEnvironmentImpl(
+      mockLlmClient,
+      'mock-session',
+      'mock-prompt',
+      '/tmp/trace',
+      '/tmp/temp',
+      tracer,
+      4,
+      eventBus,
+    );
+
+    expect(env.llmClient).toBe(mockLlmClient);
+    expect(env.sessionId).toBe('mock-session');
+    expect(env.promptId).toBe('mock-prompt');
+    expect(env.traceDir).toBe('/tmp/trace');
+    expect(env.projectTempDir).toBe('/tmp/temp');
+    expect(env.tracer).toBe(tracer);
+    expect(env.charsPerToken).toBe(4);
+    expect(env.eventBus).toBe(eventBus);
+
+    // Default internals
+    expect(env.behaviorRegistry).toBeDefined();
+    expect(env.tokenCalculator).toBeDefined();
+    expect(env.inbox).toBeDefined();
+    expect(env.graphMapper).toBeDefined();
+  });
+});

packages/core/src/context/pipeline/environmentImpl.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { ContextTracer } from '../tracer.js';
+import type { ContextEnvironment } from './environment.js';
+import type { ContextEventBus } from '../eventBus.js';
+import { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import { LiveInbox } from './inbox.js';
+import { NodeBehaviorRegistry } from '../graph/behaviorRegistry.js';
+import { registerBuiltInBehaviors } from '../graph/builtinBehaviors.js';
+import { ContextGraphMapper } from '../graph/mapper.js';
+
+export class ContextEnvironmentImpl implements ContextEnvironment {
+  readonly tokenCalculator: ContextTokenCalculator;
+  readonly inbox: LiveInbox;
+  readonly behaviorRegistry: NodeBehaviorRegistry;
+  readonly graphMapper: ContextGraphMapper;
+
+  constructor(
+    readonly llmClient: BaseLlmClient,
+    readonly sessionId: string,
+    readonly promptId: string,
+    readonly traceDir: string,
+    readonly projectTempDir: string,
+    readonly tracer: ContextTracer,
+    readonly charsPerToken: number,
+    readonly eventBus: ContextEventBus,
+  ) {
+    this.behaviorRegistry = new NodeBehaviorRegistry();
+    registerBuiltInBehaviors(this.behaviorRegistry);
+    this.tokenCalculator = new ContextTokenCalculator(
+      this.charsPerToken,
+      this.behaviorRegistry,
+    );
+    this.inbox = new LiveInbox();
+    this.graphMapper = new ContextGraphMapper(this.behaviorRegistry);
+  }
+}

packages/core/src/context/pipeline/inbox.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { LiveInbox, InboxSnapshotImpl } from './inbox.js';
+
+describe('Inbox', () => {
+  it('should publish messages and provide snapshots', () => {
+    const inbox = new LiveInbox();
+
+    inbox.publish('test-topic', { data: 'hello' });
+    inbox.publish('other-topic', { data: 'world' });
+
+    const messages = inbox.getMessages();
+    expect(messages.length).toBe(2);
+    expect(messages[0].topic).toBe('test-topic');
+    expect(messages[0].payload).toEqual({ data: 'hello' });
+  });
+
+  it('should drain consumed messages from the snapshot', () => {
+    const inbox = new LiveInbox();
+
+    inbox.publish('test-topic', { data: 'hello' });
+    inbox.publish('other-topic', { data: 'world' });
+
+    const messages = inbox.getMessages();
+    const snapshot = new InboxSnapshotImpl(messages);
+
+    const filtered = snapshot.getMessages<{ data: string }>('test-topic');
+    expect(filtered.length).toBe(1);
+    expect(filtered[0].payload.data).toBe('hello');
+
+    // Consume the message
+    snapshot.consume(filtered[0].id);
+
+    // Provide the consumed IDs to the real inbox to drain them
+    inbox.drainConsumed(snapshot.getConsumedIds());
+
+    const finalMessages = inbox.getMessages();
+    expect(finalMessages.length).toBe(1);
+    expect(finalMessages[0].topic).toBe('other-topic');
+  });
+});

packages/core/src/context/pipeline/inbox.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { InboxMessage, InboxSnapshot } from '../pipeline.js';
+
+export class LiveInbox {
+  private messages: InboxMessage[] = [];
+
+  publish<T>(topic: string, payload: T): void {
+    this.messages.push({
+      id: randomUUID(),
+      topic,
+      payload,
+      timestamp: Date.now(),
+    });
+  }
+
+  getMessages(): readonly InboxMessage[] {
+    return [...this.messages];
+  }
+
+  drainConsumed(consumedIds: Set<string>): void {
+    this.messages = this.messages.filter((m) => !consumedIds.has(m.id));
+  }
+}
+
+export class InboxSnapshotImpl implements InboxSnapshot {
+  private messages: readonly InboxMessage[];
+  private consumedIds = new Set<string>();
+
+  constructor(messages: readonly InboxMessage[]) {
+    this.messages = messages;
+  }
+
+  getMessages<T = unknown>(topic: string): ReadonlyArray<InboxMessage<T>> {
+    const raw = this.messages.filter((m) => m.topic === topic);
+    /*
+     * Architectural Justification for Unchecked Cast:
+     * The Inbox is a heterogeneous event bus designed to support arbitrary, declarative
+     * routing via configuration files (where topics are just strings). Because TypeScript
+     * completely erases generic type information (<T>) at runtime, the central array
+     * can only hold `unknown` payloads. To enforce strict type safety without a central
+     * registry (which would break decoupling) or heavy runtime validation (Zod schemas),
+     * we must assert the type boundary here. The contract relies on the async pipeline and Processor
+     * agreeing on the payload structure associated with the configured topic string.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return raw as ReadonlyArray<InboxMessage<T>>;
+  }
+
+  consume(messageId: string): void {
+    this.consumedIds.add(messageId);
+  }
+
+  getConsumedIds(): Set<string> {
+    return this.consumedIds;
+  }
+}

packages/core/src/context/pipeline/orchestrator.test.ts

@@ -0,0 +1,224 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { PipelineOrchestrator } from './orchestrator.js';
+import {
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+import type { ContextEnvironment } from './environment.js';
+import type {
+  ContextProcessor,
+  AsyncContextProcessor,
+  ProcessArgs,
+} from '../pipeline.js';
+import type { PipelineDef, AsyncPipelineDef } from '../config/types.js';
+import type { ContextEventBus } from '../eventBus.js';
+import type { ConcreteNode, UserPrompt } from '../graph/types.js';
+
+// A realistic mock processor that modifies the text of the first target node
+function createModifyingProcessor(id: string): ContextProcessor {
+  return {
+    id,
+    name: 'ModifyingProcessor',
+    process: async (args: ProcessArgs) => {
+      const newTargets = [...args.targets];
+      if (newTargets.length > 0 && newTargets[0].type === 'USER_PROMPT') {
+        const prompt = newTargets[0];
+        const newParts = [...prompt.semanticParts];
+        if (newParts.length > 0 && newParts[0].type === 'text') {
+          newParts[0] = {
+            ...newParts[0],
+            text: newParts[0].text + ' [modified]',
+          };
+        }
+        newTargets[0] = {
+          ...prompt,
+          id: prompt.id + '-modified',
+          replacesId: prompt.id,
+          semanticParts: newParts,
+        };
+      }
+      return newTargets;
+    },
+  };
+}
+
+// A processor that just throws an error
+function createThrowingProcessor(id: string): ContextProcessor {
+  return {
+    id,
+    name: 'Throwing',
+    process: async (): Promise<readonly ConcreteNode[]> => {
+      throw new Error('Processor failed intentionally');
+    },
+  };
+}
+
+// A mock async processor that signals it ran
+function createMockAsyncProcessor(
+  id: string,
+  executeSpy: ReturnType<typeof vi.fn>,
+): AsyncContextProcessor {
+  return {
+    id,
+    name: 'MockAsyncProcessor',
+    process: async (args: ProcessArgs) => {
+      executeSpy(args);
+    },
+  };
+}
+
+describe('PipelineOrchestrator (Component)', () => {
+  let env: ContextEnvironment;
+  let eventBus: ContextEventBus;
+
+  beforeEach(() => {
+    env = createMockEnvironment();
+    eventBus = env.eventBus;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const setupOrchestrator = (
+    pipelines: PipelineDef[],
+    asyncPipelines: AsyncPipelineDef[] = [],
+  ) => {
+    const orchestrator = new PipelineOrchestrator(
+      pipelines,
+      asyncPipelines,
+      env,
+      eventBus,
+      env.tracer,
+    );
+    return orchestrator;
+  };
+
+  describe('Synchronous Pipeline Execution', () => {
+    it('applies processors in sequence on matching trigger', async () => {
+      const pipelines: PipelineDef[] = [
+        {
+          name: 'TestPipeline',
+          triggers: ['new_message'],
+          processors: [createModifyingProcessor('Mod')],
+        },
+      ];
+
+      const orchestrator = setupOrchestrator(pipelines);
+      const originalNode = createDummyNode('ep1', 'USER_PROMPT', 50, {
+        semanticParts: [{ type: 'text', text: 'Original' }],
+      });
+
+      const processed = await orchestrator.executeTriggerSync(
+        'new_message',
+        [originalNode],
+        new Set([originalNode.id]),
+        new Set(),
+      );
+
+      expect(processed.length).toBe(1);
+      const resultingNode = processed[0] as UserPrompt;
+      assert(resultingNode.semanticParts[0].type === 'text');
+      expect(resultingNode.semanticParts[0].text).toBe('Original [modified]');
+      expect(resultingNode.replacesId).toBe(originalNode.id);
+    });
+
+    it('bypasses pipelines that do not match the trigger', async () => {
+      const pipelines: PipelineDef[] = [
+        {
+          name: 'TestPipeline',
+          triggers: ['gc_backstop'], // Different trigger
+          processors: [createModifyingProcessor('Mod')],
+        },
+      ];
+
+      const orchestrator = setupOrchestrator(pipelines);
+      const originalNode = createDummyNode('ep1', 'USER_PROMPT', 50, {
+        semanticParts: [{ type: 'text', text: 'Original' }],
+      });
+
+      const processed = await orchestrator.executeTriggerSync(
+        'new_message',
+        [originalNode],
+        new Set([originalNode.id]),
+        new Set(),
+      );
+
+      expect(processed).toEqual([originalNode]); // Untouched
+    });
+
+    it('gracefully handles a failing processor without crashing the pipeline', async () => {
+      const pipelines: PipelineDef[] = [
+        {
+          name: 'FailingPipeline',
+          triggers: ['new_message'],
+          processors: [
+            createThrowingProcessor('Thrower'),
+            createModifyingProcessor('Mod'),
+          ],
+        },
+      ];
+
+      const orchestrator = setupOrchestrator(pipelines);
+      const originalNode = createDummyNode('ep1', 'USER_PROMPT', 50, {
+        semanticParts: [{ type: 'text', text: 'Original' }],
+      });
+
+      // The throwing processor should be caught and logged, allowing Mod to still run.
+      const processed = await orchestrator.executeTriggerSync(
+        'new_message',
+        [originalNode],
+        new Set([originalNode.id]),
+        new Set(),
+      );
+
+      expect(processed.length).toBe(1);
+      const resultingNode = processed[0] as UserPrompt;
+      assert(resultingNode.semanticParts[0].type === 'text');
+      expect(resultingNode.semanticParts[0].text).toBe('Original [modified]');
+    });
+  });
+
+  describe('Asynchronous async pipeline Events', () => {
+    it('routes emitChunkReceived to async pipelines with nodes_added trigger', async () => {
+      const executeSpy = vi.fn();
+      const asyncProcessor = createMockAsyncProcessor(
+        'MyAsyncProcessor',
+        executeSpy,
+      );
+
+      setupOrchestrator(
+        [],
+        [
+          {
+            name: 'TestAsync',
+            triggers: ['nodes_added'],
+            processors: [asyncProcessor],
+          },
+        ],
+      );
+
+      const node1 = createDummyNode('ep1', 'USER_PROMPT', 10);
+      const node2 = createDummyNode('ep1', 'AGENT_THOUGHT', 20);
+
+      eventBus.emitChunkReceived({
+        nodes: [node1, node2],
+        targetNodeIds: new Set([node2.id]),
+      });
+
+      // Yield event loop
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(executeSpy).toHaveBeenCalledTimes(1);
+      const callArgs = executeSpy.mock.calls[0][0];
+      expect(callArgs.targets).toEqual([node2]); // AsyncProcessors only get the target nodes
+    });
+  });
+});

packages/core/src/context/pipeline/orchestrator.ts

@@ -0,0 +1,218 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ConcreteNode } from '../graph/types.js';
+import type {
+  AsyncPipelineDef,
+  PipelineDef,
+  PipelineTrigger,
+} from '../config/types.js';
+import type {
+  ContextEnvironment,
+  ContextEventBus,
+  ContextTracer,
+} from './environment.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { InboxSnapshotImpl } from './inbox.js';
+import { ContextWorkingBufferImpl } from './contextWorkingBuffer.js';
+
+export class PipelineOrchestrator {
+  private activeTimers: NodeJS.Timeout[] = [];
+
+  constructor(
+    private readonly pipelines: PipelineDef[],
+    private readonly asyncPipelines: AsyncPipelineDef[],
+    private readonly env: ContextEnvironment,
+    private readonly eventBus: ContextEventBus,
+    private readonly tracer: ContextTracer,
+  ) {
+    this.setupTriggers();
+  }
+
+  private isNodeAllowed(
+    node: ConcreteNode,
+    triggerTargets: ReadonlySet<string>,
+    protectedLogicalIds: ReadonlySet<string> = new Set(),
+  ): boolean {
+    return (
+      triggerTargets.has(node.id) &&
+      !protectedLogicalIds.has(node.id) &&
+      (!node.logicalParentId || !protectedLogicalIds.has(node.logicalParentId))
+    );
+  }
+
+  private setupTriggers() {
+    const bindTriggers = <P extends PipelineDef | AsyncPipelineDef>(
+      pipelines: P[],
+      executeFn: (
+        pipeline: P,
+        nodes: readonly ConcreteNode[],
+        targets: ReadonlySet<string>,
+        protectedIds: ReadonlySet<string>,
+      ) => void,
+    ) => {
+      for (const pipeline of pipelines) {
+        for (const trigger of pipeline.triggers) {
+          if (typeof trigger === 'object' && trigger.type === 'timer') {
+            const timer = setInterval(() => {
+              // Background timers not fully implemented in V1 yet
+            }, trigger.intervalMs);
+            this.activeTimers.push(timer);
+          } else if (
+            trigger === 'retained_exceeded' ||
+            trigger === 'nodes_aged_out'
+          ) {
+            this.eventBus.onConsolidationNeeded((event) => {
+              executeFn(pipeline, event.nodes, event.targetNodeIds, new Set());
+            });
+          } else if (trigger === 'new_message' || trigger === 'nodes_added') {
+            this.eventBus.onChunkReceived((event) => {
+              executeFn(pipeline, event.nodes, event.targetNodeIds, new Set());
+            });
+          }
+        }
+      }
+    };
+
+    bindTriggers(this.pipelines, (pipeline, nodes, targets, protectedIds) => {
+      void this.executePipelineAsync(
+        pipeline,
+        nodes,
+        new Set(targets),
+        new Set(protectedIds),
+      );
+    });
+
+    bindTriggers(this.asyncPipelines, (pipeline, nodes, targetIds) => {
+      const inboxSnapshot = new InboxSnapshotImpl(
+        this.env.inbox.getMessages() || [],
+      );
+      const targets = nodes.filter((n) => targetIds.has(n.id));
+      for (const processor of pipeline.processors) {
+        processor
+          .process({
+            targets,
+            inbox: inboxSnapshot,
+            buffer: ContextWorkingBufferImpl.initialize(nodes),
+          })
+          .catch((e: unknown) =>
+            debugLogger.error(`AsyncProcessor ${processor.name} failed:`, e),
+          );
+      }
+    });
+  }
+
+  shutdown() {
+    for (const timer of this.activeTimers) {
+      clearInterval(timer);
+    }
+  }
+
+  async executeTriggerSync(
+    trigger: PipelineTrigger,
+    nodes: readonly ConcreteNode[],
+    triggerTargets: ReadonlySet<string>,
+    protectedLogicalIds: ReadonlySet<string> = new Set(),
+  ): Promise<readonly ConcreteNode[]> {
+    let currentBuffer = ContextWorkingBufferImpl.initialize(nodes);
+    const triggerPipelines = this.pipelines.filter((p) =>
+      p.triggers.includes(trigger),
+    );
+
+    // Freeze the inbox for this pipeline run
+    const inboxSnapshot = new InboxSnapshotImpl(
+      this.env.inbox.getMessages() || [],
+    );
+
+    for (const pipeline of triggerPipelines) {
+      for (const processor of pipeline.processors) {
+        try {
+          this.tracer.logEvent(
+            'Orchestrator',
+            `Executing processor synchronously: ${processor.id}`,
+          );
+
+          const allowedTargets = currentBuffer.nodes.filter((n) =>
+            this.isNodeAllowed(n, triggerTargets, protectedLogicalIds),
+          );
+
+          const returnedNodes = await processor.process({
+            buffer: currentBuffer,
+            targets: allowedTargets,
+            inbox: inboxSnapshot,
+          });
+
+          currentBuffer = currentBuffer.applyProcessorResult(
+            processor.id,
+            allowedTargets,
+            returnedNodes,
+          );
+        } catch (error) {
+          debugLogger.error(
+            `Synchronous processor ${processor.id} failed:`,
+            error,
+          );
+        }
+      }
+    }
+
+    // Success! Drain consumed messages
+    this.env.inbox.drainConsumed(inboxSnapshot.getConsumedIds());
+
+    return currentBuffer.nodes;
+  }
+
+  private async executePipelineAsync(
+    pipeline: PipelineDef,
+    nodes: readonly ConcreteNode[],
+    triggerTargets: Set<string>,
+    protectedLogicalIds: ReadonlySet<string> = new Set(),
+  ) {
+    this.tracer.logEvent(
+      'Orchestrator',
+      `Triggering async pipeline: ${pipeline.name}`,
+    );
+    if (!nodes || nodes.length === 0) return;
+
+    let currentBuffer = ContextWorkingBufferImpl.initialize(nodes);
+    const inboxSnapshot = new InboxSnapshotImpl(
+      this.env.inbox.getMessages() || [],
+    );
+
+    for (const processor of pipeline.processors) {
+      try {
+        this.tracer.logEvent(
+          'Orchestrator',
+          `Executing processor: ${processor.id} (async)`,
+        );
+
+        const allowedTargets = currentBuffer.nodes.filter((n) =>
+          this.isNodeAllowed(n, triggerTargets, protectedLogicalIds),
+        );
+
+        const returnedNodes = await processor.process({
+          buffer: currentBuffer,
+          targets: allowedTargets,
+          inbox: inboxSnapshot,
+        });
+
+        currentBuffer = currentBuffer.applyProcessorResult(
+          processor.id,
+          allowedTargets,
+          returnedNodes,
+        );
+      } catch (error) {
+        debugLogger.error(
+          `Pipeline ${pipeline.name} failed async at ${processor.id}:`,
+          error,
+        );
+        return;
+      }
+    }
+
+    this.env.inbox.drainConsumed(inboxSnapshot.getConsumedIds());
+  }
+}

packages/core/src/context/processors/blobDegradationProcessor.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createBlobDegradationProcessor } from './blobDegradationProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+import type { UserPrompt, SemanticPart, ConcreteNode } from '../graph/types.js';
+
+describe('BlobDegradationProcessor', () => {
+  it('should ignore text parts and only target inline_data and file_data', async () => {
+    const env = createMockEnvironment();
+    // charsPerToken = 1
+    // We want the degraded text to be cheaper than the original blob.
+    // Degraded text is ~100 chars ("...degraded to text...").
+    // So we make the blob data 200 chars.
+    const fakeData = 'A'.repeat(200);
+
+    const processor = createBlobDegradationProcessor(
+      'BlobDegradationProcessor',
+      env,
+    );
+
+    const parts: SemanticPart[] = [
+      { type: 'text', text: 'Hello' },
+      { type: 'inline_data', mimeType: 'image/png', data: fakeData },
+      { type: 'text', text: 'World' },
+    ];
+
+    const prompt = createDummyNode('ep1', 'USER_PROMPT', 100, {
+      semanticParts: parts,
+    }) as UserPrompt;
+
+    const targets = [prompt];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(1);
+    const modifiedPrompt = result[0] as UserPrompt;
+
+    expect(modifiedPrompt.id).not.toBe(prompt.id);
+    expect(modifiedPrompt.semanticParts.length).toBe(3);
+
+    // Text parts should be untouched
+    expect(modifiedPrompt.semanticParts[0]).toEqual(parts[0]);
+    expect(modifiedPrompt.semanticParts[2]).toEqual(parts[2]);
+
+    // The inline_data part should be replaced with text
+    const degradedPart = modifiedPrompt.semanticParts[1];
+    expect(degradedPart.type).toBe('text');
+    assert(degradedPart.type === 'text');
+    expect(degradedPart.text).toContain(
+      '[Multi-Modal Blob (image/png, 0.00MB) degraded to text',
+    );
+  });
+
+  it('should degrade all blobs unconditionally', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createBlobDegradationProcessor(
+      'BlobDegradationProcessor',
+      env,
+    );
+
+    // Tokens for fileData = 258.
+    // Degraded text = "[File Reference (video/mp4) degraded to text to preserve context window. Original URI: gs://test1]"
+    // Degraded text length ~100 characters.
+    // Since charsPerToken=1, degraded text = 100 tokens.
+    // Tokens saved = 258 - 100 = 158. This is > 0, so it WILL degrade it!
+
+    const prompt = createDummyNode('ep1', 'USER_PROMPT', 100, {
+      semanticParts: [
+        { type: 'file_data', mimeType: 'video/mp4', fileUri: 'gs://test1' },
+        { type: 'file_data', mimeType: 'video/mp4', fileUri: 'gs://test2' },
+      ],
+    }) as UserPrompt;
+
+    const targets = [prompt];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    const modifiedPrompt = result[0] as UserPrompt;
+    expect(modifiedPrompt.semanticParts.length).toBe(2);
+
+    // Both parts should be degraded
+    expect(modifiedPrompt.semanticParts[0].type).toBe('text');
+    expect(modifiedPrompt.semanticParts[1].type).toBe('text');
+  });
+
+  it('should return exactly the targets array if targets are empty', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createBlobDegradationProcessor(
+      'BlobDegradationProcessor',
+      env,
+    );
+    const targets: ConcreteNode[] = [];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result).toBe(targets);
+  });
+});

packages/core/src/context/processors/blobDegradationProcessor.ts

@@ -0,0 +1,153 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type { ProcessArgs, ContextProcessor } from '../pipeline.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { ConcreteNode, UserPrompt } from '../graph/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { sanitizeFilenamePart } from '../../utils/fileUtils.js';
+
+export type BlobDegradationProcessorOptions = Record<string, never>;
+
+export const BlobDegradationProcessorOptionsSchema: JSONSchemaType<BlobDegradationProcessorOptions> =
+  {
+    type: 'object',
+    properties: {},
+    required: [],
+  };
+
+export function createBlobDegradationProcessor(
+  id: string,
+  env: ContextEnvironment,
+): ContextProcessor {
+  return {
+    id,
+    name: 'BlobDegradationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      if (targets.length === 0) {
+        return targets;
+      }
+
+      let directoryCreated = false;
+
+      let blobOutputsDir = path.join(env.projectTempDir, 'degraded-blobs');
+      const sessionId = env.sessionId;
+      if (sessionId) {
+        blobOutputsDir = path.join(
+          blobOutputsDir,
+          `session-${sanitizeFilenamePart(sessionId)}`,
+        );
+      }
+
+      const ensureDir = async () => {
+        if (!directoryCreated) {
+          await fs.mkdir(blobOutputsDir, { recursive: true });
+          directoryCreated = true;
+        }
+      };
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      // Forward scan, looking for bloated non-text parts to degrade
+      for (const node of targets) {
+        switch (node.type) {
+          case 'USER_PROMPT': {
+            let modified = false;
+            const newParts = [...node.semanticParts];
+
+            for (let j = 0; j < node.semanticParts.length; j++) {
+              const part = node.semanticParts[j];
+              if (part.type === 'text') continue;
+
+              let newText = '';
+              let tokensSaved = 0;
+
+              switch (part.type) {
+                case 'inline_data': {
+                  await ensureDir();
+                  const ext = part.mimeType.split('/')[1] || 'bin';
+                  const fileName = `blob_${Date.now()}_${randomUUID()}.${ext}`;
+                  const filePath = path.join(blobOutputsDir, fileName);
+
+                  const buffer = Buffer.from(part.data, 'base64');
+                  await fs.writeFile(filePath, buffer);
+
+                  const mb = (buffer.byteLength / 1024 / 1024).toFixed(2);
+                  newText = `[Multi-Modal Blob (${part.mimeType}, ${mb}MB) degraded to text to preserve context window. Saved to: ${filePath}]`;
+
+                  const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                    {
+                      inlineData: { mimeType: part.mimeType, data: part.data },
+                    },
+                  ]);
+                  const newTokens = env.tokenCalculator.estimateTokensForParts([
+                    { text: newText },
+                  ]);
+                  tokensSaved = oldTokens - newTokens;
+                  break;
+                }
+                case 'file_data': {
+                  newText = `[File Reference (${part.mimeType}) degraded to text to preserve context window. Original URI: ${part.fileUri}]`;
+                  const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                    {
+                      fileData: {
+                        mimeType: part.mimeType,
+                        fileUri: part.fileUri,
+                      },
+                    },
+                  ]);
+                  const newTokens = env.tokenCalculator.estimateTokensForParts([
+                    { text: newText },
+                  ]);
+                  tokensSaved = oldTokens - newTokens;
+                  break;
+                }
+                case 'raw_part': {
+                  newText = `[Unknown Part degraded to text to preserve context window.]`;
+                  const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                    part.part,
+                  ]);
+                  const newTokens = env.tokenCalculator.estimateTokensForParts([
+                    { text: newText },
+                  ]);
+                  tokensSaved = oldTokens - newTokens;
+                  break;
+                }
+                default:
+                  break;
+              }
+
+              if (newText && tokensSaved > 0) {
+                newParts[j] = { type: 'text', text: newText };
+                modified = true;
+              }
+            }
+
+            if (modified) {
+              const degradedNode: UserPrompt = {
+                ...node,
+                id: randomUUID(),
+                semanticParts: newParts,
+                replacesId: node.id,
+              };
+              returnedNodes.push(degradedNode);
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/processors/historyTruncationProcessor.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  ContextProcessor,
+  BackstopTargetOptions,
+  ProcessArgs,
+} from '../pipeline.js';
+import type { ConcreteNode } from '../graph/types.js';
+import type { JSONSchemaType } from 'ajv';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+
+export type HistoryTruncationProcessorOptions = BackstopTargetOptions;
+
+export const HistoryTruncationProcessorOptionsSchema: JSONSchemaType<HistoryTruncationProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      target: {
+        type: 'string',
+        enum: ['incremental', 'freeNTokens', 'max'],
+        nullable: true,
+      },
+      freeTokensTarget: { type: 'number', nullable: true },
+    },
+    required: [],
+  };
+
+export function createHistoryTruncationProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: HistoryTruncationProcessorOptions,
+): ContextProcessor {
+  return {
+    id,
+    name: 'HistoryTruncationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      const strategy = options.target ?? 'max';
+      const keptNodes: ConcreteNode[] = [];
+
+      if (strategy === 'incremental') {
+        // 'incremental' simply drops the single oldest node in the targets, ignoring tokens.
+        let removedNodes = 0;
+        for (const node of targets) {
+          if (removedNodes < 1) {
+            removedNodes++;
+            continue;
+          }
+          keptNodes.push(node);
+        }
+        return keptNodes;
+      }
+
+      let targetTokensToRemove = 0;
+      if (strategy === 'freeNTokens') {
+        targetTokensToRemove = options.freeTokensTarget ?? 0;
+        if (targetTokensToRemove <= 0) return targets;
+      } else if (strategy === 'max') {
+        // 'max' means we remove all targets without stopping early
+        targetTokensToRemove = Infinity;
+      }
+
+      let removedTokens = 0;
+
+      // The targets are sequentially ordered from oldest to newest.
+      // We want to delete the oldest targets first.
+      for (const node of targets) {
+        if (removedTokens >= targetTokensToRemove) {
+          keptNodes.push(node);
+          continue;
+        }
+
+        removedTokens += env.tokenCalculator.getTokenCost(node);
+      }
+
+      return keptNodes;
+    },
+  };
+}

packages/core/src/context/processors/nodeDistillationProcessor.test.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createNodeDistillationProcessor } from './nodeDistillationProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+  createDummyToolNode,
+  createMockLlmClient,
+} from '../testing/contextTestUtils.js';
+import type {
+  UserPrompt,
+  AgentThought,
+  ToolExecution,
+} from '../graph/types.js';
+
+describe('NodeDistillationProcessor', () => {
+  it('should trigger summarization via LLM for long text parts', async () => {
+    const mockLlmClient = createMockLlmClient(['Mocked Summary!']);
+
+    // Use charsPerToken=1 naturally.
+    const env = createMockEnvironment({
+      llmClient: mockLlmClient,
+    });
+
+    const processor = createNodeDistillationProcessor(
+      'NodeDistillationProcessor',
+      env,
+      {
+        nodeThresholdTokens: 10,
+      },
+    );
+
+    const longText = 'A'.repeat(50); // 50 chars
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      50,
+      {
+        semanticParts: [{ type: 'text', text: longText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      50,
+      {
+        text: longText,
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const tool = createDummyToolNode(
+      'ep1',
+      5,
+      500,
+      {
+        observation: { result: 'A'.repeat(500) },
+      },
+      'tool-id',
+    );
+
+    const targets = [prompt, thought, tool];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(3);
+
+    // 1. User Prompt
+    const compressedPrompt = result[0] as UserPrompt;
+    expect(compressedPrompt.id).not.toBe(prompt.id);
+    expect(compressedPrompt.semanticParts[0].type).toBe('text');
+    assert(compressedPrompt.semanticParts[0].type === 'text');
+    expect(compressedPrompt.semanticParts[0].text).toBe('Mocked Summary!');
+
+    // 2. Agent Thought
+    const compressedThought = result[1] as AgentThought;
+    expect(compressedThought.id).not.toBe(thought.id);
+    expect(compressedThought.text).toBe('Mocked Summary!');
+
+    // 3. Tool Execution
+    const compressedTool = result[2] as ToolExecution;
+    expect(compressedTool.id).not.toBe(tool.id);
+    expect(compressedTool.observation).toEqual({ summary: 'Mocked Summary!' });
+
+    expect(mockLlmClient.generateContent).toHaveBeenCalledTimes(3);
+  });
+
+  it('should ignore nodes that are below the threshold', async () => {
+    const mockLlmClient = createMockLlmClient(['S']); // length = 1
+
+    const env = createMockEnvironment({
+      llmClient: mockLlmClient,
+    });
+
+    const processor = createNodeDistillationProcessor(
+      'NodeDistillationProcessor',
+      env,
+      {
+        nodeThresholdTokens: 100, // Very high threshold
+      },
+    );
+
+    const shortText = 'Short text'; // 10 chars
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      {
+        semanticParts: [{ type: 'text', text: shortText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      13,
+      {
+        text: 'Short thought',
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const targets = [prompt, thought];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(2);
+
+    // 1. User Prompt (NOT compressed)
+    const untouchedPrompt = result[0] as UserPrompt;
+    expect(untouchedPrompt.id).toBe(prompt.id);
+
+    // 2. Agent Thought (NOT compressed)
+    const untouchedThought = result[1] as AgentThought;
+    expect(untouchedThought.id).toBe(thought.id);
+
+    // LLM should not have been called
+    expect(mockLlmClient.generateContent).toHaveBeenCalledTimes(0);
+  });
+});

packages/core/src/context/processors/nodeDistillationProcessor.ts

@@ -0,0 +1,203 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type { ContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ConcreteNode } from '../graph/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { getResponseText } from '../../utils/partUtils.js';
+import { LlmRole } from '../../telemetry/llmRole.js';
+
+export interface NodeDistillationProcessorOptions {
+  nodeThresholdTokens: number;
+}
+
+export const NodeDistillationProcessorOptionsSchema: JSONSchemaType<NodeDistillationProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      nodeThresholdTokens: { type: 'number' },
+    },
+    required: ['nodeThresholdTokens'],
+  };
+
+export function createNodeDistillationProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: NodeDistillationProcessorOptions,
+): ContextProcessor {
+  const generateSummary = async (
+    text: string,
+    contextInfo: string,
+  ): Promise<string> => {
+    try {
+      const response = await env.llmClient.generateContent({
+        role: LlmRole.UTILITY_COMPRESSOR,
+        modelConfigKey: { model: 'gemini-3-flash-base' },
+        promptId: env.promptId,
+        abortSignal: new AbortController().signal,
+        contents: [
+          {
+            role: 'user',
+            parts: [{ text }],
+          },
+        ],
+        systemInstruction: {
+          role: 'system',
+          parts: [
+            {
+              text: `You are an expert context compressor. Your job is to drastically shorten the following ${contextInfo} while preserving the absolute core semantic meaning, facts, and intent. Omit all conversational filler, pleasantries, or redundant information. Return ONLY the compressed summary.`,
+            },
+          ],
+        },
+      });
+      return getResponseText(response) || text;
+    } catch (e) {
+      debugLogger.warn(
+        `NodeDistillationProcessor failed to summarize ${contextInfo}`,
+        e,
+      );
+      return text; // Fallback to original text on API failure
+    }
+  };
+
+  return {
+    id,
+    name: 'NodeDistillationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      const semanticConfig = options;
+      const limitTokens = semanticConfig.nodeThresholdTokens;
+      const thresholdChars = env.tokenCalculator.tokensToChars(limitTokens);
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      // Scan the target working buffer and unconditionally apply the configured hyperparameter threshold
+      for (const node of targets) {
+        switch (node.type) {
+          case 'USER_PROMPT': {
+            let modified = false;
+            const newParts = [...node.semanticParts];
+
+            for (let j = 0; j < node.semanticParts.length; j++) {
+              const part = node.semanticParts[j];
+              if (part.type !== 'text') continue;
+
+              if (part.text.length > thresholdChars) {
+                const summary = await generateSummary(part.text, 'User Prompt');
+                const newTokens = env.tokenCalculator.estimateTokensForParts([
+                  { text: summary },
+                ]);
+                const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                  { text: part.text },
+                ]);
+
+                if (newTokens < oldTokens) {
+                  newParts[j] = { type: 'text', text: summary };
+                  modified = true;
+                }
+              }
+            }
+
+            if (modified) {
+              returnedNodes.push({
+                ...node,
+                id: randomUUID(),
+                semanticParts: newParts,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          case 'AGENT_THOUGHT': {
+            if (node.text.length > thresholdChars) {
+              const summary = await generateSummary(node.text, 'Agent Thought');
+              const newTokens = env.tokenCalculator.estimateTokensForParts([
+                { text: summary },
+              ]);
+              const oldTokens = env.tokenCalculator.getTokenCost(node);
+
+              if (newTokens < oldTokens) {
+                returnedNodes.push({
+                  ...node,
+                  id: randomUUID(),
+                  text: summary,
+                  replacesId: node.id,
+                });
+                break;
+              }
+            }
+            returnedNodes.push(node);
+            break;
+          }
+
+          case 'TOOL_EXECUTION': {
+            const rawObs = node.observation;
+
+            let stringifiedObs = '';
+            if (typeof rawObs === 'string') {
+              stringifiedObs = rawObs;
+            } else {
+              try {
+                stringifiedObs = JSON.stringify(rawObs);
+              } catch {
+                stringifiedObs = String(rawObs);
+              }
+            }
+
+            if (stringifiedObs.length > thresholdChars) {
+              const summary = await generateSummary(
+                stringifiedObs,
+                node.toolName || 'unknown',
+              );
+              const newObsObject = { summary };
+
+              const newObsTokens = env.tokenCalculator.estimateTokensForParts([
+                {
+                  functionResponse: {
+                    name: node.toolName || 'unknown',
+                    response: newObsObject,
+                    id: node.id,
+                  },
+                },
+              ]);
+
+              const oldObsTokens =
+                node.tokens?.observation ??
+                env.tokenCalculator.getTokenCost(node);
+              const intentTokens = node.tokens?.intent ?? 0;
+
+              if (newObsTokens < oldObsTokens) {
+                returnedNodes.push({
+                  ...node,
+                  id: randomUUID(),
+                  observation: newObsObject,
+                  tokens: {
+                    intent: intentTokens,
+                    observation: newObsTokens,
+                  },
+                  replacesId: node.id,
+                });
+                break;
+              }
+            }
+            returnedNodes.push(node);
+            break;
+          }
+
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/processors/nodeTruncationProcessor.test.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createNodeTruncationProcessor } from './nodeTruncationProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+import type { UserPrompt, AgentThought, AgentYield } from '../graph/types.js';
+
+describe('NodeTruncationProcessor', () => {
+  it('should truncate nodes that exceed maxTokensPerNode', async () => {
+    // env.tokenCalculator uses charsPerToken=1 natively.
+    const env = createMockEnvironment();
+
+    const processor = createNodeTruncationProcessor(
+      'NodeTruncationProcessor',
+      env,
+      {
+        maxTokensPerNode: 10, // 10 chars limit
+      },
+    );
+
+    const longText = 'A'.repeat(50); // 50 tokens
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      50,
+      {
+        semanticParts: [{ type: 'text', text: longText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      50,
+      {
+        text: longText,
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const yieldNode = createDummyNode(
+      'ep1',
+      'AGENT_YIELD',
+      50,
+      {
+        text: longText,
+      },
+      'yield-id',
+    ) as AgentYield;
+
+    const targets = [prompt, thought, yieldNode];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(3);
+
+    // 1. User Prompt
+    const squashedPrompt = result[0] as UserPrompt;
+    expect(squashedPrompt.id).not.toBe(prompt.id);
+    expect(squashedPrompt.semanticParts[0].type).toBe('text');
+    assert(squashedPrompt.semanticParts[0].type === 'text');
+    expect(squashedPrompt.semanticParts[0].text).toContain('[... OMITTED');
+
+    // 2. Agent Thought
+    const squashedThought = result[1] as AgentThought;
+    expect(squashedThought.id).not.toBe(thought.id);
+    expect(squashedThought.text).toContain('[... OMITTED');
+
+    // 3. Agent Yield
+    const squashedYield = result[2] as AgentYield;
+    expect(squashedYield.id).not.toBe(yieldNode.id);
+    expect(squashedYield.text).toContain('[... OMITTED');
+  });
+
+  it('should ignore nodes that are below maxTokensPerNode', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createNodeTruncationProcessor(
+      'NodeTruncationProcessor',
+      env,
+      {
+        maxTokensPerNode: 100, // 100 chars limit
+      },
+    );
+
+    const shortText = 'Short text'; // 10 chars
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      {
+        semanticParts: [{ type: 'text', text: shortText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      13,
+      {
+        text: 'Short thought', // 13 chars
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const targets = [prompt, thought];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(2);
+
+    // 1. User Prompt (untouched)
+    const squashedPrompt = result[0] as UserPrompt;
+    expect(squashedPrompt.id).toBe(prompt.id);
+    assert(squashedPrompt.semanticParts[0].type === 'text');
+    expect(squashedPrompt.semanticParts[0].text).not.toContain('[... OMITTED');
+
+    // 2. Agent Thought (untouched)
+    const untouchedThought = result[1] as AgentThought;
+    expect(untouchedThought.id).toBe(thought.id);
+    expect(untouchedThought.text).not.toContain('[... OMITTED');
+  });
+});

packages/core/src/context/processors/nodeTruncationProcessor.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type { ContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { truncateProportionally } from '../truncation.js';
+import type { ConcreteNode } from '../graph/types.js';
+
+export interface NodeTruncationProcessorOptions {
+  maxTokensPerNode: number;
+}
+
+export const NodeTruncationProcessorOptionsSchema: JSONSchemaType<NodeTruncationProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      maxTokensPerNode: { type: 'number' },
+    },
+    required: ['maxTokensPerNode'],
+  };
+
+export function createNodeTruncationProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: NodeTruncationProcessorOptions,
+): ContextProcessor {
+  const tryApplySquash = (
+    text: string,
+    limitChars: number,
+  ): {
+    text: string;
+    newTokens: number;
+    oldTokens: number;
+    tokensSaved: number;
+  } | null => {
+    const originalLength = text.length;
+    if (originalLength <= limitChars) return null;
+
+    const newText = truncateProportionally(
+      text,
+      limitChars,
+      `\n\n[... OMITTED ${originalLength - limitChars} chars ...]\n\n`,
+    );
+
+    if (newText !== text) {
+      // Using accurate TokenCalculator instead of simple math
+      const newTokens = env.tokenCalculator.estimateTokensForString(newText);
+      const oldTokens = env.tokenCalculator.estimateTokensForString(text);
+      const tokensSaved = oldTokens - newTokens;
+
+      if (tokensSaved > 0) {
+        return { text: newText, newTokens, oldTokens, tokensSaved };
+      }
+    }
+    return null;
+  };
+
+  return {
+    id,
+    name: 'NodeTruncationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      if (targets.length === 0) {
+        return targets;
+      }
+
+      const { maxTokensPerNode } = options;
+      const limitChars = env.tokenCalculator.tokensToChars(maxTokensPerNode);
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      for (const node of targets) {
+        switch (node.type) {
+          case 'USER_PROMPT': {
+            let modified = false;
+            const newParts = [...node.semanticParts];
+
+            for (let j = 0; j < node.semanticParts.length; j++) {
+              const part = node.semanticParts[j];
+              if (part.type === 'text') {
+                const squashResult = tryApplySquash(part.text, limitChars);
+                if (squashResult) {
+                  newParts[j] = { type: 'text', text: squashResult.text };
+                  modified = true;
+                }
+              }
+            }
+
+            if (modified) {
+              returnedNodes.push({
+                ...node,
+                id: randomUUID(),
+                semanticParts: newParts,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          case 'AGENT_THOUGHT': {
+            const squashResult = tryApplySquash(node.text, limitChars);
+            if (squashResult) {
+              returnedNodes.push({
+                ...node,
+                id: randomUUID(),
+                text: squashResult.text,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          case 'AGENT_YIELD': {
+            const squashResult = tryApplySquash(node.text, limitChars);
+            if (squashResult) {
+              returnedNodes.push({
+                ...node,
+                id: randomUUID(),
+                text: squashResult.text,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/processors/rollingSummaryProcessor.test.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createRollingSummaryProcessor } from './rollingSummaryProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+
+describe('RollingSummaryProcessor', () => {
+  it('should initialize with correct default options', () => {
+    const env = createMockEnvironment();
+    const processor = createRollingSummaryProcessor(
+      'RollingSummaryProcessor',
+      env,
+      {
+        target: 'incremental',
+      },
+    );
+    expect(processor.id).toBe('RollingSummaryProcessor');
+  });
+
+  it('should summarize older nodes when the deficit exceeds the threshold', async () => {
+    // env.tokenCalculator uses charsPerToken=1 based on createMockEnvironment
+    const env = createMockEnvironment();
+
+    // We want to free exactly 100 tokens.
+    // We will supply nodes that cost 50 tokens each.
+    const processor = createRollingSummaryProcessor(
+      'RollingSummaryProcessor',
+      env,
+      {
+        target: 'freeNTokens',
+        freeTokensTarget: 100,
+      },
+    );
+
+    const text50 = 'A'.repeat(50);
+    const targets = [
+      createDummyNode(
+        'ep1',
+        'USER_PROMPT',
+        50,
+        { semanticParts: [{ type: 'text', text: text50 }] },
+        'id1',
+      ),
+      createDummyNode('ep1', 'AGENT_THOUGHT', 50, { text: text50 }, 'id2'),
+      createDummyNode('ep1', 'AGENT_YIELD', 50, { text: text50 }, 'id3'),
+    ];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    // 3 nodes at 50 cost each.
+    // The first node (id1) is the initial USER_PROMPT and is always skipped by RollingSummaryProcessor.
+    // Node id2 adds 50 deficit. Node id3 adds 50 deficit. Total = 100 deficit, which hits the target break point.
+    // Thus, id2 and id3 are summarized into a new ROLLING_SUMMARY node.
+    expect(result.length).toBe(2);
+    expect(result[0].type).toBe('USER_PROMPT');
+    expect(result[1].type).toBe('ROLLING_SUMMARY');
+  });
+
+  it('should preserve targets if deficit does not trigger summary', async () => {
+    const env = createMockEnvironment();
+
+    // We want to free 100 tokens, but our nodes will only cost 10 tokens each.
+    const processor = createRollingSummaryProcessor(
+      'RollingSummaryProcessor',
+      env,
+      {
+        target: 'freeNTokens',
+        freeTokensTarget: 100,
+      },
+    );
+
+    const text10 = 'A'.repeat(10);
+    const targets = [
+      createDummyNode(
+        'ep1',
+        'USER_PROMPT',
+        10,
+        { semanticParts: [{ type: 'text', text: text10 }] },
+        'id1',
+      ),
+      createDummyNode('ep1', 'AGENT_THOUGHT', 10, { text: text10 }, 'id2'),
+    ];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    // Deficit accumulator reaches 10. This is < 100 limit, and total summarizable nodes < 2 anyway.
+    expect(result.length).toBe(2);
+    expect(result[0].type).toBe('USER_PROMPT');
+    expect(result[1].type).toBe('AGENT_THOUGHT');
+  });
+});

packages/core/src/context/processors/rollingSummaryProcessor.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type {
+  ContextProcessor,
+  ProcessArgs,
+  BackstopTargetOptions,
+} from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode, RollingSummary } from '../graph/types.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { LlmRole } from '../../telemetry/llmRole.js';
+
+export interface RollingSummaryProcessorOptions extends BackstopTargetOptions {
+  systemInstruction?: string;
+}
+
+export const RollingSummaryProcessorOptionsSchema: JSONSchemaType<RollingSummaryProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      target: {
+        type: 'string',
+        enum: ['incremental', 'freeNTokens', 'max'],
+        nullable: true,
+      },
+      freeTokensTarget: { type: 'number', nullable: true },
+      maxRollingSummaries: { type: 'number', nullable: true },
+      systemInstruction: { type: 'string', nullable: true },
+    },
+    required: [],
+  };
+
+export function createRollingSummaryProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: RollingSummaryProcessorOptions,
+): ContextProcessor {
+  const generateRollingSummary = async (
+    nodes: ConcreteNode[],
+  ): Promise<string> => {
+    let transcript = '';
+    for (const node of nodes) {
+      let nodeContent = '';
+      if ('text' in node && typeof node.text === 'string') {
+        nodeContent = node.text;
+      } else if ('semanticParts' in node) {
+        nodeContent = JSON.stringify(node.semanticParts);
+      } else if ('observation' in node) {
+        nodeContent =
+          typeof node.observation === 'string'
+            ? node.observation
+            : JSON.stringify(node.observation);
+      }
+      transcript += `[${node.type}]: ${nodeContent}\n`;
+    }
+
+    const systemPrompt =
+      options.systemInstruction ??
+      `You are an expert context compressor. Your job is to drastically shorten the provided conversational transcript while preserving the absolute core semantic meaning, facts, and intent. Omit all conversational filler, pleasantries, or redundant information. Return ONLY the compressed summary.`;
+
+    const response = await env.llmClient.generateContent({
+      role: LlmRole.UTILITY_COMPRESSOR,
+      modelConfigKey: { model: 'gemini-3-flash-base' },
+      promptId: env.promptId,
+      abortSignal: new AbortController().signal,
+      contents: [{ role: 'user', parts: [{ text: transcript }] }],
+      systemInstruction: { role: 'system', parts: [{ text: systemPrompt }] },
+    });
+
+    const candidate = response.candidates?.[0];
+    const textPart = candidate?.content?.parts?.[0];
+    return textPart?.text || '';
+  };
+
+  return {
+    id,
+    name: 'RollingSummaryProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      if (targets.length === 0) return targets;
+
+      const strategy = options.target ?? 'max';
+      const nodesToSummarize: ConcreteNode[] = [];
+
+      if (strategy === 'incremental') {
+        // 'incremental' simply summarizes the minimum viable chunk (the oldest 2 nodes), ignoring token math.
+        for (const node of targets) {
+          if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+            continue; // Keep system prompt
+          }
+          nodesToSummarize.push(node);
+          if (nodesToSummarize.length >= 2) break; // We have enough for a minimum rolling summary
+        }
+      } else {
+        let targetTokensToRemove = 0;
+        if (strategy === 'freeNTokens') {
+          targetTokensToRemove = options.freeTokensTarget ?? Infinity;
+        } else if (strategy === 'max') {
+          targetTokensToRemove = Infinity;
+        }
+
+        if (targetTokensToRemove > 0) {
+          let deficitAccumulator = 0;
+          for (const node of targets) {
+            if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+              continue; // Keep system prompt
+            }
+            nodesToSummarize.push(node);
+            deficitAccumulator += env.tokenCalculator.getTokenCost(node);
+            if (deficitAccumulator >= targetTokensToRemove) break;
+          }
+        }
+      }
+
+      if (nodesToSummarize.length < 2) return targets; // Not enough context to summarize
+
+      try {
+        // Synthesize the rolling summary synchronously
+        const snapshotText = await generateRollingSummary(nodesToSummarize);
+        const newId = randomUUID();
+
+        const summaryNode: RollingSummary = {
+          id: newId,
+          logicalParentId: newId,
+          type: 'ROLLING_SUMMARY',
+          timestamp: Date.now(),
+          text: snapshotText,
+          abstractsIds: nodesToSummarize.map((n) => n.id),
+        };
+
+        const consumedIds = nodesToSummarize.map((n) => n.id);
+        const returnedNodes = targets.filter(
+          (t) => !consumedIds.includes(t.id),
+        );
+        const firstRemovedIdx = targets.findIndex((t) =>
+          consumedIds.includes(t.id),
+        );
+
+        if (firstRemovedIdx !== -1) {
+          const idx = Math.max(0, firstRemovedIdx);
+          returnedNodes.splice(idx, 0, summaryNode);
+        } else {
+          returnedNodes.unshift(summaryNode);
+        }
+
+        return returnedNodes;
+      } catch (e) {
+        debugLogger.error('RollingSummaryProcessor failed sync backstop', e);
+        return targets;
+      }
+    },
+  };
+}

packages/core/src/context/processors/stateSnapshotAsyncProcessor.test.ts

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createStateSnapshotAsyncProcessor } from './stateSnapshotAsyncProcessor.js';
+import {
+  createMockEnvironment,
+  createDummyNode,
+  createMockProcessArgs,
+} from '../testing/contextTestUtils.js';
+import type { InboxMessage } from '../pipeline.js';
+import type { InboxSnapshotImpl } from '../pipeline/inbox.js';
+
+describe('StateSnapshotAsyncProcessor', () => {
+  it('should generate a snapshot and publish it to the inbox', async () => {
+    const env = createMockEnvironment();
+    // Spy on the publish method
+    const publishSpy = vi.spyOn(env.inbox, 'publish');
+
+    const worker = createStateSnapshotAsyncProcessor(
+      'StateSnapshotAsyncProcessor',
+      env,
+      { type: 'point-in-time' },
+    );
+
+    const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+
+    const targets = [nodeA, nodeB];
+    await worker.process(createMockProcessArgs(targets, targets, []));
+
+    // Ensure generateContent was called
+    expect(env.llmClient.generateContent).toHaveBeenCalled();
+
+    // Verify it published to the inbox
+    expect(publishSpy).toHaveBeenCalledWith(
+      'PROPOSED_SNAPSHOT',
+      expect.objectContaining({
+        newText: 'Mock LLM summary response',
+        consumedIds: ['node-A', 'node-B'],
+        type: 'point-in-time',
+      }),
+    );
+  });
+
+  it('should pull previous accumulate snapshot from inbox and append new targets', async () => {
+    const env = createMockEnvironment();
+    const publishSpy = vi.spyOn(env.inbox, 'publish');
+    const drainSpy = vi.spyOn(env.inbox, 'drainConsumed');
+
+    const worker = createStateSnapshotAsyncProcessor(
+      'StateSnapshotAsyncProcessor',
+      env,
+      { type: 'accumulate' },
+    );
+
+    const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+    const targets = [nodeC];
+
+    const inboxMessages: InboxMessage[] = [
+      {
+        id: 'draft-1',
+        topic: 'PROPOSED_SNAPSHOT',
+        timestamp: Date.now() - 1000,
+        payload: {
+          consumedIds: ['node-A', 'node-B'],
+          newText: '<old snapshot>',
+          type: 'accumulate',
+        },
+      },
+    ];
+
+    const args = createMockProcessArgs(targets, targets, inboxMessages);
+
+    await worker.process(args);
+
+    // The old draft should be consumed
+    expect(
+      (args.inbox as InboxSnapshotImpl).getConsumedIds().has('draft-1'),
+    ).toBe(true);
+    expect(drainSpy).toHaveBeenCalledWith(expect.any(Set));
+
+    // The new publish should contain ALL consumed IDs (old + new)
+    expect(publishSpy).toHaveBeenCalledWith(
+      'PROPOSED_SNAPSHOT',
+      expect.objectContaining({
+        newText: 'Mock LLM summary response',
+        consumedIds: ['node-A', 'node-B', 'node-C'], // Aggregated!
+        type: 'accumulate',
+      }),
+    );
+
+    // Verify the LLM was called with the old snapshot prepended
+    expect(env.llmClient.generateContent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contents: expect.arrayContaining([
+          expect.objectContaining({
+            parts: expect.arrayContaining([
+              expect.objectContaining({
+                text: expect.stringContaining('<old snapshot>'),
+              }),
+            ]),
+          }),
+        ]),
+      }),
+    );
+  });
+
+  it('should ignore empty targets', async () => {
+    const env = createMockEnvironment();
+    const publishSpy = vi.spyOn(env.inbox, 'publish');
+    const worker = createStateSnapshotAsyncProcessor(
+      'StateSnapshotAsyncProcessor',
+      env,
+      { type: 'accumulate' },
+    );
+
+    await worker.process(createMockProcessArgs([], [], []));
+
+    expect(env.llmClient.generateContent).not.toHaveBeenCalled();
+    expect(publishSpy).not.toHaveBeenCalled();
+  });
+});

packages/core/src/context/processors/stateSnapshotAsyncProcessor.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type { AsyncContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode } from '../graph/types.js';
+import { SnapshotGenerator } from '../utils/snapshotGenerator.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+
+export interface StateSnapshotAsyncProcessorOptions {
+  type?: 'accumulate' | 'point-in-time';
+  systemInstruction?: string;
+}
+
+export const StateSnapshotAsyncProcessorOptionsSchema: JSONSchemaType<StateSnapshotAsyncProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        enum: ['accumulate', 'point-in-time'],
+        nullable: true,
+      },
+      systemInstruction: { type: 'string', nullable: true },
+    },
+    required: [],
+  };
+
+export function createStateSnapshotAsyncProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: StateSnapshotAsyncProcessorOptions,
+): AsyncContextProcessor {
+  const generator = new SnapshotGenerator(env);
+
+  return {
+    id,
+    name: 'StateSnapshotAsyncProcessor',
+    process: async ({ targets, inbox }: ProcessArgs): Promise<void> => {
+      if (targets.length === 0) return;
+
+      try {
+        let nodesToSummarize = [...targets];
+        let previousConsumedIds: string[] = [];
+        const processorType = options.type ?? 'point-in-time';
+
+        if (processorType === 'accumulate') {
+          // Look for the most recent unconsumed accumulate snapshot in the inbox
+          const proposedSnapshots = inbox.getMessages<{
+            newText: string;
+            consumedIds: string[];
+            type: string;
+          }>('PROPOSED_SNAPSHOT');
+          const accumulateSnapshots = proposedSnapshots.filter(
+            (s) => s.payload.type === 'accumulate',
+          );
+
+          if (accumulateSnapshots.length > 0) {
+            // Sort to find the most recent
+            const latest = [...accumulateSnapshots].sort(
+              (a, b) => b.timestamp - a.timestamp,
+            )[0];
+
+            // Consume the old draft so the inbox doesn't fill up with stale drafts
+            inbox.consume(latest.id);
+            // And we must persist its consumption back to the live inbox immediately,
+            // because we are effectively "taking" it from the shelf to modify.
+            env.inbox.drainConsumed(new Set([latest.id]));
+
+            previousConsumedIds = latest.payload.consumedIds;
+
+            // Prepend a synthetic node representing the previous rolling state
+            const previousStateNode: ConcreteNode = {
+              id: randomUUID(),
+              logicalParentId: '',
+              type: 'SNAPSHOT',
+              timestamp: latest.timestamp,
+              text: latest.payload.newText,
+            };
+
+            nodesToSummarize = [previousStateNode, ...targets];
+          }
+        }
+
+        const snapshotText = await generator.synthesizeSnapshot(
+          nodesToSummarize,
+          options.systemInstruction,
+        );
+
+        const newConsumedIds = [
+          ...previousConsumedIds,
+          ...targets.map((t) => t.id),
+        ];
+
+        // In V2, async pipelines communicate their work to the inbox, and the processor picks it up.
+        env.inbox.publish('PROPOSED_SNAPSHOT', {
+          newText: snapshotText,
+          consumedIds: newConsumedIds,
+          type: processorType,
+        });
+      } catch (e) {
+        debugLogger.error(
+          'StateSnapshotAsyncProcessor failed to generate snapshot',
+          e,
+        );
+      }
+    },
+  };
+}

packages/core/src/context/processors/stateSnapshotProcessor.test.ts

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createStateSnapshotProcessor } from './stateSnapshotProcessor.js';
+import {
+  createMockEnvironment,
+  createDummyNode,
+  createMockProcessArgs,
+} from '../testing/contextTestUtils.js';
+import type { InboxSnapshotImpl } from '../pipeline/inbox.js';
+
+describe('StateSnapshotProcessor', () => {
+  it('should ignore if budget is satisfied', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor(
+      'StateSnapshotProcessor',
+      env,
+      {
+        target: 'incremental',
+      },
+    );
+    const targets = [createDummyNode('ep1', 'USER_PROMPT')];
+    const result = await processor.process(createMockProcessArgs(targets));
+    expect(result).toBe(targets); // Strict equality
+  });
+
+  it('should apply a valid snapshot from the Inbox (Fast Path)', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor(
+      'StateSnapshotProcessor',
+      env,
+      {
+        target: 'incremental',
+      },
+    );
+
+    const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+    const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+
+    const targets = [nodeA, nodeB, nodeC];
+
+    // The async background pipeline created a snapshot of A and B
+    const messages = [
+      {
+        id: 'msg-1',
+        topic: 'PROPOSED_SNAPSHOT',
+        timestamp: Date.now(),
+        payload: {
+          consumedIds: ['node-A', 'node-B'],
+          newText: '<compressed A and B>',
+          type: 'point-in-time',
+        },
+      },
+    ];
+
+    const processArgs = createMockProcessArgs(targets, [], messages);
+    const result = await processor.process(processArgs);
+
+    // Should remove A and B, insert Snapshot, keep C
+    expect(result.length).toBe(2);
+    expect(result[0].type).toBe('SNAPSHOT');
+    expect(result[1].id).toBe('node-C');
+
+    // Should consume the message
+    expect(
+      (processArgs.inbox as InboxSnapshotImpl).getConsumedIds().has('msg-1'),
+    ).toBe(true);
+  });
+
+  it('should reject a snapshot if the nodes were modified/deleted (Cache Invalidated)', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor(
+      'StateSnapshotProcessor',
+      env,
+      {
+        target: 'incremental',
+      },
+    );
+    // Make deficit 0 so we don't fall through to the sync backstop and fail the test that way
+
+    // node-A is MISSING (user deleted it)
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+    const targets = [nodeB];
+
+    const messages = [
+      {
+        id: 'msg-1',
+        topic: 'PROPOSED_SNAPSHOT',
+        timestamp: Date.now(),
+        payload: {
+          consumedIds: ['node-A', 'node-B'],
+          newText: '<compressed A and B>',
+        },
+      },
+    ];
+
+    const processArgs = createMockProcessArgs(targets, [], messages);
+    const result = await processor.process(processArgs);
+
+    // Because deficit is 0, and Inbox was rejected, nothing should change
+    expect(result.length).toBe(1);
+    expect(result[0].id).toBe('node-B');
+    expect(
+      (processArgs.inbox as InboxSnapshotImpl).getConsumedIds().has('msg-1'),
+    ).toBe(false);
+  });
+
+  it('should fall back to sync backstop if inbox is empty', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor(
+      'StateSnapshotProcessor',
+      env,
+      { target: 'max' },
+    ); // Summarize all
+
+    const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+    const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+    const targets = [nodeA, nodeB, nodeC];
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    // Should synthesize a new snapshot synchronously
+    expect(env.llmClient.generateContent).toHaveBeenCalled();
+    expect(result.length).toBe(2); // nodeA is skipped as "system prompt", snapshot + nodeA
+    expect(result[1].type).toBe('SNAPSHOT');
+  });
+});

packages/core/src/context/processors/stateSnapshotProcessor.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type {
+  ContextProcessor,
+  ProcessArgs,
+  BackstopTargetOptions,
+} from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode, Snapshot } from '../graph/types.js';
+import { SnapshotGenerator } from '../utils/snapshotGenerator.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+
+export interface StateSnapshotProcessorOptions extends BackstopTargetOptions {
+  model?: string;
+  systemInstruction?: string;
+}
+
+export const StateSnapshotProcessorOptionsSchema: JSONSchemaType<StateSnapshotProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      target: {
+        type: 'string',
+        enum: ['incremental', 'freeNTokens', 'max'],
+        nullable: true,
+      },
+      freeTokensTarget: { type: 'number', nullable: true },
+      model: { type: 'string', nullable: true },
+      systemInstruction: { type: 'string', nullable: true },
+    },
+    required: [],
+  };
+
+export function createStateSnapshotProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: StateSnapshotProcessorOptions,
+): ContextProcessor {
+  const generator = new SnapshotGenerator(env);
+
+  return {
+    id,
+    name: 'StateSnapshotProcessor',
+    process: async ({ targets, inbox }: ProcessArgs) => {
+      if (targets.length === 0) {
+        return targets;
+      }
+
+      // Determine what mode we are looking for: 'incremental' -> 'point-in-time', 'max' -> 'accumulate'
+      const strategy = options.target ?? 'max';
+      const expectedType =
+        strategy === 'incremental' ? 'point-in-time' : 'accumulate';
+
+      // 1. Check Inbox for a completed Snapshot (The Fast Path)
+      const proposedSnapshots = inbox.getMessages<{
+        newText: string;
+        consumedIds: string[];
+        type: string;
+      }>('PROPOSED_SNAPSHOT');
+
+      if (proposedSnapshots.length > 0) {
+        // Filter for the snapshot type that matches our processor mode
+        const matchingSnapshots = proposedSnapshots.filter(
+          (s) => s.payload.type === expectedType,
+        );
+
+        // Sort by newest timestamp first (we want the most accumulated snapshot)
+        const sorted = [...matchingSnapshots].sort(
+          (a, b) => b.timestamp - a.timestamp,
+        );
+
+        for (const proposed of sorted) {
+          const { consumedIds, newText } = proposed.payload;
+
+          // Verify all consumed IDs still exist sequentially in targets
+          const targetIds = new Set(targets.map((t) => t.id));
+          const isValid = consumedIds.every((id) => targetIds.has(id));
+
+          if (isValid) {
+            // If valid, apply it!
+            const newId = randomUUID();
+
+            const snapshotNode: Snapshot = {
+              id: newId,
+              logicalParentId: newId,
+              type: 'SNAPSHOT',
+              timestamp: Date.now(),
+              text: newText,
+              abstractsIds: consumedIds,
+            };
+
+            // Remove the consumed nodes and insert the snapshot at the earliest index
+            const returnedNodes = targets.filter(
+              (t) => !consumedIds.includes(t.id),
+            );
+            const firstRemovedIdx = targets.findIndex((t) =>
+              consumedIds.includes(t.id),
+            );
+
+            if (firstRemovedIdx !== -1) {
+              const idx = Math.max(0, firstRemovedIdx);
+              returnedNodes.splice(idx, 0, snapshotNode);
+            } else {
+              returnedNodes.unshift(snapshotNode);
+            }
+
+            inbox.consume(proposed.id);
+            return returnedNodes;
+          }
+        }
+      }
+
+      // 2. The Synchronous Backstop (The Slow Path)
+      let targetTokensToRemove = 0;
+
+      if (strategy === 'incremental') {
+        targetTokensToRemove = Infinity; // incremental implies removing as much as possible if no state is passed
+      } else if (strategy === 'freeNTokens') {
+        targetTokensToRemove = options.freeTokensTarget ?? Infinity;
+      } else if (strategy === 'max') {
+        targetTokensToRemove = Infinity;
+      }
+
+      let deficitAccumulator = 0;
+      const nodesToSummarize: ConcreteNode[] = [];
+
+      // Scan oldest to newest
+      for (const node of targets) {
+        if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+          // Keep system prompt if it's the very first node
+          // In a real system, system prompt is protected, but we double check
+          continue;
+        }
+
+        nodesToSummarize.push(node);
+        deficitAccumulator += env.tokenCalculator.getTokenCost(node);
+
+        if (deficitAccumulator >= targetTokensToRemove) break;
+      }
+
+      if (nodesToSummarize.length < 2) return targets; // Not enough context
+
+      try {
+        const snapshotText = await generator.synthesizeSnapshot(
+          nodesToSummarize,
+          options.systemInstruction,
+        );
+        const newId = randomUUID();
+        const snapshotNode: Snapshot = {
+          id: newId,
+          logicalParentId: newId,
+          type: 'SNAPSHOT',
+          timestamp: Date.now(),
+          text: snapshotText,
+          abstractsIds: nodesToSummarize.map((n) => n.id),
+        };
+
+        const consumedIds = nodesToSummarize.map((n) => n.id);
+        const returnedNodes = targets.filter(
+          (t) => !consumedIds.includes(t.id),
+        );
+        const firstRemovedIdx = targets.findIndex((t) =>
+          consumedIds.includes(t.id),
+        );
+
+        if (firstRemovedIdx !== -1) {
+          const idx = Math.max(0, firstRemovedIdx);
+          returnedNodes.splice(idx, 0, snapshotNode);
+        } else {
+          returnedNodes.unshift(snapshotNode);
+        }
+
+        return returnedNodes;
+      } catch (e) {
+        debugLogger.error('StateSnapshotProcessor failed sync backstop', e);
+        return targets;
+      }
+    },
+  };
+}

packages/core/src/context/processors/toolMaskingProcessor.test.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createToolMaskingProcessor } from './toolMaskingProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyToolNode,
+} from '../testing/contextTestUtils.js';
+import type { ToolExecution } from '../graph/types.js';
+
+describe('ToolMaskingProcessor', () => {
+  it('should write large strings to disk and replace them with a masked pointer', async () => {
+    const env = createMockEnvironment();
+    // env uses charsPerToken=1 natively.
+    // original string lengths > stringLengthThresholdTokens (which is 10) will be masked
+
+    const processor = createToolMaskingProcessor('ToolMaskingProcessor', env, {
+      stringLengthThresholdTokens: 10,
+    });
+
+    const longString = 'A'.repeat(500); // 500 chars
+
+    const toolStep = createDummyToolNode('ep1', 50, 500, {
+      observation: {
+        result: longString,
+        metadata: 'short', // 5 chars, will not be masked
+      },
+    });
+
+    const result = await processor.process(createMockProcessArgs([toolStep]));
+
+    expect(result.length).toBe(1);
+    const masked = result[0] as ToolExecution;
+
+    // It should have generated a new ID because it modified it
+    expect(masked.id).not.toBe(toolStep.id);
+
+    // It should have masked the observation
+    const obs = masked.observation as { result: string; metadata: string };
+    expect(obs.result).toContain('<tool_output_masked>');
+    expect(obs.metadata).toBe('short'); // Untouched
+  });
+
+  it('should skip unmaskable tools', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createToolMaskingProcessor('ToolMaskingProcessor', env, {
+      stringLengthThresholdTokens: 10,
+    });
+
+    const toolStep = createDummyToolNode('ep1', 10, 10, {
+      toolName: 'activate_skill',
+      observation: {
+        result:
+          'this is a really long string that normally would get masked but wont because of the tool name',
+      },
+    });
+
+    const result = await processor.process(createMockProcessArgs([toolStep]));
+
+    // Returned the exact same object reference
+    expect(result[0]).toBe(toolStep);
+  });
+});

packages/core/src/context/processors/toolMaskingProcessor.ts

@@ -0,0 +1,271 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import type { JSONSchemaType } from 'ajv';
+import type { ContextProcessor, ProcessArgs } from '../pipeline.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { ConcreteNode, ToolExecution } from '../graph/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { sanitizeFilenamePart } from '../../utils/fileUtils.js';
+import {
+  ACTIVATE_SKILL_TOOL_NAME,
+  MEMORY_TOOL_NAME,
+  ASK_USER_TOOL_NAME,
+  ENTER_PLAN_MODE_TOOL_NAME,
+  EXIT_PLAN_MODE_TOOL_NAME,
+} from '../../tools/tool-names.js';
+import type { Part } from '@google/genai';
+
+export interface ToolMaskingProcessorOptions {
+  stringLengthThresholdTokens: number;
+}
+
+export const ToolMaskingProcessorOptionsSchema: JSONSchemaType<ToolMaskingProcessorOptions> =
+  {
+    type: 'object',
+    properties: {
+      stringLengthThresholdTokens: { type: 'number' },
+    },
+    required: ['stringLengthThresholdTokens'],
+  };
+
+const UNMASKABLE_TOOLS = new Set([
+  ACTIVATE_SKILL_TOOL_NAME,
+  MEMORY_TOOL_NAME,
+  ASK_USER_TOOL_NAME,
+  ENTER_PLAN_MODE_TOOL_NAME,
+  EXIT_PLAN_MODE_TOOL_NAME,
+]);
+
+type MaskableValue =
+  | string
+  | number
+  | boolean
+  | null
+  | MaskableValue[]
+  | { [key: string]: MaskableValue };
+
+function isMaskableValue(val: unknown): val is MaskableValue {
+  if (
+    val === null ||
+    typeof val === 'string' ||
+    typeof val === 'number' ||
+    typeof val === 'boolean'
+  ) {
+    return true;
+  }
+  if (Array.isArray(val)) {
+    return val.every(isMaskableValue);
+  }
+  if (typeof val === 'object') {
+    return Object.values(val).every(isMaskableValue);
+  }
+  return false;
+}
+
+function isMaskableRecord(val: unknown): val is Record<string, MaskableValue> {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    !Array.isArray(val) &&
+    isMaskableValue(val)
+  );
+}
+
+export function createToolMaskingProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: ToolMaskingProcessorOptions,
+): ContextProcessor {
+  const isAlreadyMasked = (text: string): boolean =>
+    text.includes('<tool_output_masked>');
+
+  return {
+    id,
+    name: 'ToolMaskingProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      const maskingConfig = options;
+      if (!maskingConfig) return targets;
+      if (targets.length === 0) return targets;
+
+      const limitChars = env.tokenCalculator.tokensToChars(
+        maskingConfig.stringLengthThresholdTokens,
+      );
+
+      let toolOutputsDir = path.join(env.projectTempDir, 'tool-outputs');
+      const sessionId = env.sessionId;
+      if (sessionId) {
+        toolOutputsDir = path.join(
+          toolOutputsDir,
+          `session-${sanitizeFilenamePart(sessionId)}`,
+        );
+      }
+
+      let directoryCreated = false;
+
+      const handleMasking = async (
+        content: string,
+        toolName: string,
+        callId: string,
+        nodeType: string,
+      ): Promise<string> => {
+        if (!directoryCreated) {
+          await fs.mkdir(toolOutputsDir, { recursive: true });
+          directoryCreated = true;
+        }
+
+        const fileName = `${sanitizeFilenamePart(toolName).toLowerCase()}_${sanitizeFilenamePart(callId).toLowerCase()}_${nodeType}_${randomUUID()}.txt`;
+        const filePath = path.join(toolOutputsDir, fileName);
+
+        await fs.writeFile(filePath, content);
+
+        const fileSizeMB = (
+          Buffer.byteLength(content, 'utf8') /
+          1024 /
+          1024
+        ).toFixed(2);
+        const totalLines = content.split('\n').length;
+        return `<tool_output_masked>\n[Tool ${nodeType} string (${fileSizeMB}MB, ${totalLines} lines) masked to preserve context window. Full string saved to: ${filePath}]\n</tool_output_masked>`;
+      };
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      for (const node of targets) {
+        switch (node.type) {
+          case 'TOOL_EXECUTION': {
+            const toolName = node.toolName;
+            if (toolName && UNMASKABLE_TOOLS.has(toolName)) {
+              returnedNodes.push(node);
+              break;
+            }
+
+            const callId = node.id || Date.now().toString();
+
+            const maskAsync = async (
+              obj: MaskableValue,
+              nodeType: string,
+            ): Promise<{ masked: MaskableValue; changed: boolean }> => {
+              if (typeof obj === 'string') {
+                if (obj.length > limitChars && !isAlreadyMasked(obj)) {
+                  const newString = await handleMasking(
+                    obj,
+                    toolName || 'unknown',
+                    callId,
+                    nodeType,
+                  );
+                  return { masked: newString, changed: true };
+                }
+                return { masked: obj, changed: false };
+              }
+              if (Array.isArray(obj)) {
+                let changed = false;
+                const masked: MaskableValue[] = [];
+                for (const item of obj) {
+                  const res = await maskAsync(item, nodeType);
+                  if (res.changed) changed = true;
+                  masked.push(res.masked);
+                }
+                return { masked, changed };
+              }
+              if (typeof obj === 'object' && obj !== null) {
+                let changed = false;
+                const masked: Record<string, MaskableValue> = {};
+                for (const [key, value] of Object.entries(obj)) {
+                  const res = await maskAsync(value, nodeType);
+                  if (res.changed) changed = true;
+                  masked[key] = res.masked;
+                }
+                return { masked, changed };
+              }
+              return { masked: obj, changed: false };
+            };
+
+            const rawIntent = node.intent;
+            const rawObs = node.observation;
+
+            if (!isMaskableRecord(rawIntent) || !isMaskableValue(rawObs)) {
+              returnedNodes.push(node);
+              break;
+            }
+
+            const intentRes = await maskAsync(rawIntent, 'intent');
+            const obsRes = await maskAsync(rawObs, 'observation');
+
+            if (intentRes.changed || obsRes.changed) {
+              const maskedIntent = isMaskableRecord(intentRes.masked)
+                ? (intentRes.masked as Record<string, unknown>)
+                : undefined;
+              // Handle observation explicitly as string vs object
+              const maskedObs =
+                typeof obsRes.masked === 'string'
+                  ? ({ message: obsRes.masked } as Record<string, unknown>)
+                  : isMaskableRecord(obsRes.masked)
+                    ? (obsRes.masked as Record<string, unknown>)
+                    : undefined;
+
+              const newIntentTokens =
+                env.tokenCalculator.estimateTokensForParts([
+                  {
+                    functionCall: {
+                      name: toolName || 'unknown',
+                      args: maskedIntent,
+                      id: callId,
+                    },
+                  },
+                ]);
+
+              let obsPart: Record<string, unknown> = {};
+              if (maskedObs) {
+                obsPart = {
+                  functionResponse: {
+                    name: toolName || 'unknown',
+                    response: maskedObs,
+                    id: callId,
+                  },
+                };
+              }
+
+              const newObsTokens = env.tokenCalculator.estimateTokensForParts([
+                obsPart as Part,
+              ]);
+
+              const tokensSaved =
+                env.tokenCalculator.getTokenCost(node) -
+                (newIntentTokens + newObsTokens);
+
+              if (tokensSaved > 0) {
+                const maskedNode: ToolExecution = {
+                  ...node,
+                  id: randomUUID(), // Modified, so generate new ID
+                  intent: maskedIntent ?? node.intent,
+                  observation: maskedObs ?? node.observation,
+                  tokens: {
+                    intent: newIntentTokens,
+                    observation: newObsTokens,
+                  },
+                  replacesId: node.id,
+                };
+
+                returnedNodes.push(maskedNode);
+              } else {
+                returnedNodes.push(node);
+              }
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/system-tests/lifecycle.golden.test.ts

@@ -0,0 +1,246 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { SimulationHarness } from './simulationHarness.js';
+import { createMockLlmClient } from '../testing/contextTestUtils.js';
+import type { ContextProfile } from '../config/profiles.js';
+import { createToolMaskingProcessor } from '../processors/toolMaskingProcessor.js';
+import { createBlobDegradationProcessor } from '../processors/blobDegradationProcessor.js';
+import { createStateSnapshotProcessor } from '../processors/stateSnapshotProcessor.js';
+import { createHistoryTruncationProcessor } from '../processors/historyTruncationProcessor.js';
+import { createStateSnapshotAsyncProcessor } from '../processors/stateSnapshotAsyncProcessor.js';
+
+expect.addSnapshotSerializer({
+  test: (val) =>
+    typeof val === 'string' &&
+    (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+      val,
+    ) ||
+      /^\/tmp\/sim/.test(val)), // Mask temp directories and UUIDs
+  print: (val) =>
+    typeof val === 'string' && /^\/tmp\/sim/.test(val)
+      ? '"<MOCKED_DIR>"'
+      : '"<UUID>"',
+});
+
+describe('System Lifecycle Golden Tests', () => {
+  beforeAll(() => {
+    vi.spyOn(Math, 'random').mockReturnValue(0.5);
+  });
+
+  afterAll(() => {
+    vi.restoreAllMocks();
+  });
+
+  const getAggressiveConfig = (): ContextProfile => ({
+    config: {
+      budget: { maxTokens: 1000, retainedTokens: 500 }, // Extremely tight limits
+    },
+    buildPipelines: (env) => [
+      {
+        name: 'Pressure Relief', // Emits from eventBus 'retained_exceeded'
+        triggers: ['retained_exceeded'],
+        processors: [
+          createBlobDegradationProcessor('BlobDegradationProcessor', env),
+          createToolMaskingProcessor('ToolMaskingProcessor', env, {
+            stringLengthThresholdTokens: 50,
+          }),
+          createStateSnapshotProcessor('StateSnapshotProcessor', env, {}),
+        ],
+      },
+      {
+        name: 'Immediate Sanitization', // The magic string the projector is hardcoded to use
+        triggers: ['retained_exceeded'],
+        processors: [
+          createHistoryTruncationProcessor(
+            'HistoryTruncationProcessor',
+            env,
+            {},
+          ),
+        ],
+      },
+    ],
+    buildAsyncPipelines: (env) => [
+      {
+        name: 'Async',
+        triggers: ['nodes_aged_out'],
+        processors: [
+          createStateSnapshotAsyncProcessor(
+            'StateSnapshotAsyncProcessor',
+            env,
+            {},
+          ),
+        ],
+      },
+    ],
+  });
+
+  const mockLlmClient = createMockLlmClient([
+    '<MOCKED_STATE_SNAPSHOT_SUMMARY>',
+  ]);
+
+  it('Scenario 1: Organic Growth with Huge Tool Output & Images', async () => {
+    const harness = await SimulationHarness.create(
+      getAggressiveConfig(),
+      mockLlmClient,
+    );
+
+    // Turn 0: System Prompt
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'System Instructions' }] },
+      { role: 'model', parts: [{ text: 'Ack.' }] },
+    ]);
+
+    // Turn 1: Normal conversation
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Hello!' }] },
+      { role: 'model', parts: [{ text: 'Hi, how can I help?' }] },
+    ]);
+
+    // Turn 2: Massive Tool Output (Should trigger ToolMaskingProcessor in background)
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Read the logs.' }] },
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'run_shell_command',
+              args: { cmd: 'cat server.log' },
+            },
+          },
+        ],
+      },
+      {
+        role: 'user',
+        parts: [
+          {
+            functionResponse: {
+              name: 'run_shell_command',
+              response: { output: 'LOG '.repeat(5000) },
+            },
+          },
+        ],
+      },
+      { role: 'model', parts: [{ text: 'The logs are very long.' }] },
+    ]);
+
+    // Turn 3: Multi-modal blob (Should trigger BlobDegradationProcessor)
+    await harness.simulateTurn([
+      {
+        role: 'user',
+        parts: [
+          { text: 'Look at this architecture diagram:' },
+          {
+            inlineData: {
+              mimeType: 'image/png',
+              data: 'fake_base64_data_'.repeat(1000),
+            },
+          },
+        ],
+      },
+      { role: 'model', parts: [{ text: 'Nice diagram.' }] },
+    ]);
+
+    // Turn 4: More conversation to trigger StateSnapshot
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Can we refactor?' }] },
+      { role: 'model', parts: [{ text: 'Yes we can.' }] },
+    ]);
+
+    // Get final state
+    const goldenState = await harness.getGoldenState();
+
+    // In a perfectly functioning opportunistic system, the token trajectory should show
+    // the massive spikes in Turn 2 and 3 being immediately resolved by the background tasks.
+    // The final projection should fit neatly under the Max Tokens limit.
+
+    expect(goldenState).toMatchSnapshot();
+  });
+
+  it('Scenario 2: Under Budget (No Modifications)', async () => {
+    const generousConfig: ContextProfile = {
+      config: {
+        budget: { maxTokens: 100000, retainedTokens: 50000 },
+      },
+      buildPipelines: () => [],
+      buildAsyncPipelines: () => [],
+    };
+
+    const harness = await SimulationHarness.create(
+      generousConfig,
+      mockLlmClient,
+    );
+
+    // Turn 0: System Prompt
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'System Instructions' }] },
+      { role: 'model', parts: [{ text: 'Ack.' }] },
+    ]);
+
+    // Turn 1: Normal conversation
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Hello!' }] },
+      { role: 'model', parts: [{ text: 'Hi, how can I help?' }] },
+    ]);
+
+    const goldenState = await harness.getGoldenState();
+
+    // Total tokens should cleanly match character count with no synthetic nodes
+    expect(goldenState).toMatchSnapshot();
+  });
+
+  it('Scenario 3: Async-Driven Background GC', async () => {
+    const gcConfig: ContextProfile = {
+      config: {
+        budget: { maxTokens: 200, retainedTokens: 100 },
+      },
+      buildPipelines: () => [],
+      buildAsyncPipelines: (env) => [
+        {
+          name: 'Async',
+          triggers: ['nodes_aged_out'],
+          processors: [
+            createStateSnapshotAsyncProcessor(
+              'StateSnapshotAsyncProcessor',
+              env,
+              {},
+            ),
+          ],
+        },
+      ],
+    };
+
+    const harness = await SimulationHarness.create(gcConfig, mockLlmClient);
+
+    // Turn 0
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'A'.repeat(50) }] },
+      { role: 'model', parts: [{ text: 'B'.repeat(50) }] },
+    ]);
+
+    // Turn 1 (Should trigger StateSnapshotasync pipeline because we exceed 100 retainedTokens)
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'C'.repeat(50) }] },
+      { role: 'model', parts: [{ text: 'D'.repeat(50) }] },
+    ]);
+
+    // Give the async background pipeline an extra beat to complete its async execution and emit variants
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Turn 2
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'E'.repeat(50) }] },
+      { role: 'model', parts: [{ text: 'F'.repeat(50) }] },
+    ]);
+
+    const goldenState = await harness.getGoldenState();
+
+    // We should see ROLLING_SUMMARY nodes injected into the graph, proving the async pipeline ran in the background
+    expect(goldenState).toMatchSnapshot();
+  });
+});

packages/core/src/context/system-tests/simulationHarness.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ContextManager } from '../contextManager.js';
+import { AgentChatHistory } from '../../core/agentChatHistory.js';
+import type { Content } from '@google/genai';
+import type { ContextProfile } from '../config/profiles.js';
+import { ContextEnvironmentImpl } from '../pipeline/environmentImpl.js';
+import { ContextTracer } from '../tracer.js';
+import { ContextEventBus } from '../eventBus.js';
+import { PipelineOrchestrator } from '../pipeline/orchestrator.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+
+export interface TurnSummary {
+  turnIndex: number;
+  tokensBeforeBackground: number;
+  tokensAfterBackground: number;
+}
+
+export class SimulationHarness {
+  readonly chatHistory: AgentChatHistory;
+  contextManager!: ContextManager;
+  env!: ContextEnvironmentImpl;
+  orchestrator!: PipelineOrchestrator;
+  readonly eventBus: ContextEventBus;
+  config!: ContextProfile;
+  private tracer!: ContextTracer;
+  private currentTurnIndex = 0;
+  private tokenTrajectory: TurnSummary[] = [];
+
+  static async create(
+    config: ContextProfile,
+    mockLlmClient: BaseLlmClient,
+    mockTempDir = '/tmp/sim',
+  ): Promise<SimulationHarness> {
+    const harness = new SimulationHarness();
+    await harness.init(config, mockLlmClient, mockTempDir);
+    return harness;
+  }
+
+  private constructor() {
+    this.chatHistory = new AgentChatHistory();
+    this.eventBus = new ContextEventBus();
+  }
+
+  private async init(
+    config: ContextProfile,
+    mockLlmClient: BaseLlmClient,
+    mockTempDir: string,
+  ) {
+    this.config = config;
+
+    this.tracer = new ContextTracer({
+      targetDir: mockTempDir,
+      sessionId: 'sim-session',
+    });
+    this.env = new ContextEnvironmentImpl(
+      mockLlmClient,
+      'sim-prompt',
+      'sim-session',
+      mockTempDir,
+      mockTempDir,
+      this.tracer,
+      1, // 1 char per token average
+      this.eventBus,
+    );
+
+    this.orchestrator = new PipelineOrchestrator(
+      config.buildPipelines(this.env),
+      config.buildAsyncPipelines(this.env),
+      this.env,
+      this.eventBus,
+      this.tracer,
+    );
+    this.contextManager = new ContextManager(
+      config,
+      this.env,
+      this.tracer,
+      this.orchestrator,
+      this.chatHistory,
+    );
+  }
+
+  /**
+   * Simulates a single "Turn" (User input + Model/Tool outputs)
+   * A turn might consist of multiple Content messages (e.g. user prompt -> model call -> user response -> model answer)
+   */
+  async simulateTurn(messages: Content[]) {
+    // 1. Append the new messages
+    const currentHistory = this.chatHistory.get();
+    this.chatHistory.set([...currentHistory, ...messages]);
+
+    // 2. Measure tokens immediately after append (Before background processing)
+    const tokensBefore = this.env.tokenCalculator.calculateConcreteListTokens(
+      this.contextManager.getNodes(),
+    );
+    debugLogger.log(
+      `[Turn ${this.currentTurnIndex}] Tokens BEFORE: ${tokensBefore}`,
+    );
+
+    // 3. Yield to event loop to allow internal async subscribers and orchestrator to finish
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // 3.1 Simulate what projectCompressedHistory does with the sync handlers
+    let currentView = this.contextManager.getNodes();
+    const currentTokens =
+      this.env.tokenCalculator.calculateConcreteListTokens(currentView);
+    if (
+      this.config.config.budget &&
+      currentTokens > this.config.config.budget.maxTokens
+    ) {
+      debugLogger.log(
+        `[Turn ${this.currentTurnIndex}] Sync panic triggered! ${currentTokens} > ${this.config.config.budget.maxTokens}`,
+      );
+      const orchestrator = this.orchestrator;
+      // In the V2 simulation, we trigger the 'gc_backstop' to simulate emergency pressure.
+      // Since contextManager owns its buffer natively, the simulation now properly matches reality
+      // where the manager runs the orchestrator and keeps the resulting modified view.
+      const modifiedView = await orchestrator.executeTriggerSync(
+        'gc_backstop',
+        currentView,
+        new Set(currentView.map((e) => e.id)),
+        new Set<string>(),
+      );
+
+      // In the real system, ContextManager triggers this and retains it.
+      // We will emulate that behavior internally in the test loop for token counting.
+      currentView = modifiedView;
+    }
+
+    // 4. Measure tokens after background processors have processed inboxes
+    const tokensAfter = this.env.tokenCalculator.calculateConcreteListTokens(
+      this.contextManager.getNodes(),
+    );
+    debugLogger.log(
+      `[Turn ${this.currentTurnIndex}] Tokens AFTER: ${tokensAfter}`,
+    );
+
+    this.tokenTrajectory.push({
+      turnIndex: this.currentTurnIndex++,
+      tokensBeforeBackground: tokensBefore,
+      tokensAfterBackground: tokensAfter,
+    });
+  }
+
+  async getGoldenState() {
+    const finalProjection = await this.contextManager.renderHistory();
+    return {
+      tokenTrajectory: this.tokenTrajectory,
+      finalProjection,
+    };
+  }
+}

packages/core/src/context/testing/contextTestUtils.ts

@@ -0,0 +1,278 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi } from 'vitest';
+import { AgentChatHistory } from '../../core/agentChatHistory.js';
+import { ContextManager } from '../contextManager.js';
+import { randomUUID } from 'node:crypto';
+import { ContextTracer } from '../tracer.js';
+import { ContextEnvironmentImpl } from '../pipeline/environmentImpl.js';
+import { ContextEventBus } from '../eventBus.js';
+import { PipelineOrchestrator } from '../pipeline/orchestrator.js';
+import type { ConcreteNode, ToolExecution } from '../graph/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { Config } from '../../config/config.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { Content, GenerateContentResponse } from '@google/genai';
+import { InboxSnapshotImpl } from '../pipeline/inbox.js';
+import type { InboxMessage, ProcessArgs } from '../pipeline.js';
+import type { ContextProfile } from '../config/profiles.js';
+import type { Mock } from 'vitest';
+import { ContextWorkingBufferImpl } from '../pipeline/contextWorkingBuffer.js';
+import { testTruncateProfile } from './testProfile.js';
+
+/**
+ * Creates a valid mock GenerateContentResponse with the provided text.
+ * Used to avoid having to manually construct the deeply nested candidate/content/part structure.
+ */
+export const createMockGenerateContentResponse = (
+  text: string,
+): GenerateContentResponse =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  ({
+    candidates: [{ content: { role: 'model', parts: [{ text }] }, index: 0 }],
+  }) as GenerateContentResponse;
+
+export function createDummyNode(
+  logicalParentId: string,
+  type: ConcreteNode['type'],
+  tokens = 100,
+  overrides?: Partial<ConcreteNode>,
+  id?: string,
+): ConcreteNode {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return {
+    id: id || randomUUID(),
+    episodeId: logicalParentId,
+    logicalParentId,
+    type,
+    timestamp: Date.now(),
+    text: `Dummy ${type}`,
+    name: type === 'SYSTEM_EVENT' ? 'dummy_event' : undefined,
+    payload: type === 'SYSTEM_EVENT' ? {} : undefined,
+    semanticParts: [],
+    metadata: {
+      originalTokens: tokens,
+      currentTokens: tokens,
+      transformations: [],
+    },
+    ...overrides,
+  } as unknown as ConcreteNode;
+}
+
+export function createDummyToolNode(
+  logicalParentId: string,
+  intentTokens = 100,
+  obsTokens = 200,
+  overrides?: Partial<ToolExecution>,
+  id?: string,
+): ToolExecution {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return {
+    id: id || randomUUID(),
+    episodeId: logicalParentId,
+    logicalParentId,
+    type: 'TOOL_EXECUTION',
+    timestamp: Date.now(),
+    toolName: 'dummy_tool',
+    intent: { action: 'test' },
+    observation: { result: 'ok' },
+    tokens: {
+      intent: intentTokens,
+      observation: obsTokens,
+    },
+    metadata: {
+      originalTokens: intentTokens + obsTokens,
+      currentTokens: intentTokens + obsTokens,
+      transformations: [],
+    },
+    ...overrides,
+  } as unknown as ToolExecution;
+}
+
+export interface MockLlmClient extends BaseLlmClient {
+  generateContent: Mock;
+}
+
+export function createMockLlmClient(
+  responses?: Array<string | GenerateContentResponse>,
+): MockLlmClient {
+  const generateContentMock = vi.fn();
+
+  if (responses && responses.length > 0) {
+    for (const response of responses) {
+      if (typeof response === 'string') {
+        generateContentMock.mockResolvedValueOnce(
+          createMockGenerateContentResponse(response),
+        );
+      } else {
+        generateContentMock.mockResolvedValueOnce(response);
+      }
+    }
+    // Fallback to the last response for any subsequent calls
+    const lastResponse = responses[responses.length - 1];
+    if (typeof lastResponse === 'string') {
+      generateContentMock.mockResolvedValue(
+        createMockGenerateContentResponse(lastResponse),
+      );
+    } else {
+      generateContentMock.mockResolvedValue(lastResponse);
+    }
+  } else {
+    // Default fallback
+    generateContentMock.mockResolvedValue(
+      createMockGenerateContentResponse('Mock LLM response'),
+    );
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return {
+    generateContent: generateContentMock,
+  } as unknown as MockLlmClient;
+}
+
+export function createMockEnvironment(
+  overrides?: Partial<ContextEnvironment>,
+): ContextEnvironment {
+  const llmClient = createMockLlmClient(['Mock LLM summary response']);
+
+  const tracer = new ContextTracer({
+    targetDir: '/tmp',
+    sessionId: 'mock-session',
+  });
+  const eventBus = new ContextEventBus();
+
+  const env = new ContextEnvironmentImpl(
+    llmClient,
+    'mock-session',
+    'mock-prompt-id',
+    '/tmp/.gemini/trace',
+    '/tmp/.gemini/tool-outputs',
+    tracer,
+    1,
+    eventBus,
+  );
+
+  if (overrides) {
+    Object.assign(env, overrides);
+  }
+  return env;
+}
+
+/**
+ * Creates a block of synthetic conversation history designed to consume a specific number of tokens.
+ * Assumes roughly 4 characters per token for standard English text.
+ */
+
+export function createMockProcessArgs(
+  targets: ConcreteNode[],
+  bufferNodes: ConcreteNode[] = [],
+  inboxMessages: InboxMessage[] = [],
+): ProcessArgs {
+  return {
+    targets,
+    buffer: ContextWorkingBufferImpl.initialize(
+      bufferNodes.length ? bufferNodes : targets,
+    ),
+    inbox: new InboxSnapshotImpl(inboxMessages),
+  };
+}
+
+export function createSyntheticHistory(
+  numTurns: number,
+  tokensPerTurn: number,
+): Content[] {
+  const history: Content[] = [];
+  const charsPerTurn = tokensPerTurn * 1;
+
+  for (let i = 0; i < numTurns; i++) {
+    history.push({
+      role: 'user',
+      parts: [{ text: `User turn ${i}. ` + 'A'.repeat(charsPerTurn) }],
+    });
+    history.push({
+      role: 'model',
+      parts: [{ text: `Model response ${i}. ` + 'B'.repeat(charsPerTurn) }],
+    });
+  }
+
+  return history;
+}
+
+/**
+ * Creates a fully mocked Config object tailored for Context Component testing.
+ */
+export function createMockContextConfig(
+  overrides?: Record<string, unknown>,
+  llmClientOverride?: unknown,
+): Config {
+  const defaultConfig = {
+    isContextManagementEnabled: vi.fn().mockReturnValue(true),
+    storage: {
+      getProjectTempDir: vi.fn().mockReturnValue('/tmp/gemini-test'),
+    },
+    getBaseLlmClient: vi.fn().mockReturnValue(
+      llmClientOverride || {
+        generateContent: vi.fn().mockResolvedValue({
+          text: '<mocked_snapshot>Synthesized state</mocked_snapshot>',
+        }),
+      },
+    ),
+    getUsageStatisticsEnabled: vi.fn().mockReturnValue(false),
+    getTargetDir: vi.fn().mockReturnValue('/tmp'),
+    getSessionId: vi.fn().mockReturnValue('test-session'),
+    getExperimentalContextManagementConfig: vi.fn().mockReturnValue(undefined),
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return { ...defaultConfig, ...overrides } as unknown as Config;
+}
+
+/**
+ * Wires up a full ContextManager component with an AgentChatHistory and active background async pipelines.
+ */
+
+export function setupContextComponentTest(
+  config: Config,
+  sidecarOverride?: ContextProfile,
+): { chatHistory: AgentChatHistory; contextManager: ContextManager } {
+  const chatHistory = new AgentChatHistory();
+  const sidecar = sidecarOverride || testTruncateProfile;
+  const tracer = new ContextTracer({
+    targetDir: '/tmp',
+    sessionId: 'test-session',
+  });
+  const eventBus = new ContextEventBus();
+  const env = new ContextEnvironmentImpl(
+    config.getBaseLlmClient(),
+    'test prompt-id',
+    'test-session',
+    '/tmp',
+    '/tmp/gemini-test',
+    tracer,
+    1,
+    eventBus,
+  );
+
+  const orchestrator = new PipelineOrchestrator(
+    sidecar.buildPipelines(env),
+    sidecar.buildAsyncPipelines(env),
+    env,
+    eventBus,
+    tracer,
+  );
+
+  const contextManager = new ContextManager(
+    sidecar,
+    env,
+    tracer,
+    orchestrator,
+    chatHistory,
+  );
+
+  // The async async pipeline is now internally managed by ContextManager
+  return { chatHistory, contextManager };
+}

packages/core/src/context/testing/testProfile.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProfile } from '../config/profiles.js';
+import type { PipelineDef } from '../config/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { createHistoryTruncationProcessor } from '../processors/historyTruncationProcessor.js';
+
+export const testTruncateProfile: ContextProfile = {
+  config: {
+    budget: {
+      retainedTokens: 65000,
+      maxTokens: 150000,
+    },
+  },
+  buildPipelines: (env: ContextEnvironment): PipelineDef[] => [
+    {
+      name: 'Emergency Backstop (Truncate Only)',
+      triggers: ['gc_backstop', 'retained_exceeded'],
+      processors: [
+        createHistoryTruncationProcessor('HistoryTruncation', env, {}),
+      ],
+    },
+  ],
+  buildAsyncPipelines: () => [],
+};

packages/core/src/context/toolOutputMaskingService.test.ts

@@ -661,4 +661,82 @@ describe('ToolOutputMaskingService', () => {
       )['output'],
     ).toContain(MASKING_INDICATOR_TAG);
   });
+
+  it('should use existing outputFile if available in the tool response', async () => {
+    // Setup: Create a large history to trigger masking
+    const largeContent = 'a'.repeat(60000);
+    const existingOutputFile = path.join(testTempDir, 'truly_full_output.txt');
+    await fs.promises.writeFile(existingOutputFile, 'truly full content');
+
+    const history: Content[] = [
+      {
+        role: 'user',
+        parts: [{ text: 'Old turn' }],
+      },
+      {
+        role: 'model',
+        parts: [
+          {
+            functionResponse: {
+              name: 'shell',
+              id: 'call-1',
+              response: {
+                output: largeContent,
+                outputFile: existingOutputFile,
+              },
+            },
+          },
+        ],
+      },
+      // Protection buffer
+      {
+        role: 'user',
+        parts: [
+          {
+            functionResponse: {
+              name: 'padding',
+              response: { output: 'B'.repeat(60000) },
+            },
+          },
+        ],
+      },
+      {
+        role: 'user',
+        parts: [{ text: 'Newest turn' }],
+      },
+    ];
+
+    mockedEstimateTokenCountSync.mockImplementation((parts: Part[]) => {
+      const resp = parts[0].functionResponse?.response as Record<
+        string,
+        unknown
+      >;
+      const content = (resp?.['output'] as string) ?? JSON.stringify(resp);
+      if (content.includes(`<${MASKING_INDICATOR_TAG}`)) return 100;
+
+      const name = parts[0].functionResponse?.name;
+      if (name === 'shell') return 60000;
+      if (name === 'padding') return 60000;
+      return 10;
+    });
+
+    // Trigger masking
+    const result = await service.mask(history, mockConfig);
+
+    expect(result.maskedCount).toBe(2);
+    const maskedPart = result.newHistory[1].parts![0];
+    const maskedResponse = maskedPart.functionResponse?.response as Record<
+      string,
+      unknown
+    >;
+    const maskedOutput = maskedResponse['output'] as string;
+
+    // Verify the masked snippet points to the existing file
+    expect(maskedOutput).toContain(
+      `Full output available at: ${existingOutputFile}`,
+    );
+
+    // Verify the path in maskedOutput is exactly the one we provided
+    expect(maskedOutput).toContain(existingOutputFile);
+  });
 });

packages/core/src/context/toolOutputMaskingService.ts

@@ -48,6 +48,18 @@ export interface MaskingResult {
   tokensSaved: number;
 }
 
+interface HasOutputFile {
+  outputFile: string;
+}
+
+function hasOutputFile(obj: unknown): obj is HasOutputFile {
+  if (typeof obj !== 'object' || obj === null || !('outputFile' in obj)) {
+    return false;
+  }
+  const val = (obj as Record<string, unknown>)['outputFile'];
+  return typeof val === 'string';
+}
+
 /**
  * Service to manage context window efficiency by masking bulky tool outputs (Tool Output Masking).
  *
@@ -182,25 +194,44 @@ export class ToolOutputMaskingService {
 
       const toolName = part.functionResponse.name || 'unknown_tool';
       const callId = part.functionResponse.id || Date.now().toString();
-      const safeToolName = sanitizeFilenamePart(toolName).toLowerCase();
-      const safeCallId = sanitizeFilenamePart(callId).toLowerCase();
-      const fileName = `${safeToolName}_${safeCallId}_${Math.random()
-        .toString(36)
-        .substring(7)}.txt`;
-      const filePath = path.join(toolOutputsDir, fileName);
-
-      await fsPromises.writeFile(filePath, content, 'utf-8');
 
       const originalResponse =
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         (part.functionResponse.response as Record<string, unknown>) || {};
 
-      const totalLines = content.split('\n').length;
-      const fileSizeMB = (
-        Buffer.byteLength(content, 'utf8') /
-        1024 /
-        1024
-      ).toFixed(2);
+      let filePath = '';
+      let fileSizeMB = '0.00';
+      let totalLines = 0;
+
+      if (hasOutputFile(originalResponse) && originalResponse.outputFile) {
+        filePath = originalResponse.outputFile;
+        try {
+          const stats = await fsPromises.stat(filePath);
+          fileSizeMB = (stats.size / 1024 / 1024).toFixed(2);
+          // For truly full files, we don't count lines as it's too slow.
+          // We just indicate it's the full file.
+          totalLines = -1;
+        } catch {
+          // Fallback if file is gone
+          filePath = '';
+        }
+      }
+
+      if (!filePath) {
+        const safeToolName = sanitizeFilenamePart(toolName).toLowerCase();
+        const safeCallId = sanitizeFilenamePart(callId).toLowerCase();
+        const fileName = `${safeToolName}_${safeCallId}_${Math.random()
+          .toString(36)
+          .substring(7)}.txt`;
+        filePath = path.join(toolOutputsDir, fileName);
+
+        await fsPromises.writeFile(filePath, content, 'utf-8');
+
+        totalLines = content.split('\n').length;
+        fileSizeMB = (Buffer.byteLength(content, 'utf8') / 1024 / 1024).toFixed(
+          2,
+        );
+      }
 
       let preview = '';
       if (toolName === SHELL_TOOL_NAME) {

packages/core/src/context/tracer.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ContextTracer } from './tracer.js';
+import * as fs from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+vi.mock('node:crypto', () => {
+  let count = 0;
+  return {
+    randomUUID: vi.fn(() => `mock-uuid-${++count}`),
+  };
+});
+
+describe('ContextTracer (Real FS & Mock ID Gen)', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gemini-tracer-test-'));
+
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T12:00:00Z'));
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('initializes, logs events, and auto-saves large assets deterministically', async () => {
+    const tracer = new ContextTracer({
+      enabled: true,
+      targetDir: tmpDir,
+      sessionId: 'test-session',
+    });
+    vi.advanceTimersByTime(10);
+    await Promise.resolve(); // allow async mkdir to happen in constructor
+
+    // Verify Initialization
+    const traceLogPath = path.join(
+      tmpDir,
+      '.gemini/context_trace/test-session/trace.log',
+    );
+    const initTraceLog = readFileSync(traceLogPath, 'utf-8');
+    expect(initTraceLog).toContain('[SYSTEM] Context Tracer Initialized');
+
+    tracer.logEvent('TestComponent', 'TestAction', { key: 'value' });
+    vi.advanceTimersByTime(10);
+    await Promise.resolve();
+
+    const smallTraceLog = readFileSync(traceLogPath, 'utf-8');
+    expect(smallTraceLog).toContain('[TestComponent] TestAction');
+    expect(smallTraceLog).toContain('{"key":"value"}');
+
+    const hugeString = 'a'.repeat(2000);
+    tracer.logEvent('TestComponent', 'LargeAction', { largeKey: hugeString });
+    vi.advanceTimersByTime(10);
+    await Promise.resolve();
+
+    const expectedAssetPath = path.join(
+      tmpDir,
+      '.gemini/context_trace/test-session/assets/1767268800020-mock-uuid-1-largeKey.json',
+    );
+    expect(existsSync(expectedAssetPath)).toBe(true);
+
+    const largeTraceLog = readFileSync(traceLogPath, 'utf-8');
+    expect(largeTraceLog).toContain('[TestComponent] LargeAction');
+    expect(largeTraceLog).toContain(
+      `{"largeKey":{"$asset":"1767268800020-mock-uuid-1-largeKey.json"}}`,
+    );
+  });
+
+  it('silently ignores logging when disabled', async () => {
+    const tracer = new ContextTracer({
+      enabled: false,
+      targetDir: tmpDir,
+      sessionId: 'test-session',
+    });
+
+    tracer.logEvent('TestComponent', 'TestAction');
+    const hugeString = 'a'.repeat(2000);
+    tracer.logEvent('TestComponent', 'LargeAction', { largeKey: hugeString });
+
+    // Nothing should be written
+    const traceDir = path.join(tmpDir, '.gemini');
+    expect(existsSync(traceDir)).toBe(false);
+  });
+});

packages/core/src/context/tracer.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { debugLogger } from '../utils/debugLogger.js';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export interface ContextTracerOptions {
+  enabled?: boolean;
+  targetDir: string;
+  sessionId: string;
+}
+
+export class ContextTracer {
+  private traceDir: string;
+  private assetsDir: string;
+  private enabled: boolean;
+
+  private readonly MAX_INLINE_SIZE = 1000;
+
+  constructor(options: ContextTracerOptions) {
+    this.enabled = options.enabled ?? false;
+
+    this.traceDir = path.join(
+      options.targetDir,
+      '.gemini',
+      'context_trace',
+      options.sessionId,
+    );
+    this.assetsDir = path.join(this.traceDir, 'assets');
+
+    if (this.enabled) {
+      try {
+        fsSync.mkdirSync(this.assetsDir, { recursive: true });
+        this.logEvent('SYSTEM', 'Context Tracer Initialized', {
+          sessionId: options.sessionId,
+        });
+      } catch (e) {
+        debugLogger.error('Failed to initialize ContextTracer', e);
+        this.enabled = false;
+      }
+    }
+  }
+
+  logEvent(
+    component: string,
+    action: string,
+    details?: Record<string, unknown>,
+  ) {
+    if (!this.enabled) return;
+    try {
+      let processedDetails: Record<string, unknown> | undefined;
+
+      if (details) {
+        processedDetails = {};
+        for (const [key, value] of Object.entries(details)) {
+          const strValue =
+            typeof value === 'string' ? value : JSON.stringify(value);
+          if (strValue && strValue.length > this.MAX_INLINE_SIZE) {
+            const assetId = this.saveAsset(component, key, value);
+            processedDetails[key] = { $asset: assetId };
+          } else {
+            processedDetails[key] = value;
+          }
+        }
+      }
+
+      const timestamp = new Date().toISOString();
+      const detailsStr = processedDetails
+        ? ` | Details: ${JSON.stringify(processedDetails)}`
+        : '';
+      const logLine = `[${timestamp}] [${component}] ${action}${detailsStr}\n`;
+      fsSync.appendFileSync(
+        path.join(this.traceDir, 'trace.log'),
+        logLine,
+        'utf-8',
+      );
+    } catch (e) {
+      debugLogger.warn(`Tracing failed: ${e}`);
+    }
+  }
+
+  private saveAsset(
+    component: string,
+    assetName: string,
+    data: unknown,
+  ): string {
+    if (!this.enabled) return 'asset-recording-disabled';
+    try {
+      const assetId = `${Date.now()}-${randomUUID()}-${assetName}.json`;
+      const assetPath = path.join(this.assetsDir, assetId);
+
+      fsSync.writeFileSync(assetPath, JSON.stringify(data, null, 2), 'utf-8');
+      this.logEvent(component, `Saved asset: ${assetName}`, { assetId });
+      return assetId;
+    } catch (e) {
+      this.logEvent(component, `Failed to save asset: ${assetName}`, {
+        error: String(e),
+      });
+      return 'asset-save-failed';
+    }
+  }
+}

packages/core/src/context/utils/contextTokenCalculator.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Part } from '@google/genai';
+import { estimateTokenCountSync as baseEstimate } from '../../utils/tokenCalculation.js';
+import type { ConcreteNode } from '../graph/types.js';
+import type { NodeBehaviorRegistry } from '../graph/behaviorRegistry.js';
+
+/**
+ * The flat token cost assigned to a single multi-modal asset (like an image tile)
+ * by the Gemini API. We use this as a baseline heuristic for inlineData/fileData.
+ */
+
+export class ContextTokenCalculator {
+  private readonly tokenCache = new Map<string, number>();
+
+  constructor(
+    private readonly charsPerToken: number,
+    private readonly registry: NodeBehaviorRegistry,
+  ) {}
+
+  /**
+   * Estimates tokens for a simple string based on character count.
+   * Fast, but inherently inaccurate compared to real model tokenization.
+   */
+  estimateTokensForString(text: string): number {
+    return Math.ceil(text.length / this.charsPerToken);
+  }
+
+  /**
+   * Fast, simple heuristic conversion from tokens to expected character length.
+   * Useful for calculating truncation thresholds.
+   */
+  tokensToChars(tokens: number): number {
+    return tokens * this.charsPerToken;
+  }
+
+  /**
+   * Pre-calculates and caches the token cost of a newly minted node.
+   * Because nodes are immutable, this cost never changes for this node ID.
+   */
+
+  /**
+   * Removes cached token counts for any nodes that are no longer in the given live set.
+   * This prevents unbounded memory growth during long sessions.
+   */
+  garbageCollectCache(liveNodeIds: ReadonlySet<string>): void {
+    for (const [id] of this.tokenCache) {
+      if (!liveNodeIds.has(id)) {
+        this.tokenCache.delete(id);
+      }
+    }
+  }
+
+  cacheNodeTokens(node: ConcreteNode): number {
+    const behavior = this.registry.get(node.type);
+    const parts = behavior.getEstimatableParts(node);
+    const tokens = this.estimateTokensForParts(parts);
+    this.tokenCache.set(node.id, tokens);
+    return tokens;
+  }
+
+  /**
+   * Retrieves the token cost of a single node from the cache.
+   * If it misses the cache, it computes it and caches it.
+   */
+  getTokenCost(node: ConcreteNode): number {
+    const cached = this.tokenCache.get(node.id);
+    if (cached !== undefined) return cached;
+    return this.cacheNodeTokens(node);
+  }
+
+  /**
+   * Fast calculation for a flat array of ConcreteNodes (The Nodes).
+   * It relies entirely on the O(1) sidecar token cache.
+   */
+  calculateConcreteListTokens(nodes: readonly ConcreteNode[]): number {
+    let tokens = 0;
+    for (const node of nodes) {
+      tokens += this.getTokenCost(node);
+    }
+    return tokens;
+  }
+  /**
+   * Slower, precise estimation for a Gemini Content/Part graph.
+   * Deeply inspects the nested structure and uses the base tokenization math.
+   */
+  estimateTokensForParts(parts: Part[], depth: number = 0): number {
+    let totalTokens = 0;
+    for (const part of parts) {
+      if (typeof part.text === 'string') {
+        totalTokens += Math.ceil(part.text.length / this.charsPerToken);
+      } else if (part.inlineData !== undefined || part.fileData !== undefined) {
+        totalTokens += 258;
+      } else {
+        totalTokens += Math.ceil(
+          JSON.stringify(part).length / this.charsPerToken,
+        );
+      }
+    }
+    // Also include structural overhead
+    return totalTokens + baseEstimate(parts, depth);
+  }
+}

packages/core/src/context/utils/snapshotGenerator.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ConcreteNode } from '../graph/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { LlmRole } from '../../telemetry/llmRole.js';
+
+export class SnapshotGenerator {
+  constructor(private readonly env: ContextEnvironment) {}
+
+  async synthesizeSnapshot(
+    nodes: readonly ConcreteNode[],
+    systemInstruction?: string,
+  ): Promise<string> {
+    const systemPrompt =
+      systemInstruction ??
+      `You are an expert Context Memory Manager. You will be provided with a raw transcript of older conversation turns between a user and an AI assistant.
+Your task is to synthesize these turns into a single, dense, factual snapshot that preserves all critical context, preferences, active tasks, and factual knowledge, but discards conversational filler, pleasantries, and redundant back-and-forth iterations.
+
+Output ONLY the raw factual snapshot, formatted compactly. Do not include markdown wrappers, prefixes like "Here is the snapshot", or conversational elements.`;
+
+    let userPromptText = 'TRANSCRIPT TO SNAPSHOT:\n\n';
+    for (const node of nodes) {
+      let nodeContent = '';
+      if ('text' in node && typeof node.text === 'string') {
+        nodeContent = node.text;
+      } else if ('semanticParts' in node) {
+        nodeContent = JSON.stringify(node.semanticParts);
+      } else if ('observation' in node) {
+        nodeContent =
+          typeof node.observation === 'string'
+            ? node.observation
+            : JSON.stringify(node.observation);
+      }
+
+      userPromptText += `[${node.type}]: ${nodeContent}\n`;
+    }
+
+    const response = await this.env.llmClient.generateContent({
+      role: LlmRole.UTILITY_STATE_SNAPSHOT_PROCESSOR,
+      modelConfigKey: { model: 'gemini-3-flash-base' },
+      contents: [{ role: 'user', parts: [{ text: userPromptText }] }],
+      systemInstruction: { role: 'system', parts: [{ text: systemPrompt }] },
+      promptId: this.env.promptId,
+      abortSignal: new AbortController().signal,
+    });
+
+    const candidate = response.candidates?.[0];
+    const textPart = candidate?.content?.parts?.[0];
+    return textPart?.text || '';
+  }
+}

packages/core/src/core/__snapshots__/prompts.test.ts.snap

@@ -119,6 +119,7 @@ The following tools are available in Plan Mode:
    - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
 5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
 6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use \`exit_plan_mode\` to request approval.
+7. **Presenting Plan:** When seeking informal agreement on a plan, or any time the user asks to see the plan, you MUST output the full content of the plan in the chat response. This overrides the "Minimal Output" guideline.
 
 ## Planning Workflow
 Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
@@ -139,6 +140,7 @@ Write the implementation plan to \`/tmp/plans/\`. The plan's structure adapts to
 - **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
 - **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
 - **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+- **Alignment Check:** After drafting the plan, you MUST present it to the user in the chat (adhering to Rule 7 for presenting plans) to ensure alignment on the specific details. Ask for feedback or confirmation, and proceed to Step 4 (Review & Approval) once the user agrees with the detailed plan.
 
 ### 4. Review & Approval
 ONLY use the \`exit_plan_mode\` tool to present the plan for formal approval AFTER you have reached an informal agreement with the user in the chat regarding the proposed strategy. When called, this tool will present the plan and formally request approval.
@@ -297,6 +299,7 @@ The following tools are available in Plan Mode:
    - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
 5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
 6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use \`exit_plan_mode\` to request approval.
+7. **Presenting Plan:** When seeking informal agreement on a plan, or any time the user asks to see the plan, you MUST output the full content of the plan in the chat response. This overrides the "Minimal Output" guideline.
 
 ## Planning Workflow
 Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
@@ -317,6 +320,7 @@ Write the implementation plan to \`/tmp/plans/\`. The plan's structure adapts to
 - **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
 - **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
 - **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+- **Alignment Check:** After drafting the plan, you MUST present it to the user in the chat (adhering to Rule 7 for presenting plans) to ensure alignment on the specific details. Ask for feedback or confirmation, and proceed to Step 4 (Review & Approval) once the user agrees with the detailed plan.
 
 ### 4. Review & Approval
 ONLY use the \`exit_plan_mode\` tool to present the plan for formal approval AFTER you have reached an informal agreement with the user in the chat regarding the proposed strategy. When called, this tool will present the plan and formally request approval.
@@ -596,6 +600,7 @@ The following tools are available in Plan Mode:
    - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
 5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
 6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use \`exit_plan_mode\` to request approval.
+7. **Presenting Plan:** When seeking informal agreement on a plan, or any time the user asks to see the plan, you MUST output the full content of the plan in the chat response. This overrides the "Minimal Output" guideline.
 
 ## Planning Workflow
 Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
@@ -616,6 +621,7 @@ Write the implementation plan to \`/tmp/project-temp/plans/\`. The plan's struct
 - **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
 - **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
 - **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+- **Alignment Check:** After drafting the plan, you MUST present it to the user in the chat (adhering to Rule 7 for presenting plans) to ensure alignment on the specific details. Ask for feedback or confirmation, and proceed to Step 4 (Review & Approval) once the user agrees with the detailed plan.
 
 ### 4. Review & Approval
 ONLY use the \`exit_plan_mode\` tool to present the plan for formal approval AFTER you have reached an informal agreement with the user in the chat regarding the proposed strategy. When called, this tool will present the plan and formally request approval.

packages/core/src/core/agentChatHistory.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/genai';
+
+export type HistoryEventType = 'PUSH' | 'SYNC_FULL' | 'CLEAR';
+
+export interface HistoryEvent {
+  type: HistoryEventType;
+  payload: readonly Content[];
+}
+
+export type HistoryListener = (event: HistoryEvent) => void;
+
+export class AgentChatHistory {
+  private history: Content[];
+  private listeners: Set<HistoryListener> = new Set();
+
+  constructor(initialHistory: Content[] = []) {
+    this.history = [...initialHistory];
+  }
+
+  subscribe(listener: HistoryListener): () => void {
+    this.listeners.add(listener);
+    // Emit initial state to new subscriber
+    listener({ type: 'SYNC_FULL', payload: this.history });
+    return () => this.listeners.delete(listener);
+  }
+
+  private notify(type: HistoryEventType, payload: readonly Content[]) {
+    const event: HistoryEvent = { type, payload };
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+
+  push(content: Content) {
+    this.history.push(content);
+    this.notify('PUSH', [content]);
+  }
+
+  set(history: readonly Content[]) {
+    this.history = [...history];
+    this.notify('SYNC_FULL', this.history);
+  }
+
+  clear() {
+    this.history = [];
+    this.notify('CLEAR', []);
+  }
+
+  get(): readonly Content[] {
+    return this.history;
+  }
+
+  map(callback: (value: Content, index: number, array: Content[]) => Content) {
+    this.history = this.history.map(callback);
+    this.notify('SYNC_FULL', this.history);
+  }
+
+  flatMap<U>(
+    callback: (
+      value: Content,
+      index: number,
+      array: Content[],
+    ) => U | readonly U[],
+  ): U[] {
+    return this.history.flatMap(callback);
+  }
+
+  get length(): number {
+    return this.history.length;
+  }
+}

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

@@ -148,7 +148,7 @@ describe('createContentGenerator', () => {
     );
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.stringMatching(
@@ -365,7 +365,7 @@ describe('createContentGenerator', () => {
 
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.any(String),
@@ -409,7 +409,7 @@ describe('createContentGenerator', () => {
 
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.any(String),
@@ -443,7 +443,7 @@ describe('createContentGenerator', () => {
 
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.any(String),
@@ -481,7 +481,7 @@ describe('createContentGenerator', () => {
     );
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: {
           'User-Agent': expect.any(String),
@@ -517,7 +517,7 @@ describe('createContentGenerator', () => {
 
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.any(String),
@@ -550,7 +550,7 @@ describe('createContentGenerator', () => {
 
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.any(String),
@@ -589,7 +589,7 @@ describe('createContentGenerator', () => {
 
     expect(GoogleGenAI).toHaveBeenCalledWith({
       apiKey: 'test-api-key',
-      vertexai: undefined,
+      vertexai: false,
       httpOptions: expect.objectContaining({
         headers: expect.objectContaining({
           'User-Agent': expect.any(String),
@@ -638,6 +638,193 @@ describe('createContentGenerator', () => {
       apiVersion: 'v1alpha',
     });
   });
+
+  it('should pass baseUrl to GoogleGenAI when GOOGLE_GEMINI_BASE_URL is set', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => false,
+      getClientName: vi.fn().mockReturnValue(undefined),
+    } as unknown as Config;
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+    vi.stubEnv('GOOGLE_GEMINI_BASE_URL', 'https://gemini.test.local');
+    vi.stubEnv('GEMINI_API_KEY', 'test-api-key');
+
+    const config = await createContentGeneratorConfig(
+      mockConfig,
+      AuthType.USE_GEMINI,
+    );
+    await createContentGenerator(config, mockConfig);
+
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: 'test-api-key',
+        vertexai: false,
+        httpOptions: expect.objectContaining({
+          baseUrl: 'https://gemini.test.local',
+        }),
+      }),
+    );
+  });
+
+  it('should pass baseUrl to GoogleGenAI when GOOGLE_VERTEX_BASE_URL is set', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => false,
+      getClientName: vi.fn().mockReturnValue(undefined),
+    } as unknown as Config;
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+    vi.stubEnv('GOOGLE_VERTEX_BASE_URL', 'https://vertex.test.local');
+    vi.stubEnv('GOOGLE_CLOUD_PROJECT', 'my-project');
+    vi.stubEnv('GOOGLE_CLOUD_LOCATION', 'us-central1');
+
+    const config = await createContentGeneratorConfig(
+      mockConfig,
+      AuthType.USE_VERTEX_AI,
+    );
+    await createContentGenerator(config, mockConfig);
+
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: undefined,
+        vertexai: true,
+        httpOptions: expect.objectContaining({
+          baseUrl: 'https://vertex.test.local',
+        }),
+      }),
+    );
+  });
+
+  it('should prefer GOOGLE_VERTEX_BASE_URL when authType is USE_VERTEX_AI without inferred vertex credentials', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => false,
+      getClientName: vi.fn().mockReturnValue(undefined),
+    } as unknown as Config;
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+    vi.stubEnv('GOOGLE_GEMINI_BASE_URL', 'https://gemini.test.local');
+    vi.stubEnv('GOOGLE_VERTEX_BASE_URL', 'https://vertex.test.local');
+
+    await createContentGenerator(
+      {
+        authType: AuthType.USE_VERTEX_AI,
+      },
+      mockConfig,
+    );
+
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: undefined,
+        vertexai: true,
+        httpOptions: expect.objectContaining({
+          baseUrl: 'https://vertex.test.local',
+        }),
+      }),
+    );
+  });
+
+  it('should prefer an explicit baseUrl over GOOGLE_GEMINI_BASE_URL', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => false,
+      getClientName: vi.fn().mockReturnValue(undefined),
+    } as unknown as Config;
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+    vi.stubEnv('GOOGLE_GEMINI_BASE_URL', 'https://env.test.local');
+    vi.stubEnv('GEMINI_API_KEY', 'test-api-key');
+
+    const config = await createContentGeneratorConfig(
+      mockConfig,
+      AuthType.USE_GEMINI,
+      undefined,
+      'https://explicit.test.local',
+    );
+    await createContentGenerator(config, mockConfig);
+
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpOptions: expect.objectContaining({
+          baseUrl: 'https://explicit.test.local',
+        }),
+      }),
+    );
+  });
+
+  it('should allow localhost baseUrl overrides over http', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => false,
+      getClientName: vi.fn().mockReturnValue(undefined),
+    } as unknown as Config;
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+
+    await createContentGenerator(
+      {
+        apiKey: 'test-api-key',
+        authType: AuthType.USE_GEMINI,
+        baseUrl: 'http://127.0.0.1:8080',
+      },
+      mockConfig,
+    );
+
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpOptions: expect.objectContaining({
+          baseUrl: 'http://127.0.0.1:8080',
+        }),
+      }),
+    );
+  });
+
+  it('should reject invalid custom baseUrl values', async () => {
+    await expect(
+      createContentGenerator(
+        {
+          apiKey: 'test-api-key',
+          authType: AuthType.USE_GEMINI,
+          baseUrl: 'not-a-url',
+        },
+        mockConfig,
+      ),
+    ).rejects.toThrow('Invalid custom base URL: not-a-url');
+  });
+
+  it('should reject non-https remote custom baseUrl values', async () => {
+    await expect(
+      createContentGenerator(
+        {
+          apiKey: 'test-api-key',
+          authType: AuthType.USE_GEMINI,
+          baseUrl: 'http://example.com',
+        },
+        mockConfig,
+      ),
+    ).rejects.toThrow('Custom base URL must use HTTPS unless it is localhost.');
+  });
 });
 
 describe('createContentGeneratorConfig', () => {

packages/core/src/core/contentGenerator.ts

@@ -101,6 +101,21 @@ export type ContentGeneratorConfig = {
   customHeaders?: Record<string, string>;
 };
 
+const LOCAL_HOSTNAMES = ['localhost', '127.0.0.1', '[::1]'];
+
+function validateBaseUrl(baseUrl: string): void {
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid custom base URL: ${baseUrl}`);
+  }
+
+  if (url.protocol !== 'https:' && !LOCAL_HOSTNAMES.includes(url.hostname)) {
+    throw new Error('Custom base URL must use HTTPS unless it is localhost.');
+  }
+}
+
 export async function createContentGeneratorConfig(
   config: Config,
   authType: AuthType | undefined,
@@ -273,18 +288,32 @@ export async function createContentGenerator(
           'x-gemini-api-privileged-user-id': `${installationId}`,
         };
       }
+      let baseUrl = config.baseUrl;
+      if (!baseUrl) {
+        const envBaseUrl =
+          config.authType === AuthType.USE_VERTEX_AI
+            ? process.env['GOOGLE_VERTEX_BASE_URL']
+            : process.env['GOOGLE_GEMINI_BASE_URL'];
+        if (envBaseUrl) {
+          validateBaseUrl(envBaseUrl);
+          baseUrl = envBaseUrl;
+        }
+      } else {
+        validateBaseUrl(baseUrl);
+      }
+
       const httpOptions: {
         baseUrl?: string;
         headers: Record<string, string>;
       } = { headers };
 
-      if (config.baseUrl) {
-        httpOptions.baseUrl = config.baseUrl;
+      if (baseUrl) {
+        httpOptions.baseUrl = baseUrl;
       }
 
       const googleGenAI = new GoogleGenAI({
         apiKey: config.apiKey === '' ? undefined : config.apiKey,
-        vertexai: config.vertexai,
+        vertexai: config.vertexai ?? config.authType === AuthType.USE_VERTEX_AI,
         httpOptions,
         ...(apiVersionEnv && { apiVersion: apiVersionEnv }),
       });