@google/gemini-cli-core 0.48.0-preview.0 → 0.49.0-preview.0

package/dist/docs/reference/configuration.md

@@ -106,6 +106,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `general`
 
 - **`general.preferredEditor`** (enum):
+
   - **Description:** The preferred editor to open files in. Must be one of the
     built-in supported identifiers. Use /editor in the CLI to pick
     interactively, or leave unset to use $VISUAL/$EDITOR.
@@ -115,15 +116,18 @@ their corresponding top-level category object in your `settings.json` file.
     `"neovim"`, `"emacs"`, `"hx"`, `"emacsclient"`, `"micro"`
 
 - **`general.openEditorInNewWindow`** (boolean):
+
   - **Description:** Open VS Code-family editors in a new window when editing
     files.
   - **Default:** `false`
 
 - **`general.vimMode`** (boolean):
+
   - **Description:** Enable Vim keybindings
   - **Default:** `false`
 
 - **`general.defaultApprovalMode`** (enum):
+
   - **Description:** The default approval mode for tool execution. 'default'
     prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is
     read-only mode. YOLO mode (auto-approve all actions) can only be enabled via
@@ -132,38 +136,46 @@ their corresponding top-level category object in your `settings.json` file.
   - **Values:** `"default"`, `"auto_edit"`, `"plan"`
 
 - **`general.devtools`** (boolean):
+
   - **Description:** Enable DevTools inspector on launch.
   - **Default:** `false`
 
 - **`general.enableAutoUpdate`** (boolean):
+
   - **Description:** Enable automatic updates.
   - **Default:** `true`
 
 - **`general.enableAutoUpdateNotification`** (boolean):
+
   - **Description:** Enable update notification prompts.
   - **Default:** `true`
 
 - **`general.enableNotifications`** (boolean):
+
   - **Description:** Enable terminal run-event notifications for action-required
     prompts and session completion.
   - **Default:** `false`
 
 - **`general.notificationMethod`** (enum):
+
   - **Description:** How to send terminal notifications.
   - **Default:** `"auto"`
   - **Values:** `"auto"`, `"osc9"`, `"osc777"`, `"bell"`
 
 - **`general.checkpointing.enabled`** (boolean):
+
   - **Description:** Enable session checkpointing for recovery
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`general.plan.enabled`** (boolean):
+
   - **Description:** Enable Plan Mode for read-only safety during planning.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`general.plan.directory`** (string):
+
   - **Description:** The directory where planning artifacts are stored. If not
     specified, defaults to the system temporary directory. A custom directory
     requires a policy to allow write access in Plan Mode.
@@ -171,44 +183,53 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`general.plan.modelRouting`** (boolean):
+
   - **Description:** Automatically switch between Pro and Flash models based on
     Plan Mode status. Uses Pro for the planning phase and Flash for the
     implementation phase.
   - **Default:** `true`
 
 - **`general.retryFetchErrors`** (boolean):
+
   - **Description:** Retry on "exception TypeError: fetch failed sending
     request" errors.
   - **Default:** `true`
 
 - **`general.maxAttempts`** (number):
+
   - **Description:** Maximum number of attempts for requests to the main chat
     model. Cannot exceed 10.
   - **Default:** `10`
 
 - **`general.debugKeystrokeLogging`** (boolean):
+
   - **Description:** Enable debug logging of keystrokes to the console.
   - **Default:** `false`
 
 - **`general.sessionRetention.enabled`** (boolean):
+
   - **Description:** Enable automatic session cleanup
   - **Default:** `true`
 
 - **`general.sessionRetention.maxAge`** (string):
+
   - **Description:** Automatically delete chats older than this time period
     (e.g., "30d", "7d", "24h", "1w")
   - **Default:** `"30d"`
 
 - **`general.sessionRetention.maxCount`** (number):
+
   - **Description:** Alternative: Maximum number of sessions to keep (most
     recent)
   - **Default:** `undefined`
 
 - **`general.sessionRetention.minRetention`** (string):
+
   - **Description:** Minimum retention period (safety limit, defaults to "1d")
   - **Default:** `"1d"`
 
 - **`general.topicUpdateNarration`** (boolean):
+
   - **Description:** Enable the Topic & Update communication model for reduced
     chattiness and structured progress reporting.
   - **Default:** `true`
@@ -228,163 +249,198 @@ their corresponding top-level category object in your `settings.json` file.
 #### `ui`
 
 - **`ui.debugRainbow`** (boolean):
+
   - **Description:** Enable debug rainbow rendering. Only useful for debugging
     rendering bugs and performance issues.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`ui.theme`** (string):
+
   - **Description:** The color theme for the UI. See the CLI themes guide for
     available options.
   - **Default:** `undefined`
 
 - **`ui.autoThemeSwitching`** (boolean):
+
   - **Description:** Automatically switch between default light and dark themes
     based on terminal background color.
   - **Default:** `true`
 
 - **`ui.terminalBackgroundPollingInterval`** (number):
+
   - **Description:** Interval in seconds to poll the terminal background color.
   - **Default:** `60`
 
 - **`ui.customThemes`** (object):
+
   - **Description:** Custom theme definitions.
   - **Default:** `{}`
 
 - **`ui.hideWindowTitle`** (boolean):
+
   - **Description:** Hide the window title bar
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`ui.inlineThinkingMode`** (enum):
+
   - **Description:** Display model thinking inline: off or full.
   - **Default:** `"off"`
   - **Values:** `"off"`, `"full"`
 
 - **`ui.showStatusInTitle`** (boolean):
+
   - **Description:** Show Gemini CLI model thoughts in the terminal window title
     during the working phase
   - **Default:** `false`
 
 - **`ui.dynamicWindowTitle`** (boolean):
+
   - **Description:** Update the terminal window title with current status icons
     (Ready: ◇, Action Required: ✋, Working: ✦)
   - **Default:** `true`
 
 - **`ui.showHomeDirectoryWarning`** (boolean):
+
   - **Description:** Show a warning when running Gemini CLI in the home
     directory.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`ui.showCompatibilityWarnings`** (boolean):
+
   - **Description:** Show warnings about terminal or OS compatibility issues.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`ui.hideTips`** (boolean):
+
   - **Description:** Hide helpful tips in the UI
   - **Default:** `false`
 
 - **`ui.escapePastedAtSymbols`** (boolean):
+
   - **Description:** When enabled, @ symbols in pasted text are escaped to
     prevent unintended @path expansion.
   - **Default:** `false`
 
 - **`ui.showShortcutsHint`** (boolean):
+
   - **Description:** Show the "? for shortcuts" hint above the input.
   - **Default:** `true`
 
 - **`ui.compactToolOutput`** (boolean):
+
   - **Description:** Display tool outputs (like directory listings and file
     reads) in a compact, structured format.
   - **Default:** `true`
 
 - **`ui.hideBanner`** (boolean):
+
   - **Description:** Hide the application banner
   - **Default:** `false`
 
 - **`ui.hideContextSummary`** (boolean):
+
   - **Description:** Hide the context summary (GEMINI.md, MCP servers) above the
     input.
   - **Default:** `false`
 
 - **`ui.footer.items`** (array):
+
   - **Description:** List of item IDs to display in the footer. Rendered in
     order
   - **Default:** `undefined`
 
 - **`ui.footer.showLabels`** (boolean):
+
   - **Description:** Display a second line above the footer items with
     descriptive headers (e.g., /model).
   - **Default:** `true`
 
 - **`ui.footer.hideCWD`** (boolean):
+
   - **Description:** Hide the current working directory in the footer.
   - **Default:** `false`
 
 - **`ui.footer.hideSandboxStatus`** (boolean):
+
   - **Description:** Hide the sandbox status indicator in the footer.
   - **Default:** `false`
 
 - **`ui.footer.hideModelInfo`** (boolean):
+
   - **Description:** Hide the model name and context usage in the footer.
   - **Default:** `false`
 
 - **`ui.footer.hideContextPercentage`** (boolean):
+
   - **Description:** Hides the context window usage percentage.
   - **Default:** `true`
 
 - **`ui.hideFooter`** (boolean):
+
   - **Description:** Hide the footer from the UI
   - **Default:** `false`
 
 - **`ui.collapseDrawerDuringApproval`** (boolean):
+
   - **Description:** Whether to collapse the UI drawer when a tool is awaiting
     confirmation.
   - **Default:** `true`
 
 - **`ui.showMemoryUsage`** (boolean):
+
   - **Description:** Display memory usage information in the UI
   - **Default:** `false`
 
 - **`ui.showLineNumbers`** (boolean):
+
   - **Description:** Show line numbers in the chat.
   - **Default:** `true`
 
 - **`ui.showCitations`** (boolean):
+
   - **Description:** Show citations for generated text in the chat.
   - **Default:** `false`
 
 - **`ui.showModelInfoInChat`** (boolean):
+
   - **Description:** Show the model name in the chat for each model turn.
   - **Default:** `false`
 
 - **`ui.showUserIdentity`** (boolean):
+
   - **Description:** Show the signed-in user's identity (e.g. email) in the UI.
   - **Default:** `true`
 
 - **`ui.useAlternateBuffer`** (boolean):
+
   - **Description:** Use an alternate screen buffer for the UI, preserving shell
     history.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`ui.renderProcess`** (boolean):
+
   - **Description:** Enable Ink render process for the UI.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`ui.terminalBuffer`** (boolean):
+
   - **Description:** Use the new terminal buffer architecture for rendering.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`ui.useBackgroundColor`** (boolean):
+
   - **Description:** Whether to use background colors in the UI.
   - **Default:** `true`
 
 - **`ui.incrementalRendering`** (boolean):
+
   - **Description:** Enable incremental rendering for the UI. This option will
     reduce flickering but may cause rendering artifacts. Only supported when
     useAlternateBuffer is enabled.
@@ -392,27 +448,32 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`ui.showSpinner`** (boolean):
+
   - **Description:** Show the spinner during operations.
   - **Default:** `true`
 
 - **`ui.loadingPhrases`** (enum):
+
   - **Description:** What to show while the model is working: tips, witty
     comments, all, or off.
   - **Default:** `"off"`
   - **Values:** `"tips"`, `"witty"`, `"all"`, `"off"`
 
 - **`ui.errorVerbosity`** (enum):
+
   - **Description:** Controls whether recoverable errors are hidden (low) or
     fully shown (full).
   - **Default:** `"low"`
   - **Values:** `"low"`, `"full"`
 
 - **`ui.customWittyPhrases`** (array):
+
   - **Description:** Custom witty phrases to display during loading. When
     provided, the CLI cycles through these instead of the defaults.
   - **Default:** `[]`
 
 - **`ui.accessibility.enableLoadingPhrases`** (boolean):
+
   - **Description:** @deprecated Use ui.loadingPhrases instead. Enable loading
     phrases during operations.
   - **Default:** `true`
@@ -427,6 +488,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `ide`
 
 - **`ide.enabled`** (boolean):
+
   - **Description:** Enable IDE integration mode.
   - **Default:** `false`
   - **Requires restart:** Yes
@@ -445,6 +507,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `billing`
 
 - **`billing.overageStrategy`** (enum):
+
   - **Description:** How to handle quota exhaustion when AI credits are
     available. 'ask' prompts each time, 'always' automatically uses credits,
     'never' disables credit usage.
@@ -452,6 +515,7 @@ their corresponding top-level category object in your `settings.json` file.
   - **Values:** `"ask"`, `"always"`, `"never"`
 
 - **`billing.vertexAi.requestType`** (enum):
+
   - **Description:** Sets the X-Vertex-AI-LLM-Request-Type header for Vertex AI
     requests.
   - **Default:** `undefined`
@@ -468,27 +532,32 @@ their corresponding top-level category object in your `settings.json` file.
 #### `model`
 
 - **`model.name`** (string):
+
   - **Description:** The Gemini model to use for conversations.
   - **Default:** `undefined`
 
 - **`model.maxSessionTurns`** (number):
+
   - **Description:** Maximum number of user/model/tool turns to keep in a
     session. -1 means unlimited.
   - **Default:** `-1`
 
 - **`model.summarizeToolOutput`** (object):
+
   - **Description:** Enables or disables summarization of tool output. Configure
     per-tool token budgets (for example {"run_shell_command": {"tokenBudget":
     2000}}). Currently only the run_shell_command tool supports summarization.
   - **Default:** `undefined`
 
 - **`model.compressionThreshold`** (number):
+
   - **Description:** The fraction of context usage at which to trigger context
     compression (e.g. 0.2, 0.3).
   - **Default:** `0.5`
   - **Requires restart:** Yes
 
 - **`model.disableLoopDetection`** (boolean):
+
   - **Description:** Disable automatic detection and prevention of infinite
     loops.
   - **Default:** `false`
@@ -501,6 +570,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `modelConfigs`
 
 - **`modelConfigs.aliases`** (object):
+
   - **Description:** Named presets for model configs. Can be used in place of a
     model name and can inherit from other aliases using an `extends` property.
   - **Default:**
@@ -808,22 +878,26 @@ their corresponding top-level category object in your `settings.json` file.
     ```
 
 - **`modelConfigs.customAliases`** (object):
+
   - **Description:** Custom named presets for model configs. These are merged
     with (and override) the built-in aliases.
   - **Default:** `{}`
 
 - **`modelConfigs.customOverrides`** (array):
+
   - **Description:** Custom model config overrides. These are merged with (and
     added to) the built-in overrides.
   - **Default:** `[]`
 
 - **`modelConfigs.overrides`** (array):
+
   - **Description:** Apply specific configuration overrides based on matches,
     with a primary key of model (or alias). The most specific match will be
     used.
   - **Default:** `[]`
 
 - **`modelConfigs.modelDefinitions`** (object):
+
   - **Description:** Registry of model metadata, including tier, family, and
     features.
   - **Default:**
@@ -997,6 +1071,7 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`modelConfigs.modelIdResolutions`** (object):
+
   - **Description:** Rules for resolving requested model names to concrete model
     IDs based on context.
   - **Default:**
@@ -1213,6 +1288,7 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`modelConfigs.classifierIdResolutions`** (object):
+
   - **Description:** Rules for resolving classifier tiers (flash, pro) to
     concrete model IDs.
   - **Default:**
@@ -1278,6 +1354,7 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`modelConfigs.modelChains`** (object):
+
   - **Description:** Availability policy chains defining fallback behavior for
     models.
   - **Default:**
@@ -1478,34 +1555,40 @@ their corresponding top-level category object in your `settings.json` file.
 #### `agents`
 
 - **`agents.overrides`** (object):
+
   - **Description:** Override settings for specific agents, e.g. to disable the
     agent, set a custom model config, or run config.
   - **Default:** `{}`
   - **Requires restart:** Yes
 
 - **`agents.browser.sessionMode`** (enum):
+
   - **Description:** Session mode: 'persistent', 'isolated', or 'existing'.
   - **Default:** `"persistent"`
   - **Values:** `"persistent"`, `"isolated"`, `"existing"`
   - **Requires restart:** Yes
 
 - **`agents.browser.headless`** (boolean):
+
   - **Description:** Run browser in headless mode.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`agents.browser.profilePath`** (string):
+
   - **Description:** Path to browser profile directory for session persistence.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`agents.browser.visualModel`** (string):
+
   - **Description:** Model for the visual agent's analyze_screenshot tool. When
     set, enables the tool.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`agents.browser.allowedDomains`** (array):
+
   - **Description:** A list of allowed domains for the browser agent (e.g.,
     ["github.com", "*.google.com"]).
   - **Default:**
@@ -1517,15 +1600,18 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`agents.browser.disableUserInput`** (boolean):
+
   - **Description:** Disable user input on browser window during automation.
   - **Default:** `true`
 
 - **`agents.browser.maxActionsPerTask`** (number):
+
   - **Description:** The maximum number of tool calls allowed per browser task.
     Enforcement is hard: the agent will be terminated when the limit is reached.
   - **Default:** `100`
 
 - **`agents.browser.confirmSensitiveActions`** (boolean):
+
   - **Description:** Require manual confirmation for sensitive browser actions
     (e.g., fill_form, evaluate_script).
   - **Default:** `false`
@@ -1539,24 +1625,29 @@ their corresponding top-level category object in your `settings.json` file.
 #### `context`
 
 - **`context.fileName`** (string | string[]):
+
   - **Description:** The name of the context file or files to load into memory.
     Accepts either a single string or an array of strings.
   - **Default:** `undefined`
 
 - **`context.importFormat`** (string):
+
   - **Description:** The format to use when importing memory.
   - **Default:** `undefined`
 
 - **`context.includeDirectoryTree`** (boolean):
+
   - **Description:** Whether to include the directory tree of the current
     working directory in the initial request to the model.
   - **Default:** `true`
 
 - **`context.discoveryMaxDirs`** (number):
+
   - **Description:** Maximum number of directories to search for memory.
   - **Default:** `200`
 
 - **`context.memoryBoundaryMarkers`** (array):
+
   - **Description:** File or directory names that mark the boundary for
     GEMINI.md discovery. The upward traversal stops at the first directory
     containing any of these markers. An empty array disables parent traversal.
@@ -1569,39 +1660,46 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`context.includeDirectories`** (array):
+
   - **Description:** Additional directories to include in the workspace context.
     Missing directories will be skipped with a warning.
   - **Default:** `[]`
 
 - **`context.loadMemoryFromIncludeDirectories`** (boolean):
+
   - **Description:** Controls how /memory reload loads GEMINI.md files. When
     true, include directories are scanned; when false, only the current
     directory is used.
   - **Default:** `false`
 
 - **`context.fileFiltering.respectGitIgnore`** (boolean):
+
   - **Description:** Respect .gitignore files when searching.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`context.fileFiltering.respectGeminiIgnore`** (boolean):
+
   - **Description:** Respect .geminiignore files when searching.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`context.fileFiltering.enableFileWatcher`** (boolean):
+
   - **Description:** Enable file watcher updates for @ file suggestions
     (experimental).
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`context.fileFiltering.enableRecursiveFileSearch`** (boolean):
+
   - **Description:** Enable recursive file search functionality when completing
     @ references in the prompt.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`context.fileFiltering.enableFuzzySearch`** (boolean):
+
   - **Description:** Enable fuzzy search when searching for files.
   - **Default:** `true`
   - **Requires restart:** Yes
@@ -1617,6 +1715,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `tools`
 
 - **`tools.sandbox`** (string):
+
   - **Description:** Legacy full-process sandbox execution environment. Set to a
     boolean to enable or disable the sandbox, provide a string path to a sandbox
     profile, or specify an explicit sandbox command (e.g., "docker", "podman",
@@ -1625,23 +1724,27 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`tools.sandboxAllowedPaths`** (array):
+
   - **Description:** List of additional paths that the sandbox is allowed to
     access.
   - **Default:** `[]`
   - **Requires restart:** Yes
 
 - **`tools.sandboxNetworkAccess`** (boolean):
+
   - **Description:** Whether the sandbox is allowed to access the network.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`tools.shell.enableInteractiveShell`** (boolean):
+
   - **Description:** Use node-pty for an interactive shell experience. Fallback
     to child_process still applies.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`tools.shell.backgroundCompletionBehavior`** (enum):
+
   - **Description:** Controls what happens when a background shell command
     finishes. 'silent' (default): quietly exits in background. 'inject':
     automatically returns output to agent. 'notify': shows brief message in
@@ -1650,25 +1753,30 @@ their corresponding top-level category object in your `settings.json` file.
   - **Values:** `"silent"`, `"inject"`, `"notify"`
 
 - **`tools.shell.pager`** (string):
+
   - **Description:** The pager command to use for shell output. Defaults to
     `cat`.
   - **Default:** `"cat"`
 
 - **`tools.shell.showColor`** (boolean):
+
   - **Description:** Show color in shell output.
   - **Default:** `true`
 
 - **`tools.shell.inactivityTimeout`** (number):
+
   - **Description:** The maximum time in seconds allowed without output from the
     shell command. Defaults to 5 minutes.
   - **Default:** `300`
 
 - **`tools.shell.enableShellOutputEfficiency`** (boolean):
+
   - **Description:** Enable shell output efficiency optimizations for better
     performance.
   - **Default:** `true`
 
 - **`tools.core`** (array):
+
   - **Description:** Restrict the set of built-in tools with an allowlist. Match
     semantics mirror tools.allowed; see the built-in tools documentation for
     available names.
@@ -1676,6 +1784,7 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`tools.allowed`** (array):
+
   - **Description:** Tool names that bypass the confirmation dialog. Useful for
     trusted commands (for example ["run_shell_command(git)",
     "run_shell_command(npm test)"]). See shell tool command restrictions for
@@ -1684,22 +1793,26 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`tools.confirmationRequired`** (array):
+
   - **Description:** Tool names that always require user confirmation. Takes
     precedence over allowed tools and core tool allowlists.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`tools.exclude`** (array):
+
   - **Description:** Tool names to exclude from discovery.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`tools.discoveryCommand`** (string):
+
   - **Description:** Command to run for tool discovery.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`tools.callCommand`** (string):
+
   - **Description:** Defines a custom shell command for invoking discovered
     tools. The command must take the tool name as the first argument, read JSON
     arguments from stdin, and emit JSON results on stdout.
@@ -1707,11 +1820,13 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`tools.useRipgrep`** (boolean):
+
   - **Description:** Use ripgrep for file content search instead of the fallback
     implementation. Provides faster search performance.
   - **Default:** `true`
 
 - **`tools.truncateToolOutputThreshold`** (number):
+
   - **Description:** Maximum characters to show when truncating large tool
     outputs. Set to 0 or negative to disable truncation.
   - **Default:** `40000`
@@ -1727,11 +1842,13 @@ their corresponding top-level category object in your `settings.json` file.
 #### `mcp`
 
 - **`mcp.serverCommand`** (string):
+
   - **Description:** Command to start an MCP server.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`mcp.allowed`** (array):
+
   - **Description:** A list of MCP servers to allow.
   - **Default:** `undefined`
   - **Requires restart:** Yes
@@ -1750,38 +1867,45 @@ their corresponding top-level category object in your `settings.json` file.
 #### `security`
 
 - **`security.toolSandboxing`** (boolean):
+
   - **Description:** Tool-level sandboxing. Isolates individual tools instead of
     the entire CLI process.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`security.disableYoloMode`** (boolean):
+
   - **Description:** Disable YOLO mode, even if enabled by a flag.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`security.disableAlwaysAllow`** (boolean):
+
   - **Description:** Disable "Always allow" options in tool confirmation
     dialogs.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`security.enablePermanentToolApproval`** (boolean):
+
   - **Description:** Enable the "Allow for all future sessions" option in tool
     confirmation dialogs.
   - **Default:** `false`
 
 - **`security.autoAddToPolicyByDefault`** (boolean):
+
   - **Description:** When enabled, the "Allow for all future sessions" option
     becomes the default choice for low-risk tools in trusted workspaces.
   - **Default:** `false`
 
 - **`security.blockGitExtensions`** (boolean):
+
   - **Description:** Blocks installing and loading extensions from Git.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`security.allowedExtensions`** (array):
+
   - **Description:** List of Regex patterns for allowed extensions. If nonempty,
     only extensions that match the patterns in this list are allowed. Overrides
     the blockGitExtensions setting.
@@ -1789,38 +1913,45 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`security.folderTrust.enabled`** (boolean):
+
   - **Description:** Setting to track whether Folder trust is enabled.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`security.environmentVariableRedaction.allowed`** (array):
+
   - **Description:** Environment variables to always allow (bypass redaction).
   - **Default:** `[]`
   - **Requires restart:** Yes
 
 - **`security.environmentVariableRedaction.blocked`** (array):
+
   - **Description:** Environment variables to always redact.
   - **Default:** `[]`
   - **Requires restart:** Yes
 
 - **`security.environmentVariableRedaction.enabled`** (boolean):
+
   - **Description:** Enable redaction of environment variables that may contain
     secrets.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`security.auth.selectedType`** (string):
+
   - **Description:** The currently selected authentication type.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`security.auth.enforcedType`** (string):
+
   - **Description:** The required auth type. If this does not match the selected
     auth type, the user will be prompted to re-authenticate.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`security.auth.useExternal`** (boolean):
+
   - **Description:** Whether to use an external authentication flow.
   - **Default:** `undefined`
   - **Requires restart:** Yes
@@ -1836,6 +1967,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `advanced`
 
 - **`advanced.autoConfigureMemory`** (boolean):
+
   - **Description:** Automatically configure Node.js memory limits. Note:
     Because memory is allocated during the initial process boot, this setting is
     only read from the global user settings file and ignores workspace-level
@@ -1844,11 +1976,13 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`advanced.dnsResolutionOrder`** (string):
+
   - **Description:** The DNS resolution order.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
 - **`advanced.excludedEnvVars`** (array):
+
   - **Description:** Environment variables to exclude from project context.
   - **Default:**
 
@@ -1857,6 +1991,7 @@ their corresponding top-level category object in your `settings.json` file.
     ```
 
 - **`advanced.ignoreLocalEnv`** (boolean):
+
   - **Description:** Whether to ignore generic .env files in the project
     directory.
   - **Default:** `false`
@@ -1869,21 +2004,25 @@ their corresponding top-level category object in your `settings.json` file.
 #### `experimental`
 
 - **`experimental.gemma`** (boolean):
+
   - **Description:** Enable access to Gemma 4 models via Gemini API.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`experimental.voiceMode`** (boolean):
+
   - **Description:** Enable experimental voice dictation and commands (/voice,
     /voice model).
   - **Default:** `false`
 
 - **`experimental.voice.activationMode`** (enum):
+
   - **Description:** How to trigger voice recording with the Space key.
   - **Default:** `"push-to-talk"`
   - **Values:** `"push-to-talk"`, `"toggle"`
 
 - **`experimental.voice.backend`** (enum):
+
   - **Description:** The backend to use for voice transcription. Note: When
     using the Gemini Live backend, voice recordings are sent to Google Cloud for
     transcription.
@@ -1891,138 +2030,163 @@ their corresponding top-level category object in your `settings.json` file.
   - **Values:** `"gemini-live"`, `"whisper"`
 
 - **`experimental.voice.whisperModel`** (enum):
+
   - **Description:** The Whisper model to use for local transcription.
   - **Default:** `"ggml-base.en.bin"`
   - **Values:** `"ggml-tiny.en.bin"`, `"ggml-base.en.bin"`,
     `"ggml-large-v3-turbo-q5_0.bin"`, `"ggml-large-v3-turbo-q8_0.bin"`
 
 - **`experimental.voice.stopGracePeriodMs`** (number):
+
   - **Description:** How long to wait for final transcription after stopping
     recording.
   - **Default:** `4000`
 
 - **`experimental.adk.agentSessionNoninteractiveEnabled`** (boolean):
+
   - **Description:** Enable non-interactive agent sessions.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.adk.agentSessionInteractiveEnabled`** (boolean):
+
   - **Description:** Enable the agent session implementation for the interactive
     CLI.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.adk.agentSessionSubagentEnabled`** (boolean):
+
   - **Description:** Route subagent invocations through the AgentSession
     protocol instead of legacy executors.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.enableAgents`** (boolean):
+
   - **Description:** Enable local and remote subagents.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`experimental.worktrees`** (boolean):
+
   - **Description:** Enable automated Git worktree management for parallel work.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.extensionManagement`** (boolean):
+
   - **Description:** Enable extension management features.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`experimental.extensionConfig`** (boolean):
+
   - **Description:** Enable requesting and fetching of extension settings.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`experimental.extensionRegistry`** (boolean):
+
   - **Description:** Enable extension registry explore UI.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.extensionRegistryURI`** (string):
+
   - **Description:** The URI (web URL or local file path) of the extension
     registry.
   - **Default:** `"https://geminicli.com/extensions.json"`
   - **Requires restart:** Yes
 
 - **`experimental.extensionReloading`** (boolean):
+
   - **Description:** Enables extension loading/unloading within the CLI session.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.useOSC52Paste`** (boolean):
+
   - **Description:** Use OSC 52 for pasting. This may be more robust than the
     default system when using remote terminal sessions (if your terminal is
     configured to allow it).
   - **Default:** `false`
 
 - **`experimental.useOSC52Copy`** (boolean):
+
   - **Description:** Use OSC 52 for copying. This may be more robust than the
     default system when using remote terminal sessions (if your terminal is
     configured to allow it).
   - **Default:** `false`
 
 - **`experimental.taskTracker`** (boolean):
+
   - **Description:** Enable task tracker tools.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.modelSteering`** (boolean):
+
   - **Description:** Enable model steering (user hints) to guide the model
     during tool execution.
   - **Default:** `false`
 
 - **`experimental.directWebFetch`** (boolean):
+
   - **Description:** Enable web fetch behavior that bypasses LLM summarization.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.dynamicModelConfiguration`** (boolean):
+
   - **Description:** Enable dynamic model configuration (definitions,
     resolutions, and chains) via settings.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.gemmaModelRouter.enabled`** (boolean):
+
   - **Description:** Enable the Gemma Model Router (experimental). Requires a
     local endpoint serving Gemma via the Gemini API using LiteRT-LM shim.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.gemmaModelRouter.autoStartServer`** (boolean):
+
   - **Description:** Automatically start the LiteRT-LM server when Gemini CLI
     starts and the Gemma router is enabled.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.gemmaModelRouter.binaryPath`** (string):
+
   - **Description:** Custom path to the LiteRT-LM binary. Leave empty to use the
     default location (~/.gemini/bin/litert/).
   - **Default:** `""`
   - **Requires restart:** Yes
 
 - **`experimental.gemmaModelRouter.classifier.host`** (string):
+
   - **Description:** The host of the classifier.
   - **Default:** `"http://localhost:9379"`
   - **Requires restart:** Yes
 
 - **`experimental.gemmaModelRouter.classifier.model`** (string):
+
   - **Description:** The model to use for the classifier. Only tested on
     `gemma3-1b-gpu-custom`.
   - **Default:** `"gemma3-1b-gpu-custom"`
   - **Requires restart:** Yes
 
 - **`experimental.stressTestProfile`** (boolean):
+
   - **Description:** Significantly lowers token limits to force early garbage
     collection and distillation for testing purposes.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.autoMemory`** (boolean):
+
   - **Description:** Automatically extract memory patches and skills from past
     sessions in the background. Every change is written as a unified diff
     `.patch` file under `<projectMemoryDir>/.inbox/<kind>/` and held for review
@@ -2031,16 +2195,19 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`experimental.generalistProfile`** (boolean):
+
   - **Description:** Suitable for general coding and software development tasks.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.powerUserProfile`** (boolean):
+
   - **Description:** Less cache friendly version of the generalist profile.
   - **Default:** `false`
   - **Requires restart:** Yes
 
 - **`experimental.contextManagement`** (boolean):
+
   - **Description:** Enable logic for context management.
   - **Default:** `false`
   - **Requires restart:** Yes
@@ -2052,6 +2219,7 @@ their corresponding top-level category object in your `settings.json` file.
 #### `skills`
 
 - **`skills.enabled`** (boolean):
+
   - **Description:** Enable Agent Skills.
   - **Default:** `true`
   - **Requires restart:** Yes
@@ -2064,12 +2232,14 @@ their corresponding top-level category object in your `settings.json` file.
 #### `hooksConfig`
 
 - **`hooksConfig.enabled`** (boolean):
+
   - **Description:** Canonical toggle for the hooks system. When disabled, no
     hooks will be executed.
   - **Default:** `true`
   - **Requires restart:** Yes
 
 - **`hooksConfig.disabled`** (array):
+
   - **Description:** List of hook names (commands) that should be disabled.
     Hooks in this list will not execute even if configured.
   - **Default:** `[]`
@@ -2081,51 +2251,61 @@ their corresponding top-level category object in your `settings.json` file.
 #### `hooks`
 
 - **`hooks.BeforeTool`** (array):
+
   - **Description:** Hooks that execute before tool execution. Can intercept,
     validate, or modify tool calls.
   - **Default:** `[]`
 
 - **`hooks.AfterTool`** (array):
+
   - **Description:** Hooks that execute after tool execution. Can process
     results, log outputs, or trigger follow-up actions.
   - **Default:** `[]`
 
 - **`hooks.BeforeAgent`** (array):
+
   - **Description:** Hooks that execute before agent loop starts. Can set up
     context or initialize resources.
   - **Default:** `[]`
 
 - **`hooks.AfterAgent`** (array):
+
   - **Description:** Hooks that execute after agent loop completes. Can perform
     cleanup or summarize results.
   - **Default:** `[]`
 
 - **`hooks.Notification`** (array):
+
   - **Description:** Hooks that execute on notification events (errors,
     warnings, info). Can log or alert on specific conditions.
   - **Default:** `[]`
 
 - **`hooks.SessionStart`** (array):
+
   - **Description:** Hooks that execute when a session starts. Can initialize
     session-specific resources or state.
   - **Default:** `[]`
 
 - **`hooks.SessionEnd`** (array):
+
   - **Description:** Hooks that execute when a session ends. Can perform cleanup
     or persist session data.
   - **Default:** `[]`
 
 - **`hooks.PreCompress`** (array):
+
   - **Description:** Hooks that execute before chat history compression. Can
     back up or analyze conversation before compression.
   - **Default:** `[]`
 
 - **`hooks.BeforeModel`** (array):
+
   - **Description:** Hooks that execute before LLM requests. Can modify prompts,
     inject context, or control model parameters.
   - **Default:** `[]`
 
 - **`hooks.AfterModel`** (array):
+
   - **Description:** Hooks that execute after LLM responses. Can process
     outputs, extract information, or log interactions.
   - **Default:** `[]`
@@ -2138,35 +2318,41 @@ their corresponding top-level category object in your `settings.json` file.
 #### `contextManagement`
 
 - **`contextManagement.historyWindow.maxTokens`** (number):
+
   - **Description:** The number of tokens to allow before triggering
     compression.
   - **Default:** `150000`
   - **Requires restart:** Yes
 
 - **`contextManagement.historyWindow.retainedTokens`** (number):
+
   - **Description:** The number of tokens to always retain.
   - **Default:** `40000`
   - **Requires restart:** Yes
 
 - **`contextManagement.messageLimits.normalMaxTokens`** (number):
+
   - **Description:** The target number of tokens to budget for a normal
     conversation turn.
   - **Default:** `2500`
   - **Requires restart:** Yes
 
 - **`contextManagement.messageLimits.retainedMaxTokens`** (number):
+
   - **Description:** The maximum number of tokens a single conversation turn can
     consume before truncation.
   - **Default:** `12000`
   - **Requires restart:** Yes
 
 - **`contextManagement.messageLimits.normalizationHeadRatio`** (number):
+
   - **Description:** The ratio of tokens to retain from the beginning of a
     truncated message (0.0 to 1.0).
   - **Default:** `0.25`
   - **Requires restart:** Yes
 
 - **`contextManagement.tools.distillation.maxOutputTokens`** (number):
+
   - **Description:** Maximum tokens to show to the model when truncating large
     tool outputs.
   - **Default:** `10000`
@@ -2174,6 +2360,7 @@ their corresponding top-level category object in your `settings.json` file.
 
 - **`contextManagement.tools.distillation.summarizationThresholdTokens`**
   (number):
+
   - **Description:** Threshold above which truncated tool outputs will be
     summarized by an LLM.
   - **Default:** `20000`
@@ -2181,6 +2368,7 @@ their corresponding top-level category object in your `settings.json` file.
 
 - **`contextManagement.tools.outputMasking.protectionThresholdTokens`**
   (number):
+
   - **Description:** Minimum number of tokens to protect from masking (most
     recent tool outputs).
   - **Default:** `50000`
@@ -2188,6 +2376,7 @@ their corresponding top-level category object in your `settings.json` file.
 
 - **`contextManagement.tools.outputMasking.minPrunableThresholdTokens`**
   (number):
+
   - **Description:** Minimum prunable tokens required to trigger a masking pass.
   - **Default:** `30000`
   - **Requires restart:** Yes
@@ -2201,24 +2390,29 @@ their corresponding top-level category object in your `settings.json` file.
 #### `admin`
 
 - **`admin.secureModeEnabled`** (boolean):
+
   - **Description:** If true, disallows YOLO mode and "Always allow" options
     from being used.
   - **Default:** `false`
 
 - **`admin.extensions.enabled`** (boolean):
+
   - **Description:** If false, disallows extensions from being installed or
     used.
   - **Default:** `true`
 
 - **`admin.mcp.enabled`** (boolean):
+
   - **Description:** If false, disallows MCP servers from being used.
   - **Default:** `true`
 
 - **`admin.mcp.config`** (object):
+
   - **Description:** Admin-configured MCP servers (allowlist).
   - **Default:** `{}`
 
 - **`admin.mcp.requiredConfig`** (object):
+
   - **Description:** Admin-required MCP servers that are always injected.
   - **Default:** `{}`