@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/tools/bash.mjs

@@ -0,0 +1,216 @@
+/**
+ * lib/engine/tools/bash.mjs — the Bash tool.
+ *
+ * Input contract: `{ command, timeout?, description? }` (timeout in ms).
+ * Runs `bash -c <command>` in the run's working directory, non-interactively
+ * (stdin closed), in its own process group so a timeout or abort kills the
+ * whole tree, not just the shell.
+ *
+ * The child environment is SCRUBBED (`scrubToolEnv`) of anything shaped like a
+ * model or platform credential: every `*_API_KEY`, `*_AUTH_TOKEN`,
+ * `*_OAUTH_TOKEN`, and the COHORT_/NEOLITH_/MAESTRO_ tokens, including the
+ * engine's own gateway token. A command the model writes must never be able to
+ * read the seat token that pays for the model, or an org-leased provider key.
+ * Since W5-B (CF-22) the common secret shapes are removed too
+ * (`EXTENDED_SECRET_ENV`: GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, `*_SECRET`,
+ * `*_PASSWORD`, `*_PRIVATE_KEY`, …), unless the run's `envPassthrough` names
+ * them (`ctx.envPassthrough`). Since CF-118 a variable whose VALUE looks like a
+ * credential is removed too, whatever its name (`DATABASE_URL` with a password,
+ * a vendor token, a JWT, a long random or hex run: context/secret-values.mjs),
+ * under the same passthrough.
+ *
+ * Deferred to W2 (documented in docs/engine/README.md): background execution,
+ * a persistent working directory across calls, and permission rules. Until the
+ * permission engine lands, the caller decides whether Bash is exposed at all
+ * (`cohort run --tools`).
+ *
+ * @module lib/engine/tools/bash
+ */
+
+import { spawn } from "node:child_process";
+import { createProcessTracker, newProcessTag, PROCESS_TAG_ENV } from "../process-tree.mjs";
+import { credentialValueKind } from "../context/secret-values.mjs";
+
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const MAX_TIMEOUT_MS = 600_000;
+export const MAX_OUTPUT_CHARS = 30_000;
+
+/**
+ * Credential SHAPES, not a list of names. Org provider keys are leased into the
+ * spawn env at startup and never written to disk, so this scrub is the only
+ * thing between a model-written command and them; an allow-list of names goes
+ * stale the day the model-router catalogue gains a provider (it already had:
+ * DEEPSEEK_, MOONSHOT_, DASHSCOPE_ were missed). `tools.test.mjs` pins every
+ * `auth_env` in `lib/model-router/catalog/*.yaml` against these patterns.
+ */
+export const SECRET_ENV = Object.freeze([
+  /(^|_)API_KEY$/i, //                every provider key, incl. *_ADMIN_API_KEY
+  /(^|_)AUTH_TOKEN$/i, //             ANTHROPIC_AUTH_TOKEN and kin
+  /(^|_)OAUTH_TOKEN$/i, //            CLAUDE_CODE_OAUTH_TOKEN
+  /^(COHORT|NEOLITH|MAESTRO)_([A-Z0-9]+_)*TOKEN$/i, // COHORT_TOKEN, COHORT_API_TOKEN, COHORT_LLM_TOKEN, NEOLITH_*, MAESTRO_AGENT_TOKEN
+  /^DEEPINFRA_TOKEN$/i,
+  /^(COHORT|NEOLITH)_LLM_TOKEN_HELPER$/i, // the command that mints the engine's own gateway token
+]);
+
+/**
+ * CF-22 (W5-B): common secret shapes beyond model and platform credentials —
+ * code-host and cloud tokens, `*_SECRET`, `*_PASSWORD`, `*_PRIVATE_KEY` and
+ * named bearer tokens. Scrubbed from the Bash tool, hook commands and MCP
+ * children like {@link SECRET_ENV}, except that an explicit passthrough list
+ * (settings `cohort.envPassthrough`, COHORT_ENGINE_ENV_PASSTHROUGH) may name
+ * one of THESE to let it through. A name that also matches SECRET_ENV is never
+ * passed by that list.
+ */
+export const EXTENDED_SECRET_ENV = Object.freeze([
+  /^(GITHUB|GH|GITLAB|NPM|HF|HUGGING_FACE_HUB|CIRCLE|VERCEL|NETLIFY|RAILWAY)_TOKEN$/i,
+  /^AWS_(SECRET_ACCESS_KEY|SESSION_TOKEN)$/i,
+  /(^|_)SECRET$/i, //                 CLIENT_SECRET, SLACK_SIGNING_SECRET, RELAY_SHARED_SECRET
+  /(^|_)SECRET_(ACCESS_)?KEY$/i,
+  /(^|_)(PASSWORD|PASSWD|PASSPHRASE)$/i,
+  /(^|_)PRIVATE_KEY$/i,
+  /(^|_)(ACCESS|REFRESH|SESSION|BOT|USER|APP|PERSONAL_ACCESS)_TOKEN$/i,
+]);
+
+/** @param {string} name */
+export function isExtendedSecretName(name) {
+  return EXTENDED_SECRET_ENV.some((re) => re.test(name));
+}
+
+/**
+ * The environment of a model-written command: no credential of either list,
+ * and no variable whose VALUE looks like a credential (CF-118,
+ * context/secret-values.mjs: a URL with a password, a vendor token, a JWT, a
+ * private key, a long random or hex run); `passthrough` names extended-shape or
+ * value-shaped variables to keep. A SECRET_ENV name is never kept.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {{passthrough?:Iterable<string>}} [o]
+ * @returns {Record<string,string>}
+ */
+export function scrubToolEnv(env, { passthrough = [] } = {}) {
+  const pass = new Set(passthrough);
+  const out = {};
+  for (const [k, v] of Object.entries(env || {})) {
+    if (v === undefined) continue;
+    if (SECRET_ENV.some((re) => re.test(k))) continue;
+    if (!pass.has(k) && (isExtendedSecretName(k) || credentialValueKind(v, { name: k }) !== null)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Keep the head and tail of oversized output (errors usually live at the end).
+ * @param {string} s @param {number} [max]
+ */
+export function truncateOutput(s, max = MAX_OUTPUT_CHARS) {
+  if (s.length <= max) return s;
+  const half = Math.floor(max / 2);
+  return `${s.slice(0, half)}\n\n… [${s.length - max} characters omitted] …\n\n${s.slice(-half)}`;
+}
+
+export const bashTool = {
+  name: "Bash",
+  readOnly: false,
+  description:
+    "Run a shell command with bash in the working directory and return its combined stdout and stderr. " +
+    "Commands run non-interactively with no stdin. " +
+    `\`timeout\` is in milliseconds (default ${DEFAULT_TIMEOUT_MS}, maximum ${MAX_TIMEOUT_MS}). ` +
+    "Give a short `description` of what the command does. Prefer Read, Glob, Grep and Edit over shell equivalents.",
+  input_schema: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The command to run." },
+      timeout: { type: "integer", minimum: 1, maximum: MAX_TIMEOUT_MS, description: "Timeout in milliseconds." },
+      description: { type: "string", description: "What the command does, in a few words." },
+    },
+    required: ["command"],
+  },
+
+  /**
+   * @param {{command:string, timeout?:number}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  run(input, ctx) {
+    const timeoutMs = Math.min(input.timeout ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    return new Promise((resolve) => {
+      if (ctx.signal?.aborted) return resolve({ ok: false, error: "Aborted before the command started." });
+      // CF-48: a timeout or abort also stops what the command started outside its group (setsid).
+      const tag = newProcessTag();
+      const rootId = `bash_fg_${tag}`;
+      // CF-119: sampled like a background shell (tree and tag, 100 ms, 500 ms, every 2 s, read without
+      // holding the event loop; a call that ends sooner costs nothing), and captured again at the kill.
+      const tracker = createProcessTracker();
+      let child;
+      try {
+        child = spawn("/bin/bash", ["-c", input.command], {
+          cwd: ctx.cwd,
+          env: { ...scrubToolEnv(ctx.env, { passthrough: ctx.envPassthrough ?? [] }), [PROCESS_TAG_ENV]: tag },
+          stdio: ["ignore", "pipe", "pipe"],
+          detached: true,
+        });
+      } catch (e) {
+        return resolve({ ok: false, error: `Could not start bash: ${e instanceof Error ? e.message : e}` });
+      }
+      if (child.pid) tracker.track({ id: rootId, pid: child.pid, tag });
+      let output = "";
+      let over = false;
+      const onData = (d) => {
+        if (output.length > MAX_OUTPUT_CHARS * 4) {
+          over = true;
+          return;
+        }
+        output += d.toString("utf8");
+      };
+      child.stdout.on("data", onData);
+      child.stderr.on("data", onData);
+
+      let reason = null;
+      const killTree = (why) => {
+        if (reason) return;
+        reason = why;
+        try {
+          tracker.capture([rootId], { tags: true });
+          tracker.signal([rootId], "SIGTERM");
+        } catch {
+          /* the group signal still goes out */
+        }
+        try {
+          process.kill(-child.pid, "SIGTERM");
+        } catch {
+          /* the group already exited */
+        }
+        setTimeout(() => {
+          try {
+            process.kill(-child.pid, "SIGKILL");
+          } catch {
+            /* exited on SIGTERM, as hoped */
+          }
+          tracker.signal([rootId], "SIGKILL");
+          tracker.dispose();
+        }, 2000).unref();
+      };
+      const timer = setTimeout(() => killTree("timeout"), timeoutMs);
+      const onAbort = () => killTree("aborted");
+      ctx.signal?.addEventListener("abort", onAbort, { once: true });
+
+      const finish = (code, signal) => {
+        clearTimeout(timer);
+        ctx.signal?.removeEventListener("abort", onAbort);
+        tracker.rootExited(rootId);
+        if (!reason) tracker.dispose(); // a kill disposes after its SIGKILL pass
+        const body = truncateOutput(output) + (over ? "\n… [output limit reached; later output dropped]" : "");
+        if (reason === "timeout") return resolve({ ok: false, error: `${body}\nCommand timed out after ${timeoutMs} ms.`.trim() });
+        if (reason === "aborted") return resolve({ ok: false, error: `${body}\nCommand aborted.`.trim() });
+        if (code === 0) return resolve({ ok: true, content: body === "" ? "(no output)" : body });
+        const status = code === null ? `killed by ${signal}` : `exit code ${code}`;
+        resolve({ ok: false, error: `${body}\nCommand failed: ${status}.`.trim() });
+      };
+      child.on("error", (e) => {
+        clearTimeout(timer);
+        tracker.dispose();
+        resolve({ ok: false, error: `bash error: ${e.message}` });
+      });
+      child.on("close", finish);
+    });
+  },
+};

package/lib/engine/tools/edit.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/engine/tools/edit.mjs — the Edit tool.
+ *
+ * Input contract: `{ file_path, old_string, new_string, replace_all? }`.
+ * Exact string replacement. `old_string` must occur exactly once unless
+ * `replace_all` is set — an ambiguous edit is refused with the occurrence
+ * count, so the model widens the context instead of editing the wrong site.
+ * An empty `old_string` on a file that does not exist creates it.
+ *
+ * The replacement is a pure function (`applyEdit`); the tool is its edge.
+ *
+ * @module lib/engine/tools/edit
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "../../fs-atomic.mjs";
+import { checkFresh } from "./write.mjs";
+
+/**
+ * @param {string} text
+ * @param {string} oldString
+ * @param {string} newString
+ * @param {boolean} replaceAll
+ * @returns {{ ok:true, text:string, count:number } | { ok:false, error:string }}
+ */
+export function applyEdit(text, oldString, newString, replaceAll) {
+  if (oldString === newString) return { ok: false, error: "old_string and new_string are identical; nothing to change." };
+  if (oldString === "") return { ok: false, error: "old_string is empty; give the exact text to replace." };
+  const parts = text.split(oldString);
+  const count = parts.length - 1;
+  if (count === 0) return { ok: false, error: "old_string was not found in the file. Read the file and copy the text exactly." };
+  if (count > 1 && !replaceAll) {
+    return {
+      ok: false,
+      error: `old_string occurs ${count} times. Include more surrounding text to make it unique, or set replace_all.`,
+    };
+  }
+  // split/join, not String.replace: a `$&` in new_string must stay literal.
+  return { ok: true, text: parts.join(newString), count };
+}
+
+export const editTool = {
+  name: "Edit",
+  readOnly: false,
+  description:
+    "Replace an exact string in a file. `file_path` must be absolute and the file must have been Read first. " +
+    "`old_string` must match the file exactly (including whitespace) and occur once, unless `replace_all` is true. " +
+    "With an empty `old_string`, creates a new file containing `new_string`.",
+  input_schema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "Absolute path of the file to change." },
+      old_string: { type: "string", description: "The exact text to replace." },
+      new_string: { type: "string", description: "The replacement text." },
+      replace_all: { type: "boolean", description: "Replace every occurrence instead of exactly one." },
+    },
+    required: ["file_path", "old_string", "new_string"],
+  },
+
+  /**
+   * @param {{file_path:string, old_string:string, new_string:string, replace_all?:boolean}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const file = input.file_path;
+    if (!path.isAbsolute(file)) return { ok: false, error: `file_path must be absolute, got "${file}"` };
+    let st = null;
+    try {
+      st = statSync(file);
+    } catch {
+      st = null; // absent: only the create form (empty old_string) is valid
+    }
+    if (!st) {
+      if (input.old_string !== "") return { ok: false, error: `File does not exist: ${file}` };
+      try {
+        writeFileAtomic(file, input.new_string);
+      } catch (e) {
+        return { ok: false, error: `Could not create ${file}: ${e instanceof Error ? e.message : e}` };
+      }
+      ctx.fileState.set(file, { mtimeMs: statSync(file).mtimeMs });
+      return { ok: true, content: `Created ${file}.` };
+    }
+    if (st.isDirectory()) return { ok: false, error: `${file} is a directory.` };
+    const fresh = checkFresh(file, st, ctx.fileState);
+    if (!fresh.ok) return fresh;
+    const r = applyEdit(readFileSync(file, "utf8"), input.old_string, input.new_string, Boolean(input.replace_all));
+    if (!r.ok) return r;
+    try {
+      writeFileAtomic(file, r.text, { mode: st.mode & 0o7777 });
+    } catch (e) {
+      return { ok: false, error: `Could not write ${file}: ${e instanceof Error ? e.message : e}` };
+    }
+    ctx.fileState.set(file, { mtimeMs: statSync(file).mtimeMs });
+    return { ok: true, content: `Edited ${file} (${r.count} replacement${r.count === 1 ? "" : "s"}).` };
+  },
+};

package/lib/engine/tools/glob.mjs

@@ -0,0 +1,81 @@
+/**
+ * lib/engine/tools/glob.mjs — the Glob tool.
+ *
+ * Input contract: `{ pattern, path? }`. Returns matching file paths (absolute),
+ * newest first, capped. Candidate files come from ripgrep when available
+ * (honours .gitignore) or the pure-JS walk; matching is always `matchGlob`, so
+ * both paths agree on semantics.
+ *
+ * @module lib/engine/tools/glob
+ */
+
+import { statSync } from "node:fs";
+import path from "node:path";
+import { hasRipgrep, runRipgrep, walkFiles, matchGlob, sortByMtime, toPosix, RG_EXCLUDES } from "./walk.mjs";
+
+export const MAX_GLOB_RESULTS = 100;
+
+/**
+ * Resolve the search root for Glob/Grep: absolute, or relative to cwd.
+ * @param {string|undefined} p @param {string} cwd
+ */
+export function resolveRoot(p, cwd) {
+  if (!p) return cwd;
+  return path.isAbsolute(p) ? p : path.resolve(cwd, p);
+}
+
+/**
+ * List candidate files under root (absolute paths).
+ * @param {string} root
+ * @param {import('./index.mjs').ToolContext} ctx
+ * @returns {Promise<{ok:true, files:string[]} | {ok:false, error:string}>}
+ */
+export async function listFiles(root, ctx) {
+  if (ctx.useRipgrep ?? hasRipgrep(ctx.env)) {
+    const r = await runRipgrep(["--files", "--no-config", "--no-messages", ...RG_EXCLUDES, "--", root], { cwd: ctx.cwd, signal: ctx.signal });
+    if (r.ok) return { ok: true, files: r.stdout.split("\n").filter(Boolean) };
+    // ripgrep present but failing: the walk still answers.
+  }
+  return { ok: true, files: walkFiles(root, { signal: ctx.signal }) };
+}
+
+export const globTool = {
+  name: "Glob",
+  readOnly: true,
+  description:
+    "Find files by name pattern, such as `**/*.mjs` or `src/**/*.{ts,tsx}`. Returns absolute paths, most recently modified first. " +
+    "A pattern without a slash matches file names at any depth. `path` is the directory to search (default: the working directory). " +
+    "Use Grep to search file contents.",
+  input_schema: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Glob pattern to match file paths against." },
+      path: { type: "string", description: "Directory to search in. Defaults to the working directory." },
+    },
+    required: ["pattern"],
+  },
+
+  /**
+   * @param {{pattern:string, path?:string}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const root = resolveRoot(input.path, ctx.cwd);
+    try {
+      if (!statSync(root).isDirectory()) return { ok: false, error: `${root} is not a directory.` };
+    } catch {
+      return { ok: false, error: `Directory does not exist: ${root}` };
+    }
+    const listed = await listFiles(root, ctx);
+    if (!listed.ok) return listed;
+    const matches = listed.files.filter((f) => matchGlob(toPosix(path.relative(root, f)), input.pattern));
+    if (matches.length === 0) return { ok: true, content: "No files found." };
+    const sorted = sortByMtime(matches);
+    const shown = sorted.slice(0, MAX_GLOB_RESULTS);
+    const more = sorted.length - shown.length;
+    return {
+      ok: true,
+      content: shown.join("\n") + (more > 0 ? `\n(${more} more results not shown; narrow the pattern or path)` : ""),
+    };
+  },
+};

package/lib/engine/tools/grep.mjs

@@ -0,0 +1,224 @@
+/**
+ * lib/engine/tools/grep.mjs — the Grep tool.
+ *
+ * Input contract: `{ pattern, path?, glob?, type?, output_mode?, "-i"?, "-n"?,
+ * "-A"?, "-B"?, "-C"?, multiline?, head_limit? }`. `output_mode` is
+ * `files_with_matches` (default: paths, newest first), `content` (matching
+ * lines, `path:line:text`) or `count` (`path:count`).
+ *
+ * Ripgrep when available; otherwise a pure-JS search with JavaScript regex
+ * syntax (close to, not identical to, ripgrep's). `glob` is always decided by
+ * `matchGlob` in both modes: ripgrep's own `--glob` anchors slash patterns
+ * differently (`/src/*.mjs` matches for rg, not for us), so in ripgrep mode
+ * the candidates come from `rg --files` and are filtered here before the
+ * search. `type` uses ripgrep's type table in ripgrep mode and
+ * `TYPE_EXTENSIONS` in the fallback.
+ *
+ * @module lib/engine/tools/grep
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { hasRipgrep, runRipgrep, walkFiles, matchGlob, sortByMtime, toPosix, RG_EXCLUDES } from "./walk.mjs";
+import { resolveRoot } from "./glob.mjs";
+
+export const DEFAULT_HEAD_LIMIT = 250;
+const MAX_SEARCH_BYTES = 2 * 1024 * 1024;
+/** Explicit file arguments per ripgrep invocation, well under ARG_MAX. */
+const RG_FILES_PER_CALL = 500;
+
+/** A small file-type table for the fallback; ripgrep uses its own. */
+export const TYPE_EXTENSIONS = {
+  js: [".js", ".mjs", ".cjs", ".jsx"],
+  ts: [".ts", ".tsx", ".mts", ".cts"],
+  py: [".py"],
+  go: [".go"],
+  rust: [".rs"],
+  java: [".java"],
+  md: [".md", ".markdown"],
+  json: [".json"],
+  yaml: [".yaml", ".yml"],
+  css: [".css", ".scss"],
+  html: [".html", ".htm"],
+  sh: [".sh", ".bash", ".zsh"],
+  sql: [".sql"],
+};
+
+/**
+ * Pure: search one file's text and render in the requested mode.
+ * @param {string} file display path
+ * @param {string} text
+ * @param {RegExp} re   must carry the `g` flag
+ * @param {{ mode: 'content'|'count'|'files_with_matches', lineNumbers: boolean, before: number, after: number, multiline: boolean }} o
+ * @returns {string[]} output lines (empty when no match)
+ */
+export function searchText(file, text, re, o) {
+  if (o.multiline) {
+    re.lastIndex = 0;
+    const hits = [...text.matchAll(re)];
+    if (hits.length === 0) return [];
+    if (o.mode === "files_with_matches") return [file];
+    if (o.mode === "count") return [`${file}:${hits.length}`];
+    return hits.map((m) => {
+      const line = text.slice(0, m.index).split("\n").length;
+      return o.lineNumbers ? `${file}:${line}:${m[0]}` : `${file}:${m[0]}`;
+    });
+  }
+  const lines = text.split(/\r?\n/);
+  const matched = [];
+  const single = new RegExp(re.source, re.flags.replace("g", ""));
+  lines.forEach((l, i) => {
+    if (single.test(l)) matched.push(i);
+  });
+  if (matched.length === 0) return [];
+  if (o.mode === "files_with_matches") return [file];
+  if (o.mode === "count") return [`${file}:${matched.length}`];
+  const include = new Set();
+  for (const i of matched) for (let j = Math.max(0, i - o.before); j <= Math.min(lines.length - 1, i + o.after); j++) include.add(j);
+  const hit = new Set(matched);
+  const out = [];
+  let prev = -2;
+  for (const j of [...include].sort((a, b) => a - b)) {
+    if (prev >= 0 && j > prev + 1) out.push("--");
+    const sep = hit.has(j) ? ":" : "-";
+    out.push(o.lineNumbers ? `${file}${sep}${j + 1}${sep}${lines[j]}` : `${file}${sep}${lines[j]}`);
+    prev = j;
+  }
+  return out;
+}
+
+export const grepTool = {
+  name: "Grep",
+  readOnly: true,
+  description:
+    "Search file contents with a regular expression. `output_mode` is `files_with_matches` (default; file paths, newest first), " +
+    "`content` (matching lines as path:line:text) or `count` (matches per file). " +
+    "Narrow the search with `path`, `glob` (e.g. `*.mjs`) or `type` (e.g. `js`, `py`). " +
+    "`-i` ignores case; `-A`/`-B`/`-C` add context lines in content mode; `multiline` lets a pattern span lines; " +
+    `\`head_limit\` caps output lines (default ${DEFAULT_HEAD_LIMIT}).`,
+  input_schema: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Regular expression to search for." },
+      path: { type: "string", description: "File or directory to search. Defaults to the working directory." },
+      glob: { type: "string", description: "Only search files whose names match this glob." },
+      type: { type: "string", description: "Only search files of this type (js, ts, py, go, rust, md, json, …)." },
+      output_mode: { type: "string", enum: ["content", "files_with_matches", "count"], description: "What to return." },
+      "-i": { type: "boolean", description: "Case-insensitive search." },
+      "-n": { type: "boolean", description: "Show line numbers in content mode (default true)." },
+      "-A": { type: "integer", minimum: 0, description: "Lines of context after each match (content mode)." },
+      "-B": { type: "integer", minimum: 0, description: "Lines of context before each match (content mode)." },
+      "-C": { type: "integer", minimum: 0, description: "Lines of context around each match (content mode)." },
+      multiline: { type: "boolean", description: "Allow the pattern to match across lines." },
+      head_limit: { type: "integer", minimum: 1, description: "Maximum number of output lines." },
+    },
+    required: ["pattern"],
+  },
+
+  /**
+   * @param {any} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const root = resolveRoot(input.path, ctx.cwd);
+    let rootStat;
+    try {
+      rootStat = statSync(root);
+    } catch {
+      return { ok: false, error: `Path does not exist: ${root}` };
+    }
+    const mode = input.output_mode || "files_with_matches";
+    const o = {
+      mode,
+      lineNumbers: input["-n"] ?? true,
+      before: input["-B"] ?? input["-C"] ?? 0,
+      after: input["-A"] ?? input["-C"] ?? 0,
+      multiline: Boolean(input.multiline),
+    };
+    const headLimit = input.head_limit ?? DEFAULT_HEAD_LIMIT;
+    if (input.type && !TYPE_EXTENSIONS[input.type] && !(ctx.useRipgrep ?? hasRipgrep(ctx.env))) {
+      return { ok: false, error: `Unknown type "${input.type}". Known: ${Object.keys(TYPE_EXTENSIONS).join(", ")}.` };
+    }
+
+    /** Path a glob is matched against: relative to a directory root, else the basename. */
+    const globPath = (f) => toPosix(rootStat.isDirectory() ? path.relative(root, f) : path.basename(f));
+
+    let lines;
+    if (ctx.useRipgrep ?? hasRipgrep(ctx.env)) {
+      const args = ["--no-config", "--no-messages", "--color", "never", ...RG_EXCLUDES];
+      if (mode === "files_with_matches") args.push("-l");
+      else if (mode === "count") args.push("-c", "--with-filename");
+      else {
+        args.push("--with-filename", "--no-heading");
+        if (o.lineNumbers) args.push("-n");
+        if (o.before) args.push("-B", String(o.before));
+        if (o.after) args.push("-A", String(o.after));
+      }
+      if (input["-i"]) args.push("-i");
+      if (o.multiline) args.push("-U", "--multiline-dotall");
+      if (input.type) args.push("--type", input.type);
+      args.push("-e", input.pattern, "--");
+
+      /** @type {string[][]} */
+      let targetChunks = [[root]];
+      if (input.glob) {
+        // ripgrep searches explicitly named files regardless of --type/--glob,
+        // so the type filter goes on the listing, and the glob is ours.
+        let candidates = [root];
+        if (rootStat.isDirectory()) {
+          const listArgs = ["--files", "--no-config", "--no-messages", ...RG_EXCLUDES];
+          if (input.type) listArgs.push("--type", input.type);
+          const listed = await runRipgrep([...listArgs, "--", root], { cwd: ctx.cwd, signal: ctx.signal });
+          if (!listed.ok) return { ok: false, error: listed.error };
+          candidates = listed.stdout.split("\n").filter(Boolean);
+        }
+        const selected = candidates.filter((f) => matchGlob(globPath(f), input.glob));
+        targetChunks = [];
+        for (let i = 0; i < selected.length; i += RG_FILES_PER_CALL) targetChunks.push(selected.slice(i, i + RG_FILES_PER_CALL));
+      }
+      lines = [];
+      for (const chunk of targetChunks) {
+        if (ctx.signal?.aborted) break;
+        const r = await runRipgrep([...args, ...chunk], { cwd: ctx.cwd, signal: ctx.signal });
+        if (!r.ok) return { ok: false, error: r.error };
+        lines.push(...r.stdout.split("\n").filter((l) => l !== ""));
+        if (lines.length > headLimit * 4) break;
+      }
+      if (mode === "files_with_matches") lines = sortByMtime(lines);
+    } else {
+      let re;
+      try {
+        re = new RegExp(input.pattern, `g${input["-i"] ? "i" : ""}${o.multiline ? "s" : ""}`);
+      } catch (e) {
+        return { ok: false, error: `Invalid regular expression: ${e instanceof Error ? e.message : e}` };
+      }
+      const files = rootStat.isDirectory() ? walkFiles(root, { signal: ctx.signal }) : [root];
+      const exts = input.type ? TYPE_EXTENSIONS[input.type] : null;
+      const selected = files.filter((f) => {
+        if (exts && !exts.includes(path.extname(f))) return false;
+        if (input.glob && !matchGlob(globPath(f), input.glob)) return false;
+        return true;
+      });
+      lines = [];
+      const ordered = mode === "files_with_matches" ? sortByMtime(selected) : selected.sort();
+      for (const f of ordered) {
+        if (ctx.signal?.aborted) break;
+        let buf;
+        try {
+          if (statSync(f).size > MAX_SEARCH_BYTES) continue;
+          buf = readFileSync(f);
+        } catch {
+          continue; // unreadable or vanished file: skip, as ripgrep does with --no-messages
+        }
+        if (buf.subarray(0, 8192).includes(0)) continue; // binary
+        lines.push(...searchText(f, buf.toString("utf8"), re, o));
+        if (lines.length > headLimit * 4) break;
+      }
+    }
+
+    if (lines.length === 0) return { ok: true, content: "No matches found." };
+    const shown = lines.slice(0, headLimit);
+    const more = lines.length - shown.length;
+    return { ok: true, content: shown.join("\n") + (more > 0 ? `\n(output truncated at ${headLimit} lines)` : "") };
+  },
+};