@didim365/agent-cli-core 0.1.0

package/dist/docs/hooks/writing-hooks.md

@@ -0,0 +1,450 @@
+# Writing hooks for Gemini CLI
+
+This guide will walk you through creating hooks for Gemini CLI, from a simple
+logging hook to a comprehensive workflow assistant.
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- Gemini CLI installed and configured
+- Basic understanding of shell scripting or JavaScript/Node.js
+- Familiarity with JSON for hook input/output
+
+## Quick start
+
+Let's create a simple hook that logs all tool executions to understand the
+basics.
+
+**Crucial Rule:** Always write logs to `stderr`. Write only the final JSON to
+`stdout`.
+
+### Step 1: Create your hook script
+
+Create a directory for hooks and a simple logging script.
+
+> **Note**:
+>
+> This example uses `jq` to parse JSON. If you don't have it installed, you can
+> perform similar logic using Node.js or Python.
+
+```bash
+mkdir -p .gemini/hooks
+cat > .gemini/hooks/log-tools.sh << 'EOF'
+#!/usr/bin/env bash
+# Read hook input from stdin
+input=$(cat)
+
+# Extract tool name (requires jq)
+tool_name=$(echo "$input" | jq -r '.tool_name')
+
+# Log to stderr (visible in terminal if hook fails, or captured in logs)
+echo "Logging tool: $tool_name" >&2
+
+# Log to file
+echo "[$(date)] Tool executed: $tool_name" >> .gemini/tool-log.txt
+
+# Return success (exit 0) with empty JSON
+echo "{}"
+exit 0
+EOF
+
+chmod +x .gemini/hooks/log-tools.sh
+```
+
+## Exit Code Strategies
+
+There are two ways to control or block an action in Gemini CLI:
+
+| Strategy                   | Exit Code | Implementation                                                     | Best For                                                    |
+| :------------------------- | :-------- | :----------------------------------------------------------------- | :---------------------------------------------------------- |
+| **Structured (Idiomatic)** | `0`       | Return a JSON object like `{"decision": "deny", "reason": "..."}`. | Production hooks, custom user feedback, and complex logic.  |
+| **Emergency Brake**        | `2`       | Print the error message to `stderr` and exit.                      | Simple security gates, script errors, or rapid prototyping. |
+
+## Practical examples
+
+### Security: Block secrets in commits
+
+Prevent committing files containing API keys or passwords. Note that we use
+**Exit Code 0** to provide a structured denial message to the agent.
+
+**`.gemini/hooks/block-secrets.sh`:**
+
+```bash
+#!/usr/bin/env bash
+input=$(cat)
+
+# Extract content being written
+content=$(echo "$input" | jq -r '.tool_input.content // .tool_input.new_string // ""')
+
+# Check for secrets
+if echo "$content" | grep -qE 'api[_-]?key|password|secret'; then
+  # Log to stderr
+  echo "Blocked potential secret" >&2
+
+  # Return structured denial to stdout
+  cat <<EOF
+{
+  "decision": "deny",
+  "reason": "Security Policy: Potential secret detected in content.",
+  "systemMessage": "🔒 Security scanner blocked operation"
+}
+EOF
+  exit 0
+fi
+
+# Allow
+echo '{"decision": "allow"}'
+exit 0
+```
+
+### Dynamic context injection (Git History)
+
+Add relevant project context before each agent interaction.
+
+**`.gemini/hooks/inject-context.sh`:**
+
+```bash
+#!/usr/bin/env bash
+
+# Get recent git commits for context
+context=$(git log -5 --oneline 2>/dev/null || echo "No git history")
+
+# Return as JSON
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "BeforeAgent",
+    "additionalContext": "Recent commits:\n$context"
+  }
+}
+EOF
+```
+
+### RAG-based Tool Filtering (BeforeToolSelection)
+
+Use `BeforeToolSelection` to intelligently reduce the tool space. This example
+uses a Node.js script to check the user's prompt and allow only relevant tools.
+
+**`.gemini/hooks/filter-tools.js`:**
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+
+async function main() {
+  const input = JSON.parse(fs.readFileSync(0, 'utf-8'));
+  const { llm_request } = input;
+
+  // Decoupled API: Access messages from llm_request
+  const messages = llm_request.messages || [];
+  const lastUserMessage = messages
+    .slice()
+    .reverse()
+    .find((m) => m.role === 'user');
+
+  if (!lastUserMessage) {
+    console.log(JSON.stringify({})); // Do nothing
+    return;
+  }
+
+  const text = lastUserMessage.content;
+  const allowed = ['write_todos']; // Always allow memory
+
+  // Simple keyword matching
+  if (text.includes('read') || text.includes('check')) {
+    allowed.push('read_file', 'list_directory');
+  }
+  if (text.includes('test')) {
+    allowed.push('run_shell_command');
+  }
+
+  // If we found specific intent, filter tools. Otherwise allow all.
+  if (allowed.length > 1) {
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'BeforeToolSelection',
+          toolConfig: {
+            mode: 'ANY', // Force usage of one of these tools (or AUTO)
+            allowedFunctionNames: allowed,
+          },
+        },
+      }),
+    );
+  } else {
+    console.log(JSON.stringify({}));
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+**`.gemini/settings.json`:**
+
+```json
+{
+  "hooks": {
+    "BeforeToolSelection": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "intent-filter",
+            "type": "command",
+            "command": "node .gemini/hooks/filter-tools.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+> **TIP**
+>
+> **Union Aggregation Strategy**: `BeforeToolSelection` is unique in that it
+> combines the results of all matching hooks. If you have multiple filtering
+> hooks, the agent will receive the **union** of all whitelisted tools. Only
+> using `mode: "NONE"` will override other hooks to disable all tools.
+
+## Complete example: Smart Development Workflow Assistant
+
+This comprehensive example demonstrates all hook events working together. We
+will build a system that maintains memory, filters tools, and checks for
+security.
+
+### Architecture
+
+1. **SessionStart**: Load project memories.
+2. **BeforeAgent**: Inject memories into context.
+3. **BeforeToolSelection**: Filter tools based on intent.
+4. **BeforeTool**: Scan for secrets.
+5. **AfterModel**: Record interactions.
+6. **AfterAgent**: Validate final response quality (Retry).
+7. **SessionEnd**: Consolidate memories.
+
+### Configuration (`.gemini/settings.json`)
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "name": "init",
+            "type": "command",
+            "command": "node .gemini/hooks/init.js"
+          }
+        ]
+      }
+    ],
+    "BeforeAgent": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "memory",
+            "type": "command",
+            "command": "node .gemini/hooks/inject-memories.js"
+          }
+        ]
+      }
+    ],
+    "BeforeToolSelection": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "filter",
+            "type": "command",
+            "command": "node .gemini/hooks/rag-filter.js"
+          }
+        ]
+      }
+    ],
+    "BeforeTool": [
+      {
+        "matcher": "write_file",
+        "hooks": [
+          {
+            "name": "security",
+            "type": "command",
+            "command": "node .gemini/hooks/security.js"
+          }
+        ]
+      }
+    ],
+    "AfterModel": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "record",
+            "type": "command",
+            "command": "node .gemini/hooks/record.js"
+          }
+        ]
+      }
+    ],
+    "AfterAgent": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "validate",
+            "type": "command",
+            "command": "node .gemini/hooks/validate.js"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "exit",
+        "hooks": [
+          {
+            "name": "save",
+            "type": "command",
+            "command": "node .gemini/hooks/consolidate.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook Scripts
+
+> **Note**: For brevity, these scripts use `console.error` for logging and
+> standard `console.log` for JSON output.
+
+#### 1. Initialize (`init.js`)
+
+```javascript
+#!/usr/bin/env node
+// Initialize DB or resources
+console.error('Initializing assistant...');
+
+// Output to user
+console.log(
+  JSON.stringify({
+    systemMessage: '🧠 Smart Assistant Loaded',
+  }),
+);
+```
+
+#### 2. Inject Memories (`inject-memories.js`)
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+
+async function main() {
+  const input = JSON.parse(fs.readFileSync(0, 'utf-8'));
+  // Assume we fetch memories from a DB here
+  const memories = '- [Memory] Always use TypeScript for this project.';
+
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'BeforeAgent',
+        additionalContext: `\n## Relevant Memories\n${memories}`,
+      },
+    }),
+  );
+}
+main();
+```
+
+#### 3. Security Check (`security.js`)
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+const input = JSON.parse(fs.readFileSync(0));
+const content = input.tool_input.content || '';
+
+if (content.includes('SECRET_KEY')) {
+  console.log(
+    JSON.stringify({
+      decision: 'deny',
+      reason: 'Found SECRET_KEY in content',
+      systemMessage: '🚨 Blocked sensitive commit',
+    }),
+  );
+  process.exit(0);
+}
+
+console.log(JSON.stringify({ decision: 'allow' }));
+```
+
+#### 4. Record Interaction (`record.js`)
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const input = JSON.parse(fs.readFileSync(0));
+const { llm_request, llm_response } = input;
+const logFile = path.join(
+  process.env.GEMINI_PROJECT_DIR,
+  '.gemini/memory/session.jsonl',
+);
+
+fs.appendFileSync(
+  logFile,
+  JSON.stringify({
+    request: llm_request,
+    response: llm_response,
+    timestamp: new Date().toISOString(),
+  }) + '\n',
+);
+
+console.log(JSON.stringify({}));
+```
+
+#### 5. Validate Response (`validate.js`)
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+const input = JSON.parse(fs.readFileSync(0));
+const response = input.prompt_response;
+
+// Example: Check if the agent forgot to include a summary
+if (!response.includes('Summary:')) {
+  console.log(
+    JSON.stringify({
+      decision: 'block', // Triggers an automatic retry turn
+      reason: 'Your response is missing a Summary section. Please add one.',
+      systemMessage: '🔄 Requesting missing summary...',
+    }),
+  );
+  process.exit(0);
+}
+
+console.log(JSON.stringify({ decision: 'allow' }));
+```
+
+#### 6. Consolidate Memories (`consolidate.js`)
+
+```javascript
+#!/usr/bin/env node
+// Logic to save final session state
+console.error('Consolidating memories for session end...');
+```
+
+## Packaging as an extension
+
+While project-level hooks are great for specific repositories, you can share
+your hooks across multiple projects by packaging them as a
+[Gemini CLI extension](https://www.google.com/search?q=../extensions/index.md).
+This provides version control, easy distribution, and centralized management.

package/dist/docs/ide-integration/ide-companion-spec.md

@@ -0,0 +1,267 @@
+# Gemini CLI companion plugin: Interface specification
+
+> Last Updated: September 15, 2025
+
+This document defines the contract for building a companion plugin to enable
+Gemini CLI's IDE mode. For VS Code, these features (native diffing, context
+awareness) are provided by the official extension
+([marketplace](https://marketplace.visualstudio.com/items?itemName=Google.gemini-cli-vscode-ide-companion)).
+This specification is for contributors who wish to bring similar functionality
+to other editors like JetBrains IDEs, Sublime Text, etc.
+
+## I. The communication interface
+
+Gemini CLI and the IDE plugin communicate through a local communication channel.
+
+### 1. Transport layer: MCP over HTTP
+
+The plugin **MUST** run a local HTTP server that implements the **Model Context
+Protocol (MCP)**.
+
+- **Protocol:** The server must be a valid MCP server. We recommend using an
+  existing MCP SDK for your language of choice if available.
+- **Endpoint:** The server should expose a single endpoint (e.g., `/mcp`) for
+  all MCP communication.
+- **Port:** The server **MUST** listen on a dynamically assigned port (i.e.,
+  listen on port `0`).
+
+### 2. Discovery mechanism: The port file
+
+For Gemini CLI to connect, it needs to discover which IDE instance it's running
+in and what port your server is using. The plugin **MUST** facilitate this by
+creating a "discovery file."
+
+- **How the CLI finds the file:** The CLI determines the Process ID (PID) of the
+  IDE it's running in by traversing the process tree. It then looks for a
+  discovery file that contains this PID in its name.
+- **File location:** The file must be created in a specific directory:
+  `os.tmpdir()/gemini/ide/`. Your plugin must create this directory if it
+  doesn't exist.
+- **File naming convention:** The filename is critical and **MUST** follow the
+  pattern: `gemini-ide-server-${PID}-${PORT}.json`
+  - `${PID}`: The process ID of the parent IDE process. Your plugin must
+    determine this PID and include it in the filename.
+  - `${PORT}`: The port your MCP server is listening on.
+- **File content and workspace validation:** The file **MUST** contain a JSON
+  object with the following structure:
+
+  ```json
+  {
+    "port": 12345,
+    "workspacePath": "/path/to/project1:/path/to/project2",
+    "authToken": "a-very-secret-token",
+    "ideInfo": {
+      "name": "vscode",
+      "displayName": "VS Code"
+    }
+  }
+  ```
+  - `port` (number, required): The port of the MCP server.
+  - `workspacePath` (string, required): A list of all open workspace root paths,
+    delimited by the OS-specific path separator (`:` for Linux/macOS, `;` for
+    Windows). The CLI uses this path to ensure it's running in the same project
+    folder that's open in the IDE. If the CLI's current working directory is not
+    a sub-directory of `workspacePath`, the connection will be rejected. Your
+    plugin **MUST** provide the correct, absolute path(s) to the root of the
+    open workspace(s).
+  - `authToken` (string, required): A secret token for securing the connection.
+    The CLI will include this token in an `Authorization: Bearer <token>` header
+    on all requests.
+  - `ideInfo` (object, required): Information about the IDE.
+    - `name` (string, required): A short, lowercase identifier for the IDE
+      (e.g., `vscode`, `jetbrains`).
+    - `displayName` (string, required): A user-friendly name for the IDE (e.g.,
+      `VS Code`, `JetBrains IDE`).
+
+- **Authentication:** To secure the connection, the plugin **MUST** generate a
+  unique, secret token and include it in the discovery file. The CLI will then
+  include this token in the `Authorization` header for all requests to the MCP
+  server (e.g., `Authorization: Bearer a-very-secret-token`). Your server
+  **MUST** validate this token on every request and reject any that are
+  unauthorized.
+- **Tie-breaking with environment variables (recommended):** For the most
+  reliable experience, your plugin **SHOULD** both create the discovery file and
+  set the `GEMINI_CLI_IDE_SERVER_PORT` environment variable in the integrated
+  terminal. The file serves as the primary discovery mechanism, but the
+  environment variable is crucial for tie-breaking. If a user has multiple IDE
+  windows open for the same workspace, the CLI uses the
+  `GEMINI_CLI_IDE_SERVER_PORT` variable to identify and connect to the correct
+  window's server.
+
+## II. The context interface
+
+To enable context awareness, the plugin **MAY** provide the CLI with real-time
+information about the user's activity in the IDE.
+
+### `ide/contextUpdate` notification
+
+The plugin **MAY** send an `ide/contextUpdate`
+[notification](https://modelcontextprotocol.io/specification/2025-06-18/basic/index#notifications)
+to the CLI whenever the user's context changes.
+
+- **Triggering events:** This notification should be sent (with a recommended
+  debounce of 50ms) when:
+  - A file is opened, closed, or focused.
+  - The user's cursor position or text selection changes in the active file.
+- **Payload (`IdeContext`):** The notification parameters **MUST** be an
+  `IdeContext` object:
+
+  ```typescript
+  interface IdeContext {
+    workspaceState?: {
+      openFiles?: File[];
+      isTrusted?: boolean;
+    };
+  }
+
+  interface File {
+    // Absolute path to the file
+    path: string;
+    // Last focused Unix timestamp (for ordering)
+    timestamp: number;
+    // True if this is the currently focused file
+    isActive?: boolean;
+    cursor?: {
+      // 1-based line number
+      line: number;
+      // 1-based character number
+      character: number;
+    };
+    // The text currently selected by the user
+    selectedText?: string;
+  }
+  ```
+
+  **Note:** The `openFiles` list should only include files that exist on disk.
+  Virtual files (e.g., unsaved files without a path, editor settings pages)
+  **MUST** be excluded.
+
+### How the CLI uses this context
+
+After receiving the `IdeContext` object, the CLI performs several normalization
+and truncation steps before sending the information to the model.
+
+- **File ordering:** The CLI uses the `timestamp` field to determine the most
+  recently used files. It sorts the `openFiles` list based on this value.
+  Therefore, your plugin **MUST** provide an accurate Unix timestamp for when a
+  file was last focused.
+- **Active file:** The CLI considers only the most recent file (after sorting)
+  to be the "active" file. It will ignore the `isActive` flag on all other files
+  and clear their `cursor` and `selectedText` fields. Your plugin should focus
+  on setting `isActive: true` and providing cursor/selection details only for
+  the currently focused file.
+- **Truncation:** To manage token limits, the CLI truncates both the file list
+  (to 10 files) and the `selectedText` (to 16KB).
+
+While the CLI handles the final truncation, it is highly recommended that your
+plugin also limits the amount of context it sends.
+
+## III. The diffing interface
+
+To enable interactive code modifications, the plugin **MAY** expose a diffing
+interface. This allows the CLI to request that the IDE open a diff view, showing
+proposed changes to a file. The user can then review, edit, and ultimately
+accept or reject these changes directly within the IDE.
+
+### `openDiff` tool
+
+The plugin **MUST** register an `openDiff` tool on its MCP server.
+
+- **Description:** This tool instructs the IDE to open a modifiable diff view
+  for a specific file.
+- **Request (`OpenDiffRequest`):** The tool is invoked via a `tools/call`
+  request. The `arguments` field within the request's `params` **MUST** be an
+  `OpenDiffRequest` object.
+
+  ```typescript
+  interface OpenDiffRequest {
+    // The absolute path to the file to be diffed.
+    filePath: string;
+    // The proposed new content for the file.
+    newContent: string;
+  }
+  ```
+
+- **Response (`CallToolResult`):** The tool **MUST** immediately return a
+  `CallToolResult` to acknowledge the request and report whether the diff view
+  was successfully opened.
+  - On Success: If the diff view was opened successfully, the response **MUST**
+    contain empty content (i.e., `content: []`).
+  - On Failure: If an error prevented the diff view from opening, the response
+    **MUST** have `isError: true` and include a `TextContent` block in the
+    `content` array describing the error.
+
+  The actual outcome of the diff (acceptance or rejection) is communicated
+  asynchronously via notifications.
+
+### `closeDiff` tool
+
+The plugin **MUST** register a `closeDiff` tool on its MCP server.
+
+- **Description:** This tool instructs the IDE to close an open diff view for a
+  specific file.
+- **Request (`CloseDiffRequest`):** The tool is invoked via a `tools/call`
+  request. The `arguments` field within the request's `params` **MUST** be an
+  `CloseDiffRequest` object.
+
+  ```typescript
+  interface CloseDiffRequest {
+    // The absolute path to the file whose diff view should be closed.
+    filePath: string;
+  }
+  ```
+
+- **Response (`CallToolResult`):** The tool **MUST** return a `CallToolResult`.
+  - On Success: If the diff view was closed successfully, the response **MUST**
+    include a single **TextContent** block in the content array containing the
+    file's final content before closing.
+  - On Failure: If an error prevented the diff view from closing, the response
+    **MUST** have `isError: true` and include a `TextContent` block in the
+    `content` array describing the error.
+
+### `ide/diffAccepted` notification
+
+When the user accepts the changes in a diff view (e.g., by clicking an "Apply"
+or "Save" button), the plugin **MUST** send an `ide/diffAccepted` notification
+to the CLI.
+
+- **Payload:** The notification parameters **MUST** include the file path and
+  the final content of the file. The content may differ from the original
+  `newContent` if the user made manual edits in the diff view.
+
+  ```typescript
+  {
+    // The absolute path to the file that was diffed.
+    filePath: string;
+    // The full content of the file after acceptance.
+    content: string;
+  }
+  ```
+
+### `ide/diffRejected` notification
+
+When the user rejects the changes (e.g., by closing the diff view without
+accepting), the plugin **MUST** send an `ide/diffRejected` notification to the
+CLI.
+
+- **Payload:** The notification parameters **MUST** include the file path of the
+  rejected diff.
+
+  ```typescript
+  {
+    // The absolute path to the file that was diffed.
+    filePath: string;
+  }
+  ```
+
+## IV. The lifecycle interface
+
+The plugin **MUST** manage its resources and the discovery file correctly based
+on the IDE's lifecycle.
+
+- **On activation (IDE startup/plugin enabled):**
+  1.  Start the MCP server.
+  2.  Create the discovery file.
+- **On deactivation (IDE shutdown/plugin disabled):**
+  1.  Stop the MCP server.
+  2.  Delete the discovery file.