@meowlynxsea/koi 0.1.0

package/src/tools/bash.ts

@@ -0,0 +1,148 @@
+/**
+ * BashTool — Shell execution with safety controls
+ *
+ * Features:
+ * - Timeout with SIGTERM → SIGKILL escalation
+ * - Output size limit (capped to prevent context overflow)
+ * - Dangerous command warnings (displayed but not blocking)
+ */
+
+import { Type } from "typebox";
+import { spawn } from "child_process";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { checkPermission, isDangerousBashCommand } from "../agent/check-permissions.js";
+import { requestPermission } from "../agent/permission-ui.js";
+import { withWriteLock } from "../agent/tool-orchestration.js";
+import type { ToolResultWithError } from "./types.js";
+
+export const bashSchema = Type.Object({
+  command: Type.String({ description: "Bash command to execute" }),
+  timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 60). For long-running tasks that exceed this limit, use CreateMonitor instead.", default: 60 })),
+});
+
+export type BashToolInput = {
+  command: string;
+  timeout?: number;
+};
+
+const MAX_OUTPUT_CHARS = 200_000;
+
+function execBash(command: string, timeoutSec?: number): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
+  return new Promise((resolve, reject) => {
+    const shell = process.platform === "win32" ? "cmd" : "bash";
+    const shellFlag = process.platform === "win32" ? "/c" : "-c";
+    const child = spawn(shell, [shellFlag, command], {
+      cwd: process.cwd(),
+      env: { ...process.env, CLAUDECODE: "1", GIT_EDITOR: "true" },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
+    const effectiveTimeout = timeoutSec ?? 60;
+    if (effectiveTimeout > 0) {
+      timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+          if (!child.killed) child.kill("SIGKILL");
+        }, 5000);
+      }, effectiveTimeout * 1000);
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf-8");
+      if (stdout.length + stderr.length > MAX_OUTPUT_CHARS * 2) {
+        child.kill("SIGKILL");
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf-8");
+      if (stdout.length + stderr.length > MAX_OUTPUT_CHARS * 2) {
+        child.kill("SIGKILL");
+      }
+    });
+
+    child.on("error", (err) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      reject(err);
+    });
+
+    child.on("close", (code) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      resolve({ stdout, stderr, exitCode: code ?? 0, timedOut });
+    });
+  });
+}
+
+export async function executeBash(params: BashToolInput): Promise<{ content: TextContent[]; details: { exitCode: number; timedOut: boolean } }> {
+  const { stdout, stderr, exitCode, timedOut } = await execBash(params.command, params.timeout);
+
+  let output = stdout;
+  if (stderr) {
+    output += (output ? "\n\n" : "") + `[stderr]\n${stderr}`;
+  }
+  if (timedOut) {
+    output += "\n\n[Command timed out and was terminated]";
+  }
+  if (output.length > MAX_OUTPUT_CHARS) {
+    output = output.slice(0, MAX_OUTPUT_CHARS) + `\n\n[Output truncated: ${output.length} chars total, limit: ${MAX_OUTPUT_CHARS}]`;
+  }
+
+  const warning = isDangerousBashCommand(params.command)
+    ? "\n\n[Warning: This command may be destructive. Proceed with caution.]"
+    : "";
+
+  return {
+    content: [{ type: "text", text: output + warning }],
+    details: { exitCode, timedOut },
+  };
+}
+
+export function createBashToolDefinition(_cwd: string): ToolDefinition<typeof bashSchema, { exitCode: number; timedOut: boolean }> {
+  return {
+    name: "bash",
+    label: "Bash",
+    description:
+      "Execute a bash command in the environment.\n\n" +
+      "IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands. " +
+      "Instead, use the appropriate dedicated tool.\n\n" +
+      "Git Safety Protocol:\n" +
+      "- NEVER update the git config\n" +
+      "- NEVER run destructive git commands (push --force, reset --hard, checkout .) unless explicitly requested\n" +
+      "- NEVER use git commands with the -i flag (interactive)\n" +
+      "- NEVER skip hooks (--no-verify, --no-gpg-sign) unless explicitly asked",
+    promptSnippet: "Bash: execute shell commands (last resort — prefer dedicated tools)",
+    parameters: bashSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      return withWriteLock(async () => {
+        const perm = checkPermission("bash", params);
+        if (perm.decision === "deny") {
+          const result: ToolResultWithError<{ exitCode: number; timedOut: boolean }> = {
+            content: [{ type: "text", text: `Permission denied: ${perm.reason ?? "bash operation blocked"}` }],
+            details: { exitCode: 1, timedOut: false },
+            isError: true,
+          };
+          return result;
+        }
+        if (perm.decision === "ask") {
+          const allowed = await requestPermission({ toolName: "bash", args: params, reason: perm.reason ?? "Confirm shell command" });
+          if (!allowed) {
+            const result: ToolResultWithError<{ exitCode: number; timedOut: boolean }> = {
+              content: [{ type: "text", text: "User denied permission to execute command." }],
+              details: { exitCode: 1, timedOut: false },
+              isError: true,
+            };
+            return result;
+          }
+        }
+        return await executeBash(params);
+      });
+    },
+  };
+}

package/src/tools/edit.ts

@@ -0,0 +1,164 @@
+/**
+ * FileEditTool — Exact string replacement in files
+ *
+ * Features:
+ * - Exact string matching with quote normalization (smart → straight quotes)
+ * - Uniqueness check: old_string must be unique unless replace_all is true
+ * - Diff generation using the `diff` library
+ * - CRLF normalization and preservation on write
+ */
+
+import { Type } from "typebox";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { structuredPatch } from "diff";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { checkPermission } from "../agent/check-permissions.js";
+import { requestPermission } from "../agent/permission-ui.js";
+import { withWriteLock } from "../agent/tool-orchestration.js";
+import type { ToolResultWithError } from "./types.js";
+
+export const editSchema = Type.Object({
+  path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+  old_string: Type.String({ description: "Exact text to replace. Must be unique in the file unless replace_all is true." }),
+  new_string: Type.String({ description: "Replacement text" }),
+  replace_all: Type.Optional(Type.Boolean({ description: "Replace all occurrences (default: false)" })),
+});
+
+export type EditToolInput = {
+  path: string;
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+};
+
+// Smart quotes → straight quotes
+function normalizeQuotes(s: string): string {
+  return s
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+    .replace(/[\u2032\u2033]/g, "'");
+}
+
+function findActualString(fileContent: string, searchString: string): string | null {
+  if (fileContent.includes(searchString)) {
+    return searchString;
+  }
+  const normalizedSearch = normalizeQuotes(searchString);
+  const normalizedFile = normalizeQuotes(fileContent);
+  const idx = normalizedFile.indexOf(normalizedSearch);
+  if (idx >= 0) {
+    // Return the original substring from file (preserves original quote style)
+    return fileContent.slice(idx, idx + searchString.length);
+  }
+  return null;
+}
+
+function generateDiff(filePath: string, oldContent: string, newContent: string): string {
+  const patch = structuredPatch(filePath, filePath, oldContent, newContent, "", "", { context: 8 });
+  if (!patch || patch.hunks.length === 0) return "";
+  let result = `--- ${filePath}\n+++ ${filePath}\n`;
+  for (const hunk of patch.hunks) {
+    result += `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@\n`;
+    for (const line of hunk.lines) {
+      result += line + "\n";
+    }
+  }
+  return result;
+}
+
+export async function executeEdit(params: EditToolInput): Promise<{ content: TextContent[]; details: { replacements: number; diff: string } }> {
+  const filePath = resolve(params.path);
+
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${params.path}`);
+  }
+
+  const buffer = readFileSync(filePath);
+  const encoding = buffer[0] === 0xff && buffer[1] === 0xfe ? "utf16le" : "utf8";
+  const originalContent = buffer.toString(encoding);
+  const crlf = originalContent.includes("\r\n");
+  const fileContent = originalContent.replace(/\r\n/g, "\n");
+
+  if (params.old_string === params.new_string) {
+    throw new Error("old_string and new_string are identical — no change needed.");
+  }
+
+  const actualOld = findActualString(fileContent, params.old_string);
+  if (actualOld === null) {
+    throw new Error(
+      `Could not find the string to replace in ${params.path}.\n` +
+      `Make sure old_string matches exactly (including indentation).`
+    );
+  }
+
+  const matches = fileContent.split(actualOld).length - 1;
+  if (matches > 1 && !params.replace_all) {
+    throw new Error(
+      `Found ${matches} matches of the string to replace, but replace_all is false.\n` +
+      `To replace all occurrences, set replace_all to true. ` +
+      `To replace only one occurrence, provide more context to uniquely identify the instance.`
+    );
+  }
+
+  const newContent = params.replace_all
+    ? fileContent.split(actualOld).join(params.new_string)
+    : fileContent.replace(actualOld, params.new_string);
+
+  const diff = generateDiff(params.path, fileContent, newContent);
+
+  // Restore original line endings if file had CRLF
+  const outputContent = crlf ? newContent.replace(/\n/g, "\r\n") : newContent;
+  writeFileSync(filePath, outputContent, encoding as "utf-8");
+
+  const replacementCount = params.replace_all ? matches : 1;
+  const diffDisplay = diff ? `\n\nDiff:\n${diff}` : "";
+
+  return {
+    content: [{ type: "text", text: `File edited: ${params.path}${diffDisplay}` }],
+    details: { replacements: replacementCount, diff },
+  };
+}
+
+export function createEditToolDefinition(_cwd: string): ToolDefinition<typeof editSchema, { replacements: number; diff: string }> {
+  return {
+    name: "edit",
+    label: "Edit",
+    description:
+      "Performs exact string replacements in files.\n\n" +
+      "Usage:\n" +
+      "- You must use your Read tool at least once in the conversation before editing.\n" +
+      "- When editing text from Read tool output, preserve the exact indentation.\n" +
+      "- ALWAYS prefer editing existing files. NEVER write new files unless required.\n" +
+      "- The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more context or use replace_all.",
+    promptSnippet: "Edit: targeted string replacement in existing files",
+    parameters: editSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      return withWriteLock(async () => {
+        const perm = checkPermission("edit", params);
+        if (perm.decision === "deny") {
+          const result: ToolResultWithError<{ replacements: number; diff: string }> = {
+            content: [{ type: "text", text: `Permission denied: ${perm.reason ?? "edit operation blocked"}` }],
+            details: { replacements: 0, diff: "" },
+            isError: true,
+          };
+          return result;
+        }
+        if (perm.decision === "ask") {
+          const allowed = await requestPermission({ toolName: "edit", args: params, reason: perm.reason ?? "Confirm file edit" });
+          if (!allowed) {
+            const result: ToolResultWithError<{ replacements: number; diff: string }> = {
+              content: [{ type: "text", text: "User denied permission to edit file." }],
+              details: { replacements: 0, diff: "" },
+              isError: true,
+            };
+            return result;
+          }
+        }
+        return await executeEdit(params);
+      });
+    },
+  };
+}

package/src/tools/glob.ts

@@ -0,0 +1,102 @@
+/**
+ * GlobTool — Fast file pattern matching
+ *
+ * Supports glob patterns like "** /*.js" or "src/** /*.ts".
+ * Returns matching file paths sorted by modification time.
+ */
+
+import { Type } from "typebox";
+import { resolve } from "path";
+import { statSync } from "fs";
+import fg from "fast-glob";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { checkPermission } from "../agent/check-permissions.js";
+import { requestPermission } from "../agent/permission-ui.js";
+import type { ToolResultWithError } from "./types.js";
+
+export const globSchema = Type.Object({
+  pattern: Type.String({ description: "Glob pattern to match files, e.g. '**/*.ts' or 'src/**/*.tsx'" }),
+  path: Type.Optional(Type.String({ description: "Directory to search in (default: current directory)" })),
+});
+
+export type GlobToolInput = {
+  pattern: string;
+  path?: string;
+};
+
+const MAX_RESULTS = 100;
+
+export async function executeGlob(params: GlobToolInput): Promise<{ content: TextContent[]; details: { count: number; truncated: boolean } }> {
+  const cwd = params.path ? resolve(params.path) : process.cwd();
+  const entries = await fg(params.pattern, {
+    cwd,
+    dot: true,
+    absolute: false,
+    onlyFiles: true,
+  });
+
+  // Sort by modification time (most recent first)
+  const withMtime = entries.map((rel) => {
+    const full = resolve(cwd, rel);
+    try {
+      const mtime = statSync(full).mtimeMs;
+      return { rel, mtime };
+    } catch {
+      return { rel, mtime: 0 };
+    }
+  });
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+
+  const sorted = withMtime.map((e) => e.rel);
+  const truncated = sorted.length > MAX_RESULTS;
+  const output = sorted.slice(0, MAX_RESULTS);
+
+  let text = output.join("\n");
+  if (truncated) {
+    text += `\n\n... (${sorted.length - MAX_RESULTS} more files hidden, limit: ${MAX_RESULTS})`;
+  }
+
+  return {
+    content: [{ type: "text", text }],
+    details: { count: sorted.length, truncated },
+  };
+}
+
+export function createGlobToolDefinition(_cwd: string): ToolDefinition<typeof globSchema, { count: number; truncated: boolean }> {
+  return {
+    name: "glob",
+    label: "Glob",
+    description:
+      "Fast file pattern matching tool that works with any codebase size.\n\n" +
+      "- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n" +
+      "- Returns matching file paths sorted by modification time\n" +
+      "- Use this tool when you need to find files by name patterns",
+    promptSnippet: "Glob: find files by glob pattern (**/*.ts, etc.)",
+    parameters: globSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const perm = checkPermission("glob", params);
+      if (perm.decision === "deny") {
+        const result: ToolResultWithError<{ count: number; truncated: boolean }> = {
+          content: [{ type: "text", text: `Permission denied: ${perm.reason ?? "glob operation blocked"}` }],
+          details: { count: 0, truncated: false },
+          isError: true,
+        };
+        return result;
+      }
+      if (perm.decision === "ask") {
+        const allowed = await requestPermission({ toolName: "glob", args: params, reason: perm.reason ?? "Confirm file search" });
+        if (!allowed) {
+          const result: ToolResultWithError<{ count: number; truncated: boolean }> = {
+            content: [{ type: "text", text: "User denied permission to search files." }],
+            details: { count: 0, truncated: false },
+            isError: true,
+          };
+          return result;
+        }
+      }
+      return await executeGlob(params);
+    },
+  };
+}

package/src/tools/grep.ts

@@ -0,0 +1,248 @@
+/**
+ * GrepTool — ripgrep wrapper for content search
+ *
+ * Built on ripgrep with safe defaults:
+ *   --hidden, --glob !VCS, --max-columns 500, auto -e prefix for patterns starting with -
+ */
+
+import { Type } from "typebox";
+import { spawn } from "child_process";
+import { resolve } from "path";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { checkPermission } from "../agent/check-permissions.js";
+import { requestPermission } from "../agent/permission-ui.js";
+import type { ToolResultWithError } from "./types.js";
+
+export const grepSchema = Type.Object({
+  pattern: Type.String({ description: "Search pattern (regex or literal string)" }),
+  path: Type.Optional(Type.String({ description: "Directory or file to search (default: current directory)" })),
+  glob: Type.Optional(Type.String({ description: "Filter files by glob pattern, e.g. '*.ts' or '**/*.spec.ts'" })),
+  output_mode: Type.Optional(Type.Union(
+    [Type.Literal("content"), Type.Literal("files_with_matches"), Type.Literal("count")],
+    { description: 'Output mode: "content" | "files_with_matches" | "count" (default: content)' }
+  )),
+  context: Type.Optional(Type.Number({ description: "Number of lines to show before and after each match (default: 0)" })),
+  "-i": Type.Optional(Type.Boolean({ description: "Case-insensitive search (default: false)" })),
+  multiline: Type.Optional(Type.Boolean({ description: "Enable multiline matching (default: false)" })),
+  head_limit: Type.Optional(Type.Number({ description: "Maximum number of result lines to return (default: 250)" })),
+});
+
+export type GrepToolInput = {
+  pattern: string;
+  path?: string;
+  glob?: string;
+  output_mode?: "content" | "files_with_matches" | "count";
+  context?: number;
+  "-i"?: boolean;
+  multiline?: boolean;
+  head_limit?: number;
+};
+
+const VCS_DIRS = [".git", ".svn", ".hg", ".bzr", ".jj", ".sl"];
+const DEFAULT_HEAD_LIMIT = 250;
+
+/**
+ * Argument Builders
+ *
+ * buildRgArgs builds ripgrep flags; buildGrepArgs is the POSIX-grep fallback.
+ * addVcsExcludes, addModeFlags, addPattern are shared building blocks.
+ */
+
+function addVcsExcludes(args: string[], cmd: "rg" | "grep"): void {
+  if (cmd === "rg") {
+    for (const dir of VCS_DIRS) {
+      args.push("--glob", `!${dir}`);
+    }
+  } else {
+    for (const dir of VCS_DIRS) {
+      args.push("--exclude-dir", dir);
+    }
+  }
+}
+
+function addModeFlags(args: string[], mode: string, cmd: "rg" | "grep", context?: number): void {
+  if (mode === "files_with_matches") {
+    args.push("-l");
+  } else if (mode === "count") {
+    args.push("-c");
+  }
+
+  if (mode === "content") {
+    if (context !== undefined && context > 0) {
+      args.push("-C", String(context));
+    }
+    if (cmd === "rg") args.push("-n");
+  }
+}
+
+function addPattern(args: string[], pattern: string): void {
+  if (pattern.startsWith("-")) {
+    args.push("-e", pattern);
+  } else {
+    args.push(pattern);
+  }
+}
+
+function buildRgArgs(input: GrepToolInput): string[] {
+  const args: string[] = ["--hidden", "--max-columns", "500"];
+  addVcsExcludes(args, "rg");
+
+  if (input.multiline) args.push("-U", "--multiline-dotall");
+  if (input["-i"]) args.push("-i");
+
+  addModeFlags(args, input.output_mode ?? "content", "rg", input.context);
+
+  if (input.glob) args.push("--glob", input.glob);
+  addPattern(args, input.pattern);
+  args.push(input.path ? resolve(input.path) : process.cwd());
+
+  return args;
+}
+
+function buildGrepArgs(input: GrepToolInput): string[] {
+  const args: string[] = ["-r", "-n"];
+  addVcsExcludes(args, "grep");
+
+  if (input["-i"]) args.push("-i");
+  addModeFlags(args, input.output_mode ?? "content", "grep", input.context);
+
+  if (input.glob) args.push("--include", input.glob);
+  args.push("-e", input.pattern);
+  args.push(input.path ? resolve(input.path) : process.cwd());
+
+  return args;
+}
+
+/**
+ * Execution
+ *
+ * Tries ripgrep first; on ENOENT falls back to system grep.
+ * Exit code 1 from ripgrep means "no matches" — not an error.
+ */
+
+interface SearchResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+function execSearch(cmd: string, args: string[]): Promise<SearchResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (chunk: Buffer) => { stdout += chunk.toString("utf-8"); });
+    child.stderr?.on("data", (chunk: Buffer) => { stderr += chunk.toString("utf-8"); });
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 0 }));
+  });
+}
+
+function truncateOutput(stdout: string, stderr: string, limit: number): { text: string; truncated: boolean } {
+  const lines = stdout.split("\n");
+  const truncated = lines.length > limit;
+  let text = truncated ? lines.slice(0, limit).join("\n") : stdout;
+
+  if (truncated) {
+    text += `\n\n[Showing results with pagination = limit: ${limit}, offset: 0]`;
+  }
+  if (stderr) {
+    text += `\n\n(stderr: ${stderr.trim()})`;
+  }
+
+  return { text, truncated };
+}
+
+function countMatches(exitCode: number, outputMode: string | undefined, lines: string[]): number {
+  if (exitCode !== 0) return 0;
+  if (outputMode === "count") return lines.length - 1;
+  return lines.filter((l) => l.trim()).length;
+}
+
+export async function executeGrep(params: GrepToolInput): Promise<{
+  content: TextContent[];
+  details: { matches: number; truncated: boolean };
+}> {
+  let result: SearchResult;
+
+  try {
+    result = await execSearch("rg", buildRgArgs(params));
+  } catch (err: unknown) {
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      result = await execSearch("grep", buildGrepArgs(params));
+    } else {
+      throw err;
+    }
+  }
+
+  if (result.exitCode !== 0 && result.exitCode !== 1) {
+    throw new Error(result.stderr || `ripgrep exited with code ${result.exitCode}`);
+  }
+
+  const limit = params.head_limit ?? DEFAULT_HEAD_LIMIT;
+  const { text, truncated } = truncateOutput(result.stdout, result.stderr, limit);
+  const matchCount = countMatches(result.exitCode, params.output_mode, result.stdout.split("\n"));
+
+  return {
+    content: [{ type: "text", text }],
+    details: { matches: matchCount, truncated },
+  };
+}
+
+/** Factory helpers for permission-denied tool results. */
+
+function buildDeniedResult(): ToolResultWithError<{ matches: number; truncated: boolean }> {
+  return {
+    content: [{ type: "text", text: "Permission denied: grep operation blocked" }],
+    details: { matches: 0, truncated: false },
+    isError: true,
+  };
+}
+
+function buildUserDeniedResult(): ToolResultWithError<{ matches: number; truncated: boolean }> {
+  return {
+    content: [{ type: "text", text: "User denied permission to search." }],
+    details: { matches: 0, truncated: false },
+    isError: true,
+  };
+}
+
+/**
+ * ToolDefinition Factory
+ *
+ * Registers the grep tool with the Pi agent runtime.
+ */
+
+export function createGrepToolDefinition(_cwd: string): ToolDefinition<typeof grepSchema, { matches: number; truncated: boolean }> {
+  return {
+    name: "grep",
+    label: "Grep",
+    description:
+      "A powerful search tool built on ripgrep.\n\n" +
+      "Usage:\n" +
+      "- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command.\n" +
+      "- Supports full regex syntax (e.g. \"log.*Error\", \"function\\s+\\w+\")\n" +
+      "- Filter files with glob parameter (e.g. \"*.js\", \"**/*.tsx\")\n" +
+      "- Output modes: \"content\" shows matching lines, \"files_with_matches\" shows only file paths, \"count\" shows match counts\n" +
+      "- Pattern syntax: Uses ripgrep — literal braces need escaping (use `interface\\{}` to find `interface{}` in Go code)\n" +
+      "- Multiline matching: For cross-line patterns, use multiline: true",
+    promptSnippet: "Grep: search file contents with ripgrep (regex, glob filters, context lines)",
+    parameters: grepSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const perm = checkPermission("grep", params);
+      if (perm.decision === "deny") return buildDeniedResult();
+      if (perm.decision === "ask") {
+        const allowed = await requestPermission({
+          toolName: "grep",
+          args: params as GrepToolInput,
+          reason: perm.reason ?? "Confirm search",
+        });
+        if (!allowed) return buildUserDeniedResult();
+      }
+      return await executeGrep(params);
+    },
+  };
+}