@google/gemini-cli-core 0.22.0 → 0.23.0-preview.0

package/dist/docs/core/memport.md

@@ -0,0 +1,244 @@
+# Memory Import Processor
+
+The Memory Import Processor is a feature that allows you to modularize your
+GEMINI.md files by importing content from other files using the `@file.md`
+syntax.
+
+## Overview
+
+This feature enables you to break down large GEMINI.md files into smaller, more
+manageable components that can be reused across different contexts. The import
+processor supports both relative and absolute paths, with built-in safety
+features to prevent circular imports and ensure file access security.
+
+## Syntax
+
+Use the `@` symbol followed by the path to the file you want to import:
+
+```markdown
+# Main GEMINI.md file
+
+This is the main content.
+
+@./components/instructions.md
+
+More content here.
+
+@./shared/configuration.md
+```
+
+## Supported path formats
+
+### Relative paths
+
+- `@./file.md` - Import from the same directory
+- `@../file.md` - Import from parent directory
+- `@./components/file.md` - Import from subdirectory
+
+### Absolute paths
+
+- `@/absolute/path/to/file.md` - Import using absolute path
+
+## Examples
+
+### Basic import
+
+```markdown
+# My GEMINI.md
+
+Welcome to my project!
+
+@./get-started.md
+
+## Features
+
+@./features/overview.md
+```
+
+### Nested imports
+
+The imported files can themselves contain imports, creating a nested structure:
+
+```markdown
+# main.md
+
+@./header.md @./content.md @./footer.md
+```
+
+```markdown
+# header.md
+
+# Project Header
+
+@./shared/title.md
+```
+
+## Safety features
+
+### Circular import detection
+
+The processor automatically detects and prevents circular imports:
+
+```markdown
+# file-a.md
+
+@./file-b.md
+
+# file-b.md
+
+@./file-a.md <!-- This will be detected and prevented -->
+```
+
+### File access security
+
+The `validateImportPath` function ensures that imports are only allowed from
+specified directories, preventing access to sensitive files outside the allowed
+scope.
+
+### Maximum import depth
+
+To prevent infinite recursion, there's a configurable maximum import depth
+(default: 5 levels).
+
+## Error handling
+
+### Missing files
+
+If a referenced file doesn't exist, the import will fail gracefully with an
+error comment in the output.
+
+### File access errors
+
+Permission issues or other file system errors are handled gracefully with
+appropriate error messages.
+
+## Code region detection
+
+The import processor uses the `marked` library to detect code blocks and inline
+code spans, ensuring that `@` imports inside these regions are properly ignored.
+This provides robust handling of nested code blocks and complex Markdown
+structures.
+
+## Import tree structure
+
+The processor returns an import tree that shows the hierarchy of imported files,
+similar to Claude's `/memory` feature. This helps users debug problems with
+their GEMINI.md files by showing which files were read and their import
+relationships.
+
+Example tree structure:
+
+```
+Memory Files
+ L project: GEMINI.md
+            L a.md
+              L b.md
+                L c.md
+              L d.md
+                L e.md
+                  L f.md
+            L included.md
+```
+
+The tree preserves the order that files were imported and shows the complete
+import chain for debugging purposes.
+
+## Comparison to Claude Code's `/memory` (`claude.md`) approach
+
+Claude Code's `/memory` feature (as seen in `claude.md`) produces a flat, linear
+document by concatenating all included files, always marking file boundaries
+with clear comments and path names. It does not explicitly present the import
+hierarchy, but the LLM receives all file contents and paths, which is sufficient
+for reconstructing the hierarchy if needed.
+
+> [!NOTE] The import tree is mainly for clarity during development and has
+> limited relevance to LLM consumption.
+
+## API reference
+
+### `processImports(content, basePath, debugMode?, importState?)`
+
+Processes import statements in GEMINI.md content.
+
+**Parameters:**
+
+- `content` (string): The content to process for imports
+- `basePath` (string): The directory path where the current file is located
+- `debugMode` (boolean, optional): Whether to enable debug logging (default:
+  false)
+- `importState` (ImportState, optional): State tracking for circular import
+  prevention
+
+**Returns:** Promise&lt;ProcessImportsResult&gt; - Object containing processed
+content and import tree
+
+### `ProcessImportsResult`
+
+```typescript
+interface ProcessImportsResult {
+  content: string; // The processed content with imports resolved
+  importTree: MemoryFile; // Tree structure showing the import hierarchy
+}
+```
+
+### `MemoryFile`
+
+```typescript
+interface MemoryFile {
+  path: string; // The file path
+  imports?: MemoryFile[]; // Direct imports, in the order they were imported
+}
+```
+
+### `validateImportPath(importPath, basePath, allowedDirectories)`
+
+Validates import paths to ensure they are safe and within allowed directories.
+
+**Parameters:**
+
+- `importPath` (string): The import path to validate
+- `basePath` (string): The base directory for resolving relative paths
+- `allowedDirectories` (string[]): Array of allowed directory paths
+
+**Returns:** boolean - Whether the import path is valid
+
+### `findProjectRoot(startDir)`
+
+Finds the project root by searching for a `.git` directory upwards from the
+given start directory. Implemented as an **async** function using non-blocking
+file system APIs to avoid blocking the Node.js event loop.
+
+**Parameters:**
+
+- `startDir` (string): The directory to start searching from
+
+**Returns:** Promise&lt;string&gt; - The project root directory (or the start
+directory if no `.git` is found)
+
+## Best Practices
+
+1. **Use descriptive file names** for imported components
+2. **Keep imports shallow** - avoid deeply nested import chains
+3. **Document your structure** - maintain a clear hierarchy of imported files
+4. **Test your imports** - ensure all referenced files exist and are accessible
+5. **Use relative paths** when possible for better portability
+
+## Troubleshooting
+
+### Common issues
+
+1. **Import not working**: Check that the file exists and the path is correct
+2. **Circular import warnings**: Review your import structure for circular
+   references
+3. **Permission errors**: Ensure the files are readable and within allowed
+   directories
+4. **Path resolution issues**: Use absolute paths if relative paths aren't
+   resolving correctly
+
+### Debug mode
+
+Enable debug mode to see detailed logging of the import process:
+
+```typescript
+const result = await processImports(content, basePath, true);
+```

package/dist/docs/core/policy-engine.md

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

package/dist/docs/core/tools-api.md

@@ -0,0 +1,131 @@
+# Gemini CLI core: Tools API
+
+The Gemini CLI core (`packages/core`) features a robust system for defining,
+registering, and executing tools. These tools extend the capabilities of the
+Gemini model, allowing it to interact with the local environment, fetch web
+content, and perform various actions beyond simple text generation.
+
+## Core concepts
+
+- **Tool (`tools.ts`):** An interface and base class (`BaseTool`) that defines
+  the contract for all tools. Each tool must have:
+  - `name`: A unique internal name (used in API calls to Gemini).
+  - `displayName`: A user-friendly name.
+  - `description`: A clear explanation of what the tool does, which is provided
+    to the Gemini model.
+  - `parameterSchema`: A JSON schema defining the parameters that the tool
+    accepts. This is crucial for the Gemini model to understand how to call the
+    tool correctly.
+  - `validateToolParams()`: A method to validate incoming parameters.
+  - `getDescription()`: A method to provide a human-readable description of what
+    the tool will do with specific parameters before execution.
+  - `shouldConfirmExecute()`: A method to determine if user confirmation is
+    required before execution (e.g., for potentially destructive operations).
+  - `execute()`: The core method that performs the tool's action and returns a
+    `ToolResult`.
+
+- **`ToolResult` (`tools.ts`):** An interface defining the structure of a tool's
+  execution outcome:
+  - `llmContent`: The factual content to be included in the history sent back to
+    the LLM for context. This can be a simple string or a `PartListUnion` (an
+    array of `Part` objects and strings) for rich content.
+  - `returnDisplay`: A user-friendly string (often Markdown) or a special object
+    (like `FileDiff`) for display in the CLI.
+
+- **Returning rich content:** Tools are not limited to returning simple text.
+  The `llmContent` can be a `PartListUnion`, which is an array that can contain
+  a mix of `Part` objects (for images, audio, etc.) and `string`s. This allows a
+  single tool execution to return multiple pieces of rich content.
+
+- **Tool registry (`tool-registry.ts`):** A class (`ToolRegistry`) responsible
+  for:
+  - **Registering tools:** Holding a collection of all available built-in tools
+    (e.g., `ReadFileTool`, `ShellTool`).
+  - **Discovering tools:** It can also discover tools dynamically:
+    - **Command-based discovery:** If `tools.discoveryCommand` is configured in
+      settings, this command is executed. It's expected to output JSON
+      describing custom tools, which are then registered as `DiscoveredTool`
+      instances.
+    - **MCP-based discovery:** If `mcp.serverCommand` is configured, the
+      registry can connect to a Model Context Protocol (MCP) server to list and
+      register tools (`DiscoveredMCPTool`).
+  - **Providing schemas:** Exposing the `FunctionDeclaration` schemas of all
+    registered tools to the Gemini model, so it knows what tools are available
+    and how to use them.
+  - **Retrieving tools:** Allowing the core to get a specific tool by name for
+    execution.
+
+## Built-in tools
+
+The core comes with a suite of pre-defined tools, typically found in
+`packages/core/src/tools/`. These include:
+
+- **File system tools:**
+  - `LSTool` (`ls.ts`): Lists directory contents.
+  - `ReadFileTool` (`read-file.ts`): Reads the content of a single file.
+  - `WriteFileTool` (`write-file.ts`): Writes content to a file.
+  - `GrepTool` (`grep.ts`): Searches for patterns in files.
+  - `GlobTool` (`glob.ts`): Finds files matching glob patterns.
+  - `EditTool` (`edit.ts`): Performs in-place modifications to files (often
+    requiring confirmation).
+  - `ReadManyFilesTool` (`read-many-files.ts`): Reads and concatenates content
+    from multiple files or glob patterns (used by the `@` command in CLI).
+- **Execution tools:**
+  - `ShellTool` (`shell.ts`): Executes arbitrary shell commands (requires
+    careful sandboxing and user confirmation).
+- **Web tools:**
+  - `WebFetchTool` (`web-fetch.ts`): Fetches content from a URL.
+  - `WebSearchTool` (`web-search.ts`): Performs a web search.
+- **Memory tools:**
+  - `MemoryTool` (`memoryTool.ts`): Interacts with the AI's memory.
+
+Each of these tools extends `BaseTool` and implements the required methods for
+its specific functionality.
+
+## Tool execution flow
+
+1.  **Model request:** The Gemini model, based on the user's prompt and the
+    provided tool schemas, decides to use a tool and returns a `FunctionCall`
+    part in its response, specifying the tool name and arguments.
+2.  **Core receives request:** The core parses this `FunctionCall`.
+3.  **Tool retrieval:** It looks up the requested tool in the `ToolRegistry`.
+4.  **Parameter validation:** The tool's `validateToolParams()` method is
+    called.
+5.  **Confirmation (if needed):**
+    - The tool's `shouldConfirmExecute()` method is called.
+    - If it returns details for confirmation, the core communicates this back to
+      the CLI, which prompts the user.
+    - The user's decision (e.g., proceed, cancel) is sent back to the core.
+6.  **Execution:** If validated and confirmed (or if no confirmation is needed),
+    the core calls the tool's `execute()` method with the provided arguments and
+    an `AbortSignal` (for potential cancellation).
+7.  **Result processing:** The `ToolResult` from `execute()` is received by the
+    core.
+8.  **Response to model:** The `llmContent` from the `ToolResult` is packaged as
+    a `FunctionResponse` and sent back to the Gemini model so it can continue
+    generating a user-facing response.
+9.  **Display to user:** The `returnDisplay` from the `ToolResult` is sent to
+    the CLI to show the user what the tool did.
+
+## Extending with custom tools
+
+While direct programmatic registration of new tools by users isn't explicitly
+detailed as a primary workflow in the provided files for typical end-users, the
+architecture supports extension through:
+
+- **Command-based discovery:** Advanced users or project administrators can
+  define a `tools.discoveryCommand` in `settings.json`. This command, when run
+  by the Gemini CLI core, should output a JSON array of `FunctionDeclaration`
+  objects. The core will then make these available as `DiscoveredTool`
+  instances. The corresponding `tools.callCommand` would then be responsible for
+  actually executing these custom tools.
+- **MCP server(s):** For more complex scenarios, one or more MCP servers can be
+  set up and configured via the `mcpServers` setting in `settings.json`. The
+  Gemini CLI core can then discover and use tools exposed by these servers. As
+  mentioned, if you have multiple MCP servers, the tool names will be prefixed
+  with the server name from your configuration (e.g.,
+  `serverAlias__actualToolName`).
+
+This tool system provides a flexible and powerful way to augment the Gemini
+model's capabilities, making the Gemini CLI a versatile assistant for a wide
+range of tasks.