@anthropic-field/core 0.1.0

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
+  - search_file_content
+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.                                         |
+| `timeout_mins` | number | No       | Maximum execution time in minutes.                                                                                         |
+
+### 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.

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.

package/dist/docs/examples/proxy-script.md

@@ -0,0 +1,83 @@
+# Example proxy script
+
+The following is an example of a proxy script that can be used with the
+`GEMINI_SANDBOX_PROXY_COMMAND` environment variable. This script only allows
+`HTTPS` connections to `example.com:443` and declines all other requests.
+
+```javascript
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Example proxy server that listens on :::8877 and only allows HTTPS connections to example.com.
+// Set `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` to run proxy alongside sandbox
+// Test via `curl https://example.com` inside sandbox (in shell mode or via shell tool)
+
+import http from 'node:http';
+import net from 'node:net';
+import { URL } from 'node:url';
+import console from 'node:console';
+
+const PROXY_PORT = 8877;
+const ALLOWED_DOMAINS = ['example.com', 'googleapis.com'];
+const ALLOWED_PORT = '443';
+
+const server = http.createServer((req, res) => {
+  // Deny all requests other than CONNECT for HTTPS
+  console.log(
+    `[PROXY] Denying non-CONNECT request for: ${req.method} ${req.url}`,
+  );
+  res.writeHead(405, { 'Content-Type': 'text/plain' });
+  res.end('Method Not Allowed');
+});
+
+server.on('connect', (req, clientSocket, head) => {
+  // req.url will be in the format "hostname:port" for a CONNECT request.
+  const { port, hostname } = new URL(`http://${req.url}`);
+
+  console.log(`[PROXY] Intercepted CONNECT request for: ${hostname}:${port}`);
+
+  if (
+    ALLOWED_DOMAINS.some(
+      (domain) => hostname == domain || hostname.endsWith(`.${domain}`),
+    ) &&
+    port === ALLOWED_PORT
+  ) {
+    console.log(`[PROXY] Allowing connection to ${hostname}:${port}`);
+
+    // Establish a TCP connection to the original destination.
+    const serverSocket = net.connect(port, hostname, () => {
+      clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      // Create a tunnel by piping data between the client and the destination server.
+      serverSocket.write(head);
+      serverSocket.pipe(clientSocket);
+      clientSocket.pipe(serverSocket);
+    });
+
+    serverSocket.on('error', (err) => {
+      console.error(`[PROXY] Error connecting to destination: ${err.message}`);
+      clientSocket.end(`HTTP/1.1 502 Bad Gateway\r\n\r\n`);
+    });
+  } else {
+    console.log(`[PROXY] Denying connection to ${hostname}:${port}`);
+    clientSocket.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+  }
+
+  clientSocket.on('error', (err) => {
+    // This can happen if the client hangs up.
+    console.error(`[PROXY] Client socket error: ${err.message}`);
+  });
+});
+
+server.listen(PROXY_PORT, () => {
+  const address = server.address();
+  console.log(`[PROXY] Proxy listening on ${address.address}:${address.port}`);
+  console.log(
+    `[PROXY] Allowing HTTPS connections to domains: ${ALLOWED_DOMAINS.join(', ')}`,
+  );
+});
+```

package/dist/docs/extensions/best-practices.md

@@ -0,0 +1,139 @@
+# Extensions on Gemini CLI: Best practices
+
+This guide covers best practices for developing, securing, and maintaining
+Gemini CLI extensions.
+
+## Development
+
+Developing extensions for Gemini CLI is intended to be a lightweight, iterative
+process.
+
+### Structure your extension
+
+While simple extensions can just be a few files, we recommend a robust structure
+for complex extensions:
+
+```
+my-extension/
+├── package.json
+├── tsconfig.json
+├── gemini-extension.json
+├── src/
+│   ├── index.ts
+│   └── tools/
+└── dist/
+```
+
+- **Use TypeScript**: We strongly recommend using TypeScript for type safety and
+  better tooling.
+- **Separate source and build**: Keep your source code in `src` and build to
+  `dist`.
+- **Bundle dependencies**: If your extension has many dependencies, consider
+  bundling them (e.g., with `esbuild` or `webpack`) to reduce install time and
+  potential conflicts.
+
+### Iterate with `link`
+
+Use `gemini extensions link` to develop locally without constantly reinstalling:
+
+```bash
+cd my-extension
+gemini extensions link .
+```
+
+Changes to your code (after rebuilding) will be immediately available in the CLI
+on restart.
+
+### Use `GEMINI.md` effectively
+
+Your `GEMINI.md` file provides context to the model. Keep it focused:
+
+- **Do:** Explain high-level goals and how to use the provided tools.
+- **Don't:** Dump your entire documentation.
+- **Do:** Use clear, concise language.
+
+## Security
+
+When building a Gemini CLI extension, follow general security best practices
+(such as least privilege and input validation) to reduce risk.
+
+### Minimal permissions
+
+When defining tools in your MCP server, only request the permissions necessary.
+Avoid giving the model broad access (like full shell access) if a more
+restricted set of tools will suffice.
+
+If you must use powerful tools like `run_shell_command`, consider restricting
+them to specific commands in your `gemini-extension.json`:
+
+```json
+{
+  "name": "my-safe-extension",
+  "excludeTools": ["run_shell_command(rm -rf *)"]
+}
+```
+
+This ensures that even if the model tries to execute a dangerous command, it
+will be blocked at the CLI level.
+
+### Validate inputs
+
+Your MCP server is running on the user's machine. Always validate inputs to your
+tools to prevent arbitrary code execution or filesystem access outside the
+intended scope.
+
+```typescript
+// Good: Validating paths
+if (!path.resolve(inputPath).startsWith(path.resolve(allowedDir) + path.sep)) {
+  throw new Error('Access denied');
+}
+```
+
+### Sensitive settings
+
+If your extension requires API keys, use the `sensitive: true` option in
+`gemini-extension.json`. This ensures keys are stored securely in the system
+keychain and obfuscated in the UI.
+
+```json
+"settings": [
+  {
+    "name": "API Key",
+    "envVar": "MY_API_KEY",
+    "sensitive": true
+  }
+]
+```
+
+## Releasing
+
+You can upload your extension directly to GitHub to list it in the gallery.
+Gemini CLI extensions also offers support for more complicated
+[releases](releasing.md).
+
+### Semantic versioning
+
+Follow [Semantic Versioning](https://semver.org/).
+
+- **Major**: Breaking changes (renaming tools, changing arguments).
+- **Minor**: New features (new tools, commands).
+- **Patch**: Bug fixes.
+
+### Release Channels
+
+Use git branches to manage release channels (e.g., `main` for stable, `dev` for
+bleeding edge). This allows users to choose their stability level:
+
+```bash
+# Stable
+gemini extensions install github.com/user/repo
+
+# Dev
+gemini extensions install github.com/user/repo --ref dev
+```
+
+### Clean artifacts
+
+If you are using GitHub Releases, ensure your release artifacts only contain the
+necessary files (`dist/`, `gemini-extension.json`, `package.json`). Exclude
+`node_modules` (users will install them) and `src/` to keep downloads small.

package/dist/docs/extensions/index.md

@@ -0,0 +1,45 @@
+# Gemini CLI extensions
+
+Gemini CLI extensions package prompts, MCP servers, custom commands, hooks,
+sub-agents, and agent skills into a familiar and user-friendly format. With
+extensions, you can expand the capabilities of Gemini CLI and share those
+capabilities with others. They are designed to be easily installable and
+shareable.
+
+To see examples of extensions, you can browse a gallery of
+[Gemini CLI extensions](https://geminicli.com/extensions/browse/).
+
+## Managing extensions
+
+You can verify your installed extensions and their status using the interactive
+command:
+
+```bash
+/extensions list
+```
+
+or in noninteractive mode:
+
+```bash
+gemini extensions list
+```
+
+## Installation
+
+To install a real extension, you can use the `extensions install` command with a
+GitHub repository URL in noninteractive mode. For example:
+
+```bash
+gemini extensions install https://github.com/gemini-cli-extensions/workspace
+```
+
+## Next steps
+
+- [Writing extensions](writing-extensions.md): Learn how to create your first
+  extension.
+- [Extensions reference](reference.md): Deeply understand the extension format,
+  commands, and configuration.
+- [Best practices](best-practices.md): Learn strategies for building great
+  extensions.
+- [Extensions releasing](releasing.md): Learn how to share your extensions with
+  the world.