npm - @didim365/agent-cli-core - Versions diffs - 0.1.1 → 0.1.3 - Mend

@didim365/agent-cli-core 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1081) hide show

package/dist/docs/hooks/best-practices.md DELETED Viewed

@@ -1,677 +0,0 @@
-# Hooks Best Practices
-This guide covers security considerations, performance optimization, debugging
-techniques, and privacy considerations for developing and deploying hooks in
-Gemini CLI.
-## Performance
-### Keep hooks fast
-Hooks run synchronously—slow hooks delay the agent loop. Optimize for speed by
-using parallel operations:
-```javascript
-// Sequential operations are slower
-const data1 = await fetch(url1).then((r) => r.json());
-const data2 = await fetch(url2).then((r) => r.json());
-// Prefer parallel operations for better performance
-// Start requests concurrently
-const p1 = fetch(url1).then((r) => r.json());
-const p2 = fetch(url2).then((r) => r.json());
-// Wait for all results
-const [data1, data2] = await Promise.all([p1, p2]);
-```
-### Cache expensive operations
-Store results between invocations to avoid repeated computation, especially for
-hooks that run frequently (like `BeforeTool` or `AfterModel`).
-```javascript
-const fs = require('fs');
-const path = require('path');
-const CACHE_FILE = '.gemini/hook-cache.json';
-function readCache() {
-  try {
-    return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-function writeCache(data) {
-  fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
-}
-async function main() {
-  const cache = readCache();
-  const cacheKey = `tool-list-${(Date.now() / 3600000) | 0}`; // Hourly cache
-  if (cache[cacheKey]) {
-    // Write JSON to stdout
-    console.log(JSON.stringify(cache[cacheKey]));
-    return;
-  }
-  // Expensive operation
-  const result = await computeExpensiveResult();
-  cache[cacheKey] = result;
-  writeCache(cache);
-  console.log(JSON.stringify(result));
-}
-```
-### Use appropriate events
-Choose hook events that match your use case to avoid unnecessary execution.
-- **`AfterAgent`**: Fires **once** per turn after the model finishes its final
-  response. Use this for quality validation (Retries) or final logging.
-- **`AfterModel`**: Fires after **every chunk** of LLM output. Use this for
-  real-time redaction, PII filtering, or monitoring output as it streams.
-If you only need to check the final completion, use `AfterAgent` to save
-performance.
-### Filter with matchers
-Use specific matchers to avoid unnecessary hook execution. Instead of matching
-all tools with `*`, specify only the tools you need. This saves the overhead of
-spawning a process for irrelevant events.
-```json
-{
-  "matcher": "write_file|replace",
-  "hooks": [
-    {
-      "name": "validate-writes",
-      "type": "command",
-      "command": "./validate.sh"
-    }
-  ]
-}
-```
-### Optimize JSON parsing
-For large inputs (like `AfterModel` receiving a large context), standard JSON
-parsing can be slow. If you only need one field, consider streaming parsers or
-lightweight extraction logic, though for most shell scripts `jq` is sufficient.
-## Debugging
-### The "Strict JSON" rule
-The most common cause of hook failure is "polluting" the standard output.
-- **stdout** is for **JSON only**.
-- **stderr** is for **logs and text**.
-**Good:**
-```bash
-#!/bin/bash
-echo "Starting check..." >&2  # <--- Redirect to stderr
-echo '{"decision": "allow"}'
-```
-### Log to files
-Since hooks run in the background, writing to a dedicated log file is often the
-easiest way to debug complex logic.
-```bash
-#!/usr/bin/env bash
-LOG_FILE=".gemini/hooks/debug.log"
-# Log with timestamp
-log() {
-  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"
-}
-input=$(cat)
-log "Received input: ${input:0:100}..."
-# Hook logic here
-log "Hook completed successfully"
-# Always output valid JSON to stdout at the end, even if just empty
-echo "{}"
-```
-### Use stderr for errors
-Error messages on stderr are surfaced appropriately based on exit codes:
-```javascript
-try {
-  const result = dangerousOperation();
-  console.log(JSON.stringify({ result }));
-} catch (error) {
-  // Write the error description to stderr so the user/agent sees it
-  console.error(`Hook error: ${error.message}`);
-  process.exit(2); // Blocking error
-}
-```
-### Test hooks independently
-Run hook scripts manually with sample JSON input to verify they behave as
-expected before hooking them up to the CLI.
-```bash
-# Create test input
-cat > test-input.json << 'EOF'
-{
-  "session_id": "test-123",
-  "cwd": "/tmp/test",
-  "hook_event_name": "BeforeTool",
-  "tool_name": "write_file",
-  "tool_input": {
-    "file_path": "test.txt",
-    "content": "Test content"
-  }
-}
-EOF
-# Test the hook
-cat test-input.json | .gemini/hooks/my-hook.sh
-# Check exit code
-echo "Exit code: $?"
-```
-### Check exit codes
-Gemini CLI uses exit codes for high-level flow control:
-- **Exit 0 (Success)**: The hook ran successfully. The CLI parses `stdout` for
-  JSON decisions.
-- **Exit 2 (System Block)**: A critical block occurred. `stderr` is used as the
-  reason.
-  - For **Agent/Model** events, this aborts the turn.
-  - For **Tool** events, this blocks the tool but allows the agent to continue.
-  - For **AfterAgent**, this triggers an automatic retry turn.
-> **TIP**
->
-> **Blocking vs. Stopping**: Use `decision: "deny"` (or Exit Code 2) to block a
-> **specific action**. Use `{"continue": false}` in your JSON output to **kill
-> the entire agent loop** immediately.
-```bash
-#!/usr/bin/env bash
-set -e
-# Hook logic
-if process_input; then
-  echo '{"decision": "allow"}'
-  exit 0
-else
-  echo "Critical validation failure" >&2
-  exit 2
-fi
-```
-### Enable telemetry
-Hook execution is logged when `telemetry.logPrompts` is enabled. You can view
-these logs to debug execution flow.
-```json
-{
-  "telemetry": {
-    "logPrompts": true
-  }
-}
-```
-### Use hook panel
-The `/hooks panel` command inside the CLI shows execution status and recent
-output:
-```bash
-/hooks panel
-```
-Check for:
-- Hook execution counts
-- Recent successes/failures
-- Error messages
-- Execution timing
-## Development
-### Start simple
-Begin with basic logging hooks before implementing complex logic:
-```bash
-#!/usr/bin/env bash
-# Simple logging hook to understand input structure
-input=$(cat)
-echo "$input" >> .gemini/hook-inputs.log
-# Always return valid JSON
-echo "{}"
-```
-### Documenting your hooks
-Maintainability is critical for complex hook systems. Use descriptions and
-comments to help yourself and others understand why a hook exists.
-**Use the `description` field**: This text is displayed in the `/hooks panel` UI
-and helps diagnose issues.
-```json
-{
-  "hooks": {
-    "BeforeTool": [
-      {
-        "matcher": "write_file|replace",
-        "hooks": [
-          {
-            "name": "secret-scanner",
-            "type": "command",
-            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh",
-            "description": "Scans code changes for API keys and secrets before writing"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-**Add comments in hook scripts**: Explain performance expectations and
-dependencies.
-```javascript
-#!/usr/bin/env node
-/**
- * RAG Tool Filter Hook
- *
- * Reduces the tool space by extracting keywords from the user's request.
- *
- * Performance: ~500ms average
- * Dependencies: @google/generative-ai
- */
-```
-### Use JSON libraries
-Parse JSON with proper libraries instead of text processing.
-**Bad:**
-```bash
-# Fragile text parsing
-tool_name=$(echo "$input" | grep -oP '"tool_name":\s*"\K[^"]+')
-```
-**Good:**
-```bash
-# Robust JSON parsing
-tool_name=$(echo "$input" | jq -r '.tool_name')
-```
-### Make scripts executable
-Always make hook scripts executable:
-```bash
-chmod +x .gemini/hooks/*.sh
-chmod +x .gemini/hooks/*.js
-```
-### Version control
-Commit hooks to share with your team:
-```bash
-git add .gemini/hooks/
-git add .gemini/settings.json
-```
-**`.gitignore` considerations:**
-```gitignore
-# Ignore hook cache and logs
-.gemini/hook-cache.json
-.gemini/hook-debug.log
-.gemini/memory/session-*.jsonl
-# Keep hook scripts
-!.gemini/hooks/*.sh
-!.gemini/hooks/*.js
-```
-## Hook security
-### Threat Model
-Understanding where hooks come from and what they can do is critical for secure
-usage.
-| Hook Source                   | Description                                                                                                                |
-| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
-| **System**                    | Configured by system administrators (e.g., `/etc/gemini-cli/settings.json`, `/Library/...`). Assumed to be the **safest**. |
-| **User** (`~/.gemini/...`)    | Configured by you. You are responsible for ensuring they are safe.                                                         |
-| **Extensions**                | You explicitly approve and install these. Security depends on the extension source (integrity).                            |
-| **Project** (`./.gemini/...`) | **Untrusted by default.** Safest in trusted internal repos; higher risk in third-party/public repos.                       |
-#### Project Hook Security
-When you open a project with hooks defined in `.gemini/settings.json`:
-1. **Detection**: Gemini CLI detects the hooks.
-2. **Identification**: A unique identity is generated for each hook based on its
-   `name` and `command`.
-3. **Warning**: If this specific hook identity has not been seen before, a
-   **warning** is displayed.
-4. **Execution**: The hook is executed (unless specific security settings block
-   it).
-5. **Trust**: The hook is marked as "trusted" for this project.
-> **Modification detection**: If the `command` string of a project hook is
-> changed (e.g., by a `git pull`), its identity changes. Gemini CLI will treat
-> it as a **new, untrusted hook** and warn you again. This prevents malicious
-> actors from silently swapping a verified command for a malicious one.
-### Risks
-| Risk                         | Description                                                                                                                          |
-| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
-| **Arbitrary Code Execution** | Hooks run as your user. They can do anything you can do (delete files, install software).                                            |
-| **Data Exfiltration**        | A hook could read your input (prompts), output (code), or environment variables (`GEMINI_API_KEY`) and send them to a remote server. |
-| **Prompt Injection**         | Malicious content in a file or web page could trick an LLM into running a tool that triggers a hook in an unexpected way.            |
-### Mitigation Strategies
-#### Verify the source
-**Verify the source** of any project hooks or extensions before enabling them.
-- For open-source projects, a quick review of the hook scripts is recommended.
-- For extensions, ensure you trust the author or publisher (e.g., verified
-  publishers, well-known community members).
-- Be cautious with obfuscated scripts or compiled binaries from unknown sources.
-#### Sanitize environment
-Hooks inherit the environment of the Gemini CLI process, which may include
-sensitive API keys. Gemini CLI provides a
-[redaction system](/docs/get-started/configuration#environment-variable-redaction)
-that automatically filters variables matching sensitive patterns (e.g., `KEY`,
-`TOKEN`).
-> **Disabled by Default**: Environment redaction is currently **OFF by
-> default**. We strongly recommend enabling it if you are running third-party
-> hooks or working in sensitive environments.
-**Impact on hooks:**
-- **Security**: Prevents your hook scripts from accidentally leaking secrets.
-- **Troubleshooting**: If your hook depends on a specific environment variable
-  that is being blocked, you must explicitly allow it in `settings.json`.
-```json
-{
-  "security": {
-    "environmentVariableRedaction": {
-      "enabled": true,
-      "allowed": ["MY_REQUIRED_TOOL_KEY"]
-    }
-  }
-}
-```
-**System administrators:** You can enforce redaction for all users in the system
-configuration.
-## Troubleshooting
-### Hook not executing
-**Check hook name in `/hooks panel`:** Verify the hook appears in the list and
-is enabled.
-**Verify matcher pattern:**
-```bash
-# Test regex pattern
-echo "write_file|replace" | grep -E "write_.*|replace"
-```
-**Check disabled list:** Verify the hook is not listed in your `settings.json`:
-```json
-{
-  "hooks": {
-    "disabled": ["my-hook-name"]
-  }
-}
-```
-**Ensure script is executable**: For macOS and Linux users, verify the script
-has execution permissions:
-```bash
-ls -la .gemini/hooks/my-hook.sh
-chmod +x .gemini/hooks/my-hook.sh
-```
-**Verify script path:** Ensure the path in `settings.json` resolves correctly.
-```bash
-# Check path expansion
-echo "$GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh"
-# Verify file exists
-test -f "$GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh" && echo "File exists"
-```
-### Hook timing out
-**Check configured timeout:** The default is 60000ms (1 minute). You can
-increase this in `settings.json`:
-```json
-{
-  "name": "slow-hook",
-  "timeout": 120000
-}
-```
-**Optimize slow operations:** Move heavy processing to background tasks or use
-caching.
-### Invalid JSON output
-**Validate JSON before outputting:**
-```bash
-#!/usr/bin/env bash
-output='{"decision": "allow"}'
-# Validate JSON
-if echo "$output" | jq empty 2>/dev/null; then
-  echo "$output"
-else
-  echo "Invalid JSON generated" >&2
-  exit 1
-fi
-```
-### Environment variables not available
-**Check if variable is set:**
-```bash
-#!/usr/bin/env bash
-if [ -z "$GEMINI_PROJECT_DIR" ]; then
-  echo "GEMINI_PROJECT_DIR not set" >&2
-  exit 1
-fi
-```
-**Debug available variables:**
-```bash
-env > .gemini/hook-env.log
-```
-## Authoring secure hooks
-When writing your own hooks, follow these practices to ensure they are robust
-and secure.
-### Validate all inputs
-Never trust data from hooks without validation. Hook inputs often come from the
-LLM or user prompts, which can be manipulated.
-```bash
-#!/usr/bin/env bash
-input=$(cat)
-# Validate JSON structure
-if ! echo "$input" | jq empty 2>/dev/null; then
-  echo "Invalid JSON input" >&2
-  exit 1
-fi
-# Validate tool_name explicitly
-tool_name=$(echo "$input" | jq -r '.tool_name // empty')
-if [[ "$tool_name" != "write_file" && "$tool_name" != "read_file" ]]; then
-  echo "Unexpected tool: $tool_name" >&2
-  exit 1
-fi
-```
-### Use timeouts
-Prevent denial-of-service (hanging agents) by enforcing timeouts. Gemini CLI
-defaults to 60 seconds, but you should set stricter limits for fast hooks.
-```json
-{
-  "hooks": {
-    "BeforeTool": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "name": "fast-validator",
-            "type": "command",
-            "command": "./hooks/validate.sh",
-            "timeout": 5000 // 5 seconds
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-### Limit permissions
-Run hooks with minimal required permissions:
-```bash
-#!/usr/bin/env bash
-# Don't run as root
-if [ "$EUID" -eq 0 ]; then
-  echo "Hook should not run as root" >&2
-  exit 1
-fi
-# Check file permissions before writing
-if [ -w "$file_path" ]; then
-  # Safe to write
-else
-  echo "Insufficient permissions" >&2
-  exit 1
-fi
-```
-### Example: Secret Scanner
-Use `BeforeTool` hooks to prevent committing sensitive data. This is a powerful
-pattern for enhancing security in your workflow.
-```javascript
-const SECRET_PATTERNS = [
-  /api[_-]?key\s*[:=]\s*['"]?[a-zA-Z0-9_-]{20,}['"]?/i,
-  /password\s*[:=]\s*['"]?[^\s'"]{8,}['"]?/i,
-  /secret\s*[:=]\s*['"]?[a-zA-Z0-9_-]{20,}['"]?/i,
-  /AKIA[0-9A-Z]{16}/, // AWS access key
-  /ghp_[a-zA-Z0-9]{36}/, // GitHub personal access token
-  /sk-[a-zA-Z0-9]{48}/, // OpenAI API key
-];
-function containsSecret(content) {
-  return SECRET_PATTERNS.some((pattern) => pattern.test(content));
-}
-```
-## Privacy considerations
-Hook inputs and outputs may contain sensitive information.
-### What data is collected
-Hook telemetry may include inputs (prompts, code) and outputs (decisions,
-reasons) unless disabled.
-### Privacy settings
-**Disable PII logging:** If you are working with sensitive data, disable prompt
-logging in your settings:
-```json
-{
-  "telemetry": {
-    "logPrompts": false
-  }
-}
-```
-**Suppress Output:** Individual hooks can request their metadata be hidden from
-logs and telemetry by returning `"suppressOutput": true` in their JSON response.
-> **Note**
-> `suppressOutput` only affects background logging. Any `systemMessage` or
-> `reason` included in the JSON will still be displayed to the user in the
-> terminal.
-### Sensitive data in hooks
-If your hooks process sensitive data:
-1. **Minimize logging:** Don't write sensitive data to log files.
-2. **Sanitize outputs:** Remove sensitive data before outputting JSON or writing
-   to stderr.