@gotgenes/pi-colgrep 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [1.2.0](https://github.com/gotgenes/pi-packages/compare/pi-colgrep-v1.1.0...pi-colgrep-v1.2.0) (2026-05-23)
+
+
+### Features
+
+* add debounced reindex scheduling ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([f12bd7d](https://github.com/gotgenes/pi-packages/commit/f12bd7d2fb47b7dbe7edfbfa65705ebe727280cc))
+* add reindexer shutdown ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([55db463](https://github.com/gotgenes/pi-packages/commit/55db4631386856e1bc791f6c01b3f03251f05c23))
+* add reindexer with immediate execution ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([84356be](https://github.com/gotgenes/pi-packages/commit/84356befd9c146ca518919587a27361965671c5f))
+* clean up reindexer on session shutdown ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([9a87869](https://github.com/gotgenes/pi-packages/commit/9a878697f352bf111ca6c1dc86ce99d6c3916eef))
+* handle reindex errors gracefully ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([2ca14d5](https://github.com/gotgenes/pi-packages/commit/2ca14d544275cf16412435079206a0c9184bb266))
+* queue reindex behind in-flight run ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([bb9ccbe](https://github.com/gotgenes/pi-packages/commit/bb9ccbe1eb56df768e547649a069ac3231835bfe))
+* register /colgrep-reindex manual command ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([c591e80](https://github.com/gotgenes/pi-packages/commit/c591e8016ea9dac9db8d47e9fe51e01febc0c5b6))
+* reindex on session start ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([d18cb8a](https://github.com/gotgenes/pi-packages/commit/d18cb8a1de49c7d92535a1b14d8d02cd6a7f93eb))
+* schedule reindex on write/edit tool results ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([bb17ea0](https://github.com/gotgenes/pi-packages/commit/bb17ea0b6bb532f0d1a64e0e07a914f408482633))
+
+
+### Documentation
+
+* plan auto-reindex on session start and file mutations ([#91](https://github.com/gotgenes/pi-packages/issues/91)) ([291d55f](https://github.com/gotgenes/pi-packages/commit/291d55f2a03674c3d84ab2e59d053b72c1b2d9b6))
+
+## [1.1.0](https://github.com/gotgenes/pi-packages/compare/pi-colgrep-v1.0.0...pi-colgrep-v1.1.0) (2026-05-23)
+
+
+### Features
+
+* add colgrep availability check ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([4bf9893](https://github.com/gotgenes/pi-packages/commit/4bf989340bfae97c1aa3bca7bd246768222a4fad))
+* add colgrep CLI argument builder ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([80ba0db](https://github.com/gotgenes/pi-packages/commit/80ba0dba499b37116c98694ea0933b3a624cb85f))
+* add colgrep result formatting ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([efad4e7](https://github.com/gotgenes/pi-packages/commit/efad4e778c06afadfeba0bb0e965bde9b0db247a))
+* add colgrep search execution ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([d896766](https://github.com/gotgenes/pi-packages/commit/d8967660175c525e4234a2170d79fb853ecc6a1e))
+* add exec type and tool-result helpers ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([3142a2b](https://github.com/gotgenes/pi-packages/commit/3142a2b2d0aa5577d3883f5d58bc7674711fe324))
+* register colgrep search tool ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([0ad2bbd](https://github.com/gotgenes/pi-packages/commit/0ad2bbdc7a8926d461f5c8b37786e12940ae65f5))
+* wire colgrep tool and availability check into extension ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([738bbdb](https://github.com/gotgenes/pi-packages/commit/738bbdb3208f6bc37e802725cea2093ed94f8e9c))
+
+
+### Documentation
+
+* plan colgrep search tool registration ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([30a723d](https://github.com/gotgenes/pi-packages/commit/30a723df4b31d3ceb3b609fe89562d0ba4e43f05))
+
+
+### Miscellaneous Chores
+
+* add vitest test infrastructure for pi-colgrep ([#90](https://github.com/gotgenes/pi-packages/issues/90)) ([eba526d](https://github.com/gotgenes/pi-packages/commit/eba526d7dc0f962ad06b9d733613fd0a3568465d))
+
 ## 1.0.0 (2026-05-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-colgrep",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Pi extension that integrates ColGrep semantic code search as an agent tool.",
   "type": "module",
   "files": [
@@ -43,18 +43,24 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.75.0"
+    "@earendil-works/pi-coding-agent": ">=0.75.0",
+    "@earendil-works/pi-tui": ">=0.75.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
     "@earendil-works/pi-coding-agent": "0.75.4",
+    "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
     "rumdl": "^0.1.93",
-    "typescript": "^6.0.3"
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "check": "tsc --noEmit",
     "lint:md": "rumdl check *.md docs/**/*.md",
-    "lint": "biome check . && pnpm run lint:md"
+    "lint": "biome check . && pnpm run lint:md",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/extension.ts

@@ -1,5 +1,94 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createAvailabilityState } from "./lib/availability.js";
+import { createReindexer, type Reindexer } from "./lib/reindex.js";
+import { registerColGrep } from "./tools/colgrep.js";
 
-export default function piColGrepExtension(_pi: ExtensionAPI): void {
-  // Tool registration will be added in a future issue.
+const COLGREP_STATUS_KEY = "colgrep";
+
+function setColGrepStatus(
+  ctx: { ui: { setStatus?: (key: string, text: string | undefined) => void } },
+  text: string | undefined,
+): void {
+  if (typeof ctx.ui.setStatus === "function") {
+    ctx.ui.setStatus(COLGREP_STATUS_KEY, text);
+  }
+}
+
+export default function piColGrepExtension(pi: ExtensionAPI): void {
+  const availability = createAvailabilityState();
+  let reindexer: Reindexer | undefined;
+
+  registerColGrep(pi, {
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+    availability,
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    const exec = (
+      cmd: string,
+      args: string[],
+      opts?: { cwd?: string; timeout?: number; signal?: AbortSignal },
+    ) => pi.exec(cmd, args, opts);
+
+    await availability.refresh(exec);
+
+    if (!availability.available) {
+      ctx.ui.notify(
+        "colgrep is not installed. Semantic code search will not be available.\n" +
+          "Install from: https://github.com/lightonai/next-plaid#installation",
+        "warning",
+      );
+      return;
+    }
+
+    reindexer = createReindexer({
+      exec,
+      cwd: ctx.cwd,
+      onStatus: (text) => setColGrepStatus(ctx, text),
+    });
+    await reindexer.runNow();
+  });
+
+  pi.on("tool_result", async (event, _ctx) => {
+    if (event.isError) return;
+    if (event.toolName !== "write" && event.toolName !== "edit") return;
+    reindexer?.schedule();
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    await reindexer?.shutdown();
+    reindexer = undefined;
+  });
+
+  pi.registerCommand("colgrep-reindex", {
+    description: "Manually refresh the ColGrep semantic search index",
+    handler: async (_args, ctx) => {
+      if (!availability.available) {
+        ctx.ui.notify(
+          "colgrep is not installed. Install from: https://github.com/lightonai/next-plaid#installation",
+          "warning",
+        );
+        return;
+      }
+
+      const exec = (
+        cmd: string,
+        args: string[],
+        opts?: { cwd?: string; timeout?: number; signal?: AbortSignal },
+      ) => pi.exec(cmd, args, opts);
+
+      // Use the session reindexer if available; otherwise create a one-shot
+      // one (e.g., if the command is invoked before session_start has run).
+      const indexer =
+        reindexer ??
+        createReindexer({
+          exec,
+          cwd: ctx.cwd,
+          onStatus: (text) => setColGrepStatus(ctx, text),
+        });
+
+      await indexer.runNow();
+      ctx.ui.notify("ColGrep index updated.", "info");
+    },
+  });
 }

package/src/lib/args.ts

@@ -0,0 +1,41 @@
+export interface SearchParams {
+  query?: string;
+  regex?: string;
+  path?: string;
+  glob?: string;
+  limit?: number;
+  context?: number;
+}
+
+/**
+ * Build the CLI argument list for a colgrep search invocation.
+ *
+ * Always includes `--json`. Positional arguments (query, path) come last
+ * so flags are unambiguously parsed by the CLI.
+ */
+export function buildSearchArgs(params: SearchParams): string[] {
+  const args: string[] = ["--json"];
+
+  if (params.regex !== undefined) {
+    args.push("-e", params.regex);
+  }
+  if (params.glob !== undefined) {
+    args.push("--include", params.glob);
+  }
+  if (params.limit !== undefined) {
+    args.push("-k", String(params.limit));
+  }
+  if (params.context !== undefined) {
+    args.push("-n", String(params.context));
+  }
+
+  // Positional: query comes before path
+  if (params.query !== undefined) {
+    args.push(params.query);
+  }
+  if (params.path !== undefined) {
+    args.push(params.path);
+  }
+
+  return args;
+}

package/src/lib/availability.ts

@@ -0,0 +1,44 @@
+import type { Exec } from "./exec.js";
+
+export interface AvailabilityResult {
+  available: boolean;
+}
+
+/**
+ * Check whether the `colgrep` binary is present and responsive by running
+ * `colgrep --version`. Returns `{ available: false }` on any failure so the
+ * caller can degrade gracefully without catching.
+ */
+export async function checkAvailability(
+  exec: Exec,
+): Promise<AvailabilityResult> {
+  try {
+    const result = await exec("colgrep", ["--version"], { timeout: 5000 });
+    return { available: result.code === 0 };
+  } catch {
+    return { available: false };
+  }
+}
+
+export interface AvailabilityState {
+  /** `undefined` before the first `refresh()` call. */
+  available: boolean | undefined;
+  refresh(exec: Exec): Promise<void>;
+}
+
+/**
+ * Create a mutable availability state object that caches the result of the
+ * most recent `checkAvailability()` call.
+ *
+ * The `session_start` handler calls `refresh()` once per session and stores
+ * the result here. The tool's `execute()` reads `available` synchronously.
+ */
+export function createAvailabilityState(): AvailabilityState {
+  return {
+    available: undefined,
+    async refresh(exec: Exec): Promise<void> {
+      const result = await checkAvailability(exec);
+      this.available = result.available;
+    },
+  };
+}

package/src/lib/exec.ts

@@ -0,0 +1,9 @@
+/**
+ * Narrow exec interface matching `pi.exec()` — injected into library modules
+ * so they stay free of Pi SDK imports and remain directly testable.
+ */
+export type Exec = (
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number; signal?: AbortSignal },
+) => Promise<{ stdout: string; stderr: string; code: number }>;

package/src/lib/format.ts

@@ -0,0 +1,71 @@
+import { isAbsolute, relative } from "node:path";
+
+export interface ColGrepJsonHit {
+  unit: {
+    file: string;
+    line: number;
+    end_line: number;
+  };
+  score: number;
+}
+
+/**
+ * Format a single colgrep JSON hit into the concise text representation:
+ * `relative/path.ts:startLine-endLine [score=0.xxx]`
+ *
+ * Paths are made relative to `searchDir`. If the file is outside
+ * `searchDir`, the absolute path is used unchanged.
+ */
+export function formatHit(hit: ColGrepJsonHit, searchDir: string): string {
+  const rel = relative(searchDir, hit.unit.file);
+  // relative() produces a path starting with ".." when outside searchDir.
+  // In that case keep the absolute path for clarity.
+  const displayPath =
+    isAbsolute(rel) || rel.startsWith("..") ? hit.unit.file : rel;
+  const score = hit.score.toFixed(3);
+  return `${displayPath}:${hit.unit.line}-${hit.unit.end_line} [score=${score}]`;
+}
+
+/**
+ * Parse the colgrep `--json` stdout into agent-friendly text.
+ *
+ * Returns `"No matches found"` for an empty result set.
+ * Falls back to returning `rawOutput` unchanged when the output is not a
+ * valid JSON array — defensive against unexpected colgrep output.
+ * Skips individual hits that are missing required fields rather than
+ * throwing, so a single malformed entry doesn't suppress all results.
+ */
+export function formatResults(rawOutput: string, searchDir: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawOutput);
+  } catch {
+    return rawOutput;
+  }
+
+  if (!Array.isArray(parsed)) {
+    return rawOutput;
+  }
+
+  const lines: string[] = [];
+  for (const item of parsed) {
+    if (!isValidHit(item)) continue;
+    lines.push(formatHit(item, searchDir));
+  }
+
+  return lines.length === 0 ? "No matches found" : lines.join("\n");
+}
+
+function isValidHit(item: unknown): item is ColGrepJsonHit {
+  if (typeof item !== "object" || item === null) return false;
+  const obj = item as Record<string, unknown>;
+  if (typeof obj.score !== "number") return false;
+  const unit = obj.unit;
+  if (typeof unit !== "object" || unit === null) return false;
+  const u = unit as Record<string, unknown>;
+  return (
+    typeof u.file === "string" &&
+    typeof u.line === "number" &&
+    typeof u.end_line === "number"
+  );
+}

package/src/lib/reindex.ts

@@ -0,0 +1,111 @@
+import type { Exec } from "./exec.js";
+
+export type ReindexStatusCallback = (status: string | undefined) => void;
+
+export interface ReindexerDeps {
+  exec: Exec;
+  cwd: string;
+  onStatus: ReindexStatusCallback;
+  /** Debounce quiet period before a scheduled reindex fires. Defaults to 4000 ms. */
+  debounceMs?: number;
+  /** Exec timeout for the reindex command. Defaults to 300 000 ms (5 min). */
+  timeoutMs?: number;
+}
+
+export interface Reindexer {
+  /** Schedule a debounced reindex. Safe to call repeatedly. */
+  schedule(): void;
+  /** Run a reindex immediately, bypassing debounce. Resolves when complete. */
+  runNow(): Promise<void>;
+  /** Cancel pending timers and wait for any in-flight reindex to finish. */
+  shutdown(): Promise<void>;
+}
+
+const DEFAULT_DEBOUNCE_MS = 4_000;
+const DEFAULT_TIMEOUT_MS = 300_000;
+const INDEXING_STATUS = "colgrep: indexing\u2026";
+const QUEUED_STATUS = "colgrep: indexing\u2026 (queued updates)";
+const INDEXING_FAILED_STATUS = "colgrep: indexing failed";
+
+export function createReindexer(deps: ReindexerDeps): Reindexer {
+  const { exec, cwd, onStatus } = deps;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+  let inFlight = false;
+  let queued = false;
+  let isShutdown = false;
+  let inflightPromise: Promise<void> | undefined;
+
+  async function runReindex(): Promise<void> {
+    inFlight = true;
+    onStatus(INDEXING_STATUS);
+    let failed = false;
+    try {
+      const result = await exec("colgrep", ["init", "-y", "."], {
+        cwd,
+        timeout: timeoutMs,
+      });
+      if (result.code !== 0) {
+        failed = true;
+        const detail = result.stderr.trim();
+        console.error(
+          `colgrep reindex failed: ${detail || `exit code ${result.code}`}`,
+        );
+      }
+    } catch (err) {
+      failed = true;
+      console.error("colgrep reindex failed:", err);
+    }
+    if (failed) {
+      onStatus(INDEXING_FAILED_STATUS);
+    }
+    onStatus(undefined);
+    inFlight = false;
+    inflightPromise = undefined;
+
+    // Drain: if a reindex was queued while we were running, start it now
+    // (unless shut down in the meantime).
+    if (queued && !isShutdown) {
+      queued = false;
+      inflightPromise = runReindex();
+    }
+  }
+
+  return {
+    async runNow(): Promise<void> {
+      await runReindex();
+    },
+    schedule(): void {
+      if (isShutdown) return;
+
+      // While a reindex is in flight, mark a queued follow-up instead of
+      // starting another debounce timer.
+      if (inFlight) {
+        if (!queued) {
+          queued = true;
+          onStatus(QUEUED_STATUS);
+        }
+        return;
+      }
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer);
+      }
+      debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        inflightPromise = runReindex();
+      }, debounceMs);
+    },
+    async shutdown(): Promise<void> {
+      isShutdown = true;
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer);
+        debounceTimer = undefined;
+      }
+      if (inflightPromise !== undefined) {
+        await inflightPromise;
+      }
+    },
+  };
+}

package/src/lib/search.ts

@@ -0,0 +1,37 @@
+import { buildSearchArgs, type SearchParams } from "./args.js";
+import type { Exec } from "./exec.js";
+import { formatResults } from "./format.js";
+
+export interface SearchResult {
+  /** Formatted hit lines, present on success. */
+  output?: string;
+  /** Error message, present on failure. */
+  error?: string;
+}
+
+/**
+ * Run a colgrep search and return formatted results.
+ *
+ * Paths in the output are relativized against `params.path` when provided,
+ * otherwise against `cwd`.
+ */
+export async function runSearch(
+  exec: Exec,
+  params: SearchParams,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<SearchResult> {
+  const args = buildSearchArgs(params);
+  const result = await exec("colgrep", args, { cwd, signal });
+
+  if (result.code !== 0) {
+    const detail = result.stderr.trim();
+    const message = detail
+      ? detail
+      : `colgrep exited with exit code ${result.code}`;
+    return { error: message };
+  }
+
+  const searchDir = params.path ?? cwd;
+  return { output: formatResults(result.stdout, searchDir) };
+}

package/src/tool-result.ts

@@ -0,0 +1,31 @@
+/**
+ * Helpers to create AgentToolResult-compatible objects.
+ *
+ * Pi's AgentToolResult expects `content` as an array of TextContent objects
+ * and a `details` field. These helpers wrap a plain string into that shape.
+ */
+
+interface ToolResult<TDetails = undefined> {
+  content: { type: "text"; text: string }[];
+  details: TDetails;
+  isError: boolean;
+}
+
+export function ok<TDetails = undefined>(
+  text: string,
+  details?: TDetails,
+): ToolResult<TDetails> {
+  return {
+    content: [{ type: "text", text }],
+    details: details as TDetails,
+    isError: false,
+  };
+}
+
+export function err(text: string): ToolResult<undefined> {
+  return {
+    content: [{ type: "text", text }],
+    details: undefined,
+    isError: true,
+  };
+}

package/src/tools/colgrep.ts

@@ -0,0 +1,211 @@
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { SearchParams } from "../lib/args.js";
+import type { AvailabilityState } from "../lib/availability.js";
+import type { Exec } from "../lib/exec.js";
+import { runSearch } from "../lib/search.js";
+import { err, ok } from "../tool-result.js";
+
+export interface ColGrepToolDetails {
+  hitCount: number;
+  truncated: boolean;
+  fullOutputPath?: string;
+}
+
+export interface ColGrepExecuteDeps {
+  exec: Exec;
+  availability: AvailabilityState;
+  /** Override default truncation line limit. Used in tests. */
+  maxLines?: number;
+  /** Override default truncation byte limit. Used in tests. */
+  maxBytes?: number;
+}
+
+/**
+ * Core execute logic, extracted for testability.
+ * Called by the tool's `execute()` callback with `ctx.cwd` as cwd.
+ */
+export async function executeColGrepSearch(
+  params: SearchParams,
+  deps: ColGrepExecuteDeps,
+  cwd: string,
+  signal: AbortSignal | undefined,
+) {
+  if (!deps.availability.available) {
+    return err(
+      "colgrep is not installed or not available.\n" +
+        "Install it from: https://github.com/lightonai/next-plaid#installation",
+    );
+  }
+
+  if (!params.query && !params.regex) {
+    return err("At least one of query or regex is required.");
+  }
+
+  const searchResult = await runSearch(deps.exec, params, cwd, signal);
+  if (searchResult.error) {
+    return err(searchResult.error);
+  }
+
+  const output = searchResult.output ?? "No matches found";
+  const maxLines = deps.maxLines ?? DEFAULT_MAX_LINES;
+  const maxBytes = deps.maxBytes ?? DEFAULT_MAX_BYTES;
+  const truncation = truncateHead(output, { maxLines, maxBytes });
+
+  if (truncation.truncated) {
+    const tempPath = join(tmpdir(), `colgrep-${Date.now()}.txt`);
+    await writeFile(tempPath, output);
+    const hitCount = countHits(output);
+    return ok(`${truncation.content}\n[Truncated. Full output: ${tempPath}]`, {
+      hitCount,
+      truncated: true,
+      fullOutputPath: tempPath,
+    } satisfies ColGrepToolDetails);
+  }
+
+  const hitCount = countHits(output);
+  return ok(output, {
+    hitCount,
+    truncated: false,
+  } satisfies ColGrepToolDetails);
+}
+
+export interface RegisterColGrepDeps {
+  exec: Exec;
+  availability: AvailabilityState;
+}
+
+export function registerColGrep(
+  pi: ExtensionAPI,
+  deps: RegisterColGrepDeps,
+): void {
+  pi.registerTool({
+    name: "colgrep",
+    label: "ColGrep",
+    description:
+      "Search for code by meaning using semantic / hybrid search (ColBERT embeddings + tree-sitter). " +
+      "Complements the built-in grep: use colgrep for intent-based exploration, grep for exact pattern matching. " +
+      "At least one of query or regex is required.",
+    promptSnippet:
+      "colgrep: Semantic and hybrid code search — find code by intent, not just text.",
+    promptGuidelines: [
+      "Prefer colgrep for intent-based searches and exploration (e.g. 'error handling for database connections').",
+      "Use grep for exact pattern or symbol matching; use colgrep when keywords may not match exactly.",
+      "Increase limit (default 15) when exploring a large codebase — try limit=30 for broader coverage.",
+    ],
+    parameters: Type.Object({
+      query: Type.Optional(
+        Type.String({
+          description: "Semantic search query (natural language intent)",
+        }),
+      ),
+      regex: Type.Optional(
+        Type.String({
+          description:
+            "Regex pre-filter applied before semantic ranking (-e flag)",
+        }),
+      ),
+      path: Type.Optional(
+        Type.String({
+          description: "Directory or file to search (defaults to cwd)",
+        }),
+      ),
+      glob: Type.Optional(
+        Type.String({ description: "Include glob pattern (--include flag)" }),
+      ),
+      limit: Type.Optional(
+        Type.Number({ description: "Max results (-k flag, default: 15)" }),
+      ),
+      context: Type.Optional(
+        Type.Number({ description: "Context lines (-n flag)" }),
+      ),
+    }),
+    renderCall(args, theme, context) {
+      const text =
+        (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      text.setText(formatCall(args, theme));
+      return text;
+    },
+    renderResult(result, options, theme, context) {
+      const text =
+        (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      text.setText(formatResult(result, options, theme));
+      return text;
+    },
+    async execute(
+      _toolCallId,
+      params,
+      signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      return executeColGrepSearch(params, deps, ctx.cwd, signal);
+    },
+  });
+}
+
+// ---- rendering helpers ----
+
+function formatCall(args: Record<string, unknown>, theme: Theme): string {
+  const query = typeof args.query === "string" ? args.query : undefined;
+  const regex = typeof args.regex === "string" ? args.regex : undefined;
+  const path = typeof args.path === "string" ? args.path : ".";
+  const limit = typeof args.limit === "number" ? args.limit : 15;
+
+  const parts: string[] = [theme.fg("toolTitle", theme.bold("colgrep"))];
+  if (query) parts.push(theme.fg("accent", `"${query}"`));
+  if (regex) parts.push(theme.fg("accent", `-e /${regex}/`));
+  parts.push(theme.fg("toolOutput", `in ${path} (k=${limit})`));
+  return parts.join(" ");
+}
+
+interface AnyToolResult {
+  content: Array<{ type: string; text?: string }>;
+  details?: ColGrepToolDetails;
+}
+
+function formatResult(
+  result: unknown,
+  options: { expanded: boolean },
+  theme: Theme,
+): string {
+  const r = result as AnyToolResult;
+  const details = r.details;
+  const hitCount = details?.hitCount ?? 0;
+  const outputText =
+    r.content[0]?.type === "text" ? (r.content[0].text ?? "") : "";
+
+  if (!options.expanded) {
+    const icon = theme.fg("success", "✓");
+    const count =
+      hitCount === 0
+        ? theme.fg("muted", "no matches")
+        : theme.fg("muted", `${hitCount} hit${hitCount === 1 ? "" : "s"}`);
+    return `${icon} ${count}`;
+  }
+
+  const lines = outputText
+    .split("\n")
+    .map((l: string) => theme.fg("toolOutput", `  ${l}`));
+  return lines.join("\n");
+}
+
+// ---- private helpers ----
+
+function countHits(output: string): number {
+  if (output === "No matches found") return 0;
+  return output.split("\n").length;
+}