@office-ai/aioncli-core 0.26.0 → 0.30.1

package/dist/docs/core/concepts.md

@@ -0,0 +1,137 @@
+# Core concepts
+
+This guide explains the fundamental concepts and terminology used throughout the
+Gemini CLI ecosystem. Understanding these terms will help you make the most of
+the tool's capabilities.
+
+## Approval mode
+
+**Approval mode** determines the level of autonomy you grant to the agent when
+executing tools.
+
+- **Default:** The agent asks for confirmation before performing any potentially
+  impactful action (like writing files or running shell commands).
+- **Auto-edit:** File modifications are applied automatically, but shell
+  commands still require confirmation.
+- **YOLO (You Only Look Once):** The agent runs all tools without asking for
+  permission. High risk, high speed.
+
+## Checkpointing
+
+**Checkpointing** is a safety feature that automatically snapshots your
+project's file state before the agent performs any destructive action (like
+writing a file).
+
+- **Snapshots:** Stored in a hidden Git repository (separate from your project's
+  Git history).
+- **Restore:** Allows you to instantly revert changes if the agent makes a
+  mistake, using the `/restore` command.
+
+## Context
+
+**Context** refers to the information the agent has about your current task and
+environment. Gemini CLI provides context through several mechanisms:
+
+- **Conversation history:** The chat log of the current session.
+- **Project context (`GEMINI.md`):** Persistent instructions and rules defined
+  in your project's root or subdirectories.
+- **File content:** Files you explicitly reference (e.g., `@src/app.ts`) or that
+  the agent reads using tools.
+- **Environment:** Information about your operating system, shell, and working
+  directory.
+
+Effective context management is key to getting accurate and relevant responses.
+
+## Extension
+
+An **Extension** is a pluggable package that adds new capabilities to Gemini
+CLI. Extensions can bundle:
+
+- **Skills:** Specialized procedural knowledge.
+- **MCP Servers:** Connections to external tools and data.
+- **Commands:** Custom slash commands.
+
+## Headless mode
+
+**Headless mode** refers to running Gemini CLI without the interactive terminal
+UI (TUI). This is used for scripting, automation, and piping data into or out of
+the agent.
+
+- **Interactive:** `gemini` (starts the REPL).
+- **Headless:** `gemini "Fix this file"` (runs once and exits).
+
+## Hook
+
+A **Hook** is a script or function that intercepts specific lifecycle events in
+the CLI.
+
+- **Use cases:** Logging tool usage, validating user input, or modifying the
+  agent's system prompt dynamically.
+- **Lifecycle:** Hooks can run before or after the agent starts, before tools
+  are executed, or after the session ends.
+
+## Model Context Protocol (MCP)
+
+The **Model Context Protocol (MCP)** is an open standard that allows Gemini CLI
+to connect to external data sources and tools.
+
+- **MCP Server:** A lightweight application that exposes resources (data) and
+  tools (functions) to the CLI.
+- **Use case:** Connecting Gemini to a PostgreSQL database, a GitHub repository,
+  or a Slack workspace without building custom integration logic into the CLI
+  core.
+
+## Policy engine
+
+The **Policy Engine** is the security subsystem that enforces rules on tool
+execution. It evaluates every tool call against your configuration (e.g.,
+[Trusted folders](#trusted-folders), allowed commands) to decide whether to:
+
+- Allow the action immediately.
+- Require user confirmation.
+- Block the action entirely.
+
+## Sandboxing
+
+**Sandboxing** is an optional security mode that isolates the agent's execution
+environment. When enabled, the agent runs inside a secure container (e.g.,
+Docker), preventing it from accessing sensitive files or system resources
+outside of the designated workspace.
+
+## Session
+
+A **Session** is a single continuous interaction thread with the agent.
+
+- **State:** Sessions maintain conversation history and short-term memory.
+- **Persistence:** Sessions are automatically saved, allowing you to pause,
+  resume, or rewind them later.
+
+## Skill
+
+A **Skill** (or **Agent Skill**) is a package of specialized expertise that the
+agent can load on demand. Unlike general context, a skill provides specific
+procedural knowledge for a distinct task.
+
+- **Example:** A "Code Reviewer" skill might contain a checklist of security
+  vulnerabilities to look for and a specific format for reporting findings.
+- **Activation:** Skills are typically activated dynamically when the agent
+  recognizes a matching request.
+
+## Tool
+
+A **Tool** is a specific function or capability that the agent can execute.
+Tools allow the AI to interact with the outside world.
+
+- **Built-in tools:** Core capabilities like `read_file`, `run_shell_command`,
+  and `google_web_search`.
+- **MCP tools:** External tools provided by
+  [MCP servers](#model-context-protocol-mcp).
+
+When the agent uses a tool, it pauses generation, executes the code, and feeds
+the output back into its context window.
+
+## Trusted folders
+
+**Trusted folders** are specific directories you have explicitly authorized the
+agent to access without repeated confirmation prompts. This is a key component
+of the [Policy engine](#policy-engine) to balance security and usability.

package/dist/docs/core/index.md

@@ -7,6 +7,8 @@ requests sent from `packages/cli`. For a general overview of Gemini CLI, see the
 
 ## Navigating this section
 
+- **[Sub-agents (experimental)](./subagents.md):** Learn how to create and use
+  specialized sub-agents for complex tasks.
 - **[Core tools API](./tools-api.md):** Information on how tools are defined,
   registered, and used by the core.
 - **[Memory Import Processor](./memport.md):** Documentation for the modular
@@ -68,6 +70,10 @@ If you are using the default "pro" model and the CLI detects that you are being
 rate-limited, it automatically switches to the "flash" model for the current
 session. This allows you to continue working without interruption.
 
+Internal utility calls that use `gemini-2.5-flash-lite` (for example, prompt
+completion and classification) silently fall back to `gemini-2.5-flash` and
+`gemini-2.5-pro` when quota is exhausted, without changing the configured model.
+
 ## File discovery service
 
 The file discovery service is responsible for finding files in the project that

package/dist/docs/core/memport.md

@@ -83,7 +83,9 @@ The processor automatically detects and prevents circular imports:
 # file-a.md
 
 @./file-b.md
+```
 
+```markdown
 # file-b.md
 
 @./file-a.md <!-- This will be detected and prevented -->

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

@@ -119,9 +119,17 @@ For example:
 
 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.
+(e.g., `yolo`, `autoEdit`, `plan`). 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.
+
+- `default`: The standard interactive mode where most write tools require
+  confirmation.
+- `autoEdit`: Optimized for automated code editing; some write tools may be
+  auto-approved.
+- `plan`: A strict, read-only mode for research and design. See [Customizing
+  Plan Mode Policies].
+- `yolo`: A mode where all tools are auto-approved (use with extreme caution).
 
 ## Rule matching
 
@@ -146,6 +154,38 @@ A rule matches a tool call if all of its conditions are met:
 Policies are defined in `.toml` files. The CLI loads these files from Default,
 User, and (if configured) Admin directories.
 
+### Policy locations
+
+| Tier      | Type   | Location                    |
+| :-------- | :----- | :-------------------------- |
+| **User**  | Custom | `~/.gemini/policies/*.toml` |
+| **Admin** | System | _See below (OS specific)_   |
+
+#### System-wide policies (Admin)
+
+Administrators can enforce system-wide policies (Tier 3) that override all user
+and default settings. These policies must be placed in specific, secure
+directories:
+
+| OS          | Policy Directory Path                             |
+| :---------- | :------------------------------------------------ |
+| **Linux**   | `/etc/gemini-cli/policies`                        |
+| **macOS**   | `/Library/Application Support/GeminiCli/policies` |
+| **Windows** | `C:\ProgramData\gemini-cli\policies`              |
+
+**Security Requirements:**
+
+To prevent privilege escalation, the CLI enforces strict security checks on
+admin directories. If checks fail, system policies are **ignored**.
+
+- **Linux / macOS:** Must be owned by `root` (UID 0) and NOT writable by group
+  or others (e.g., `chmod 755`).
+- **Windows:** Must be in `C:\ProgramData`. Standard users (`Users`, `Everyone`)
+  must NOT have `Write`, `Modify`, or `Full Control` permissions. _Tip: If you
+  see a security warning, use the folder properties to remove write permissions
+  for non-admin groups. You may need to "Disable inheritance" in Advanced
+  Security Settings._
+
 ### TOML rule schema
 
 Here is a breakdown of the fields available in a TOML policy rule:
@@ -168,9 +208,11 @@ 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.
+# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`).
+# Because it prepends `"command":"`, it effectively matches from the start of the command.
+# Anchors like `^` or `$` apply to the full JSON string, so `^` should usually be avoided here.
 # You cannot use commandPrefix and commandRegex in the same rule.
-commandRegex = "^git (commit|push)"
+commandRegex = "git (commit|push)"
 
 # The decision to take. Must be "allow", "deny", or "ask_user".
 decision = "ask_user"
@@ -178,6 +220,10 @@ decision = "ask_user"
 # The priority of the rule, from 0 to 999.
 priority = 10
 
+# (Optional) A custom message to display when a tool call is denied by this rule.
+# This message is returned to the model and user, useful for explaining *why* it was denied.
+deny_message = "Deletion is permanent"
+
 # (Optional) An array of approval modes where this rule is active.
 modes = ["autoEdit"]
 ```
@@ -250,6 +296,7 @@ only the `mcpName`.
 mcpName = "untrusted-server"
 decision = "deny"
 priority = 500
+deny_message = "This server is not trusted by the admin."
 ```
 
 ## Default policies
@@ -258,10 +305,13 @@ 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).
+- **Agent delegation** defaults to **`ask_user`** to ensure remote agents can
+  prompt for confirmation, but local sub-agent actions are executed silently and
+  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.
+
+[Customizing Plan Mode Policies]: /docs/cli/plan-mode.md#customizing-policies

package/dist/docs/core/remote-agents.md

@@ -0,0 +1,84 @@
+# Remote Subagents (experimental)
+
+Gemini CLI supports connecting to remote subagents using the Agent-to-Agent
+(A2A) protocol. This allows Gemini CLI to interact with other agents, expanding
+its capabilities by delegating tasks to remote services.
+
+Gemini CLI can connect to any compliant A2A agent. You can find samples of A2A
+agents in the following repositories:
+
+- [ADK Samples (Python)](https://github.com/google/adk-samples/tree/main/python)
+- [ADK Python Contributing Samples](https://github.com/google/adk-python/tree/main/contributing/samples)
+
+> **Note: Remote subagents are currently an experimental feature.**
+
+## Configuration
+
+To use remote subagents, you must explicitly enable them in your
+`settings.json`:
+
+```json
+{
+  "experimental": {
+    "enableAgents": true
+  }
+}
+```
+
+## Defining remote subagents
+
+Remote subagents are defined as Markdown files (`.md`) with YAML frontmatter.
+You can place them in:
+
+1.  **Project-level:** `.gemini/agents/*.md` (Shared with your team)
+2.  **User-level:** `~/.gemini/agents/*.md` (Personal agents)
+
+### Configuration schema
+
+| Field            | Type   | Required | Description                                                                                                    |
+| :--------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------- |
+| `kind`           | string | Yes      | Must be `remote`.                                                                                              |
+| `name`           | string | Yes      | A unique name for the agent. Must be a valid slug (lowercase letters, numbers, hyphens, and underscores only). |
+| `agent_card_url` | string | Yes      | The URL to the agent's A2A card endpoint.                                                                      |
+
+### Single-subagent example
+
+```markdown
+---
+kind: remote
+name: my-remote-agent
+agent_card_url: https://example.com/agent-card
+---
+```
+
+### Multi-subagent example
+
+The loader explicitly supports multiple remote subagents defined in a single
+Markdown file.
+
+```markdown
+---
+- kind: remote
+  name: remote-1
+  agent_card_url: https://example.com/1
+- kind: remote
+  name: remote-2
+  agent_card_url: https://example.com/2
+---
+```
+
+> **Note:** Mixed local and remote agents, or multiple local agents, are not
+> supported in a single file; the list format is currently remote-only.
+
+## Managing Subagents
+
+Users can manage subagents using the following commands within the Gemini CLI:
+
+- `/agents list`: Displays all available local and remote subagents.
+- `/agents refresh`: Reloads the agent registry. Use this after adding or
+  modifying agent definition files.
+- `/agents enable <agent_name>`: Enables a specific subagent.
+- `/agents disable <agent_name>`: Disables a specific subagent.
+
+> **Tip:** You can use the `@cli_help` agent within Gemini CLI for assistance
+> with configuring subagents.

package/dist/docs/core/subagents.md

@@ -0,0 +1,191 @@
+# Sub-agents (experimental)
+
+Sub-agents are specialized agents that operate within your main Gemini CLI
+session. They are designed to handle specific, complex tasks—like deep codebase
+analysis, documentation lookup, or domain-specific reasoning—without cluttering
+the main agent's context or toolset.
+
+> **Note: Sub-agents are currently an experimental feature.**
+>
+> To use custom sub-agents, you must explicitly enable them in your
+> `settings.json`:
+>
+> ```json
+> {
+>   "experimental": { "enableAgents": true }
+> }
+> ```
+>
+> **Warning:** Sub-agents currently operate in
+> ["YOLO mode"](../get-started/configuration.md#command-line-arguments), meaning
+> they may execute tools without individual user confirmation for each step.
+> Proceed with caution when defining agents with powerful tools like
+> `run_shell_command` or `write_file`.
+
+## What are sub-agents?
+
+Sub-agents are "specialists" that the main Gemini agent can hire for a specific
+job.
+
+- **Focused context:** Each sub-agent has its own system prompt and persona.
+- **Specialized tools:** Sub-agents can have a restricted or specialized set of
+  tools.
+- **Independent context window:** Interactions with a sub-agent happen in a
+  separate context loop, which saves tokens in your main conversation history.
+
+Sub-agents are exposed to the main agent as a tool of the same name. When the
+main agent calls the tool, it delegates the task to the sub-agent. Once the
+sub-agent completes its task, it reports back to the main agent with its
+findings.
+
+## Built-in sub-agents
+
+Gemini CLI comes with the following built-in sub-agents:
+
+### Codebase Investigator
+
+- **Name:** `codebase_investigator`
+- **Purpose:** Analyze the codebase, reverse engineer, and understand complex
+  dependencies.
+- **When to use:** "How does the authentication system work?", "Map out the
+  dependencies of the `AgentRegistry` class."
+- **Configuration:** Enabled by default. You can configure it in
+  `settings.json`. Example (forcing a specific model):
+  ```json
+  {
+    "experimental": {
+      "codebaseInvestigatorSettings": {
+        "enabled": true,
+        "maxNumTurns": 20,
+        "model": "gemini-2.5-pro"
+      }
+    }
+  }
+  ```
+
+### CLI Help Agent
+
+- **Name:** `cli_help`
+- **Purpose:** Get expert knowledge about Gemini CLI itself, its commands,
+  configuration, and documentation.
+- **When to use:** "How do I configure a proxy?", "What does the `/rewind`
+  command do?"
+- **Configuration:** Enabled by default.
+
+### Generalist Agent
+
+- **Name:** `generalist_agent`
+- **Purpose:** Route tasks to the appropriate specialized sub-agent.
+- **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.
+
+## Creating custom sub-agents
+
+You can create your own sub-agents to automate specific workflows or enforce
+specific personas. To use custom sub-agents, you must enable them in your
+`settings.json`:
+
+```json
+{
+  "experimental": {
+    "enableAgents": true
+  }
+}
+```
+
+### Agent definition files
+
+Custom agents are defined as Markdown files (`.md`) with YAML frontmatter. You
+can place them in:
+
+1.  **Project-level:** `.gemini/agents/*.md` (Shared with your team)
+2.  **User-level:** `~/.gemini/agents/*.md` (Personal agents)
+
+### File format
+
+The file **MUST** start with YAML frontmatter enclosed in triple-dashes `---`.
+The body of the markdown file becomes the agent's **System Prompt**.
+
+**Example: `.gemini/agents/security-auditor.md`**
+
+```markdown
+---
+name: security-auditor
+description: Specialized in finding security vulnerabilities in code.
+kind: local
+tools:
+  - read_file
+  - grep_search
+model: gemini-2.5-pro
+temperature: 0.2
+max_turns: 10
+---
+
+You are a ruthless Security Auditor. Your job is to analyze code for potential
+vulnerabilities.
+
+Focus on:
+
+1.  SQL Injection
+2.  XSS (Cross-Site Scripting)
+3.  Hardcoded credentials
+4.  Unsafe file operations
+
+When you find a vulnerability, explain it clearly and suggest a fix. Do not fix
+it yourself; just report it.
+```
+
+### Configuration schema
+
+| Field          | Type   | Required | Description                                                                                                                |
+| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | string | Yes      | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores.   |
+| `description`  | string | Yes      | Short description of what the agent does. This is visible to the main agent to help it decide when to call this sub-agent. |
+| `kind`         | string | No       | `local` (default) or `remote`.                                                                                             |
+| `tools`        | array  | No       | List of tool names this agent can use. If omitted, it may have access to a default set.                                    |
+| `model`        | string | No       | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model).                       |
+| `temperature`  | number | No       | Model temperature (0.0 - 2.0).                                                                                             |
+| `max_turns`    | number | No       | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`.                       |
+| `timeout_mins` | number | No       | Maximum execution time in minutes. Defaults to `5`.                                                                        |
+
+### Optimizing your sub-agent
+
+The main agent's system prompt encourages it to use an expert sub-agent when one
+is available. It decides whether an agent is a relevant expert based on the
+agent's description. You can improve the reliability with which an agent is used
+by updating the description to more clearly indicate:
+
+- Its area of expertise.
+- When it should be used.
+- Some example scenarios.
+
+For example, the following sub-agent description should be called fairly
+consistently for Git operations.
+
+> Git expert agent which should be used for all local and remote git operations.
+> For example:
+>
+> - Making commits
+> - Searching for regressions with bisect
+> - Interacting with source control and issues providers such as GitHub.
+
+If you need to further tune your sub-agent, you can do so by selecting the model
+to optimize for with `/model` and then asking the model why it does not think
+that your sub-agent was called with a specific prompt and the given description.
+
+## Remote subagents (Agent2Agent) (experimental)
+
+Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent
+(A2A) protocol.
+
+> **Note: Remote subagents are currently an experimental feature.**
+
+See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed
+configuration and usage instructions.
+
+## Extension sub-agents
+
+Extensions can bundle and distribute sub-agents. See the
+[Extensions documentation](../extensions/index.md#sub-agents) for details on how
+to package agents within an extension.