@mono-agent/agent-runtime 0.1.0

package/src/agent/index.js

@@ -0,0 +1,40 @@
+// Public surface of the agent kernel. The kernel is consumed by the
+// worker, the assistant, the Slack triage path, and the coordinator's
+// run-spawn path. Everything below is intentionally re-exported; anything
+// not listed here is private to the kernel and should not be imported
+// from edge layers.
+
+export {
+  createAgentCompactionManager,
+  isLikelyContextTermination,
+} from "./compaction.js";
+
+export {
+  buildTranscriptTailSnapshot,
+  renderResumeSnapshot,
+} from "./transcript.js";
+
+export {
+  ALLOWLIST_MODE_ALL,
+  ALLOWLIST_MODE_CUSTOM,
+  inferAllowlistMode,
+  normalizeAllowlistMode,
+  normalizeList,
+  parseStoredAllowlist,
+  resolveAllowlist,
+  resolveAllowlistMap,
+  storedAllowlistMode,
+} from "./allowlists.js";
+
+export {
+  APPROVAL_DECISIONS,
+  RISK_TIERS,
+  createApprovalManager,
+  wrapToolsWithApprovalGate,
+} from "./approval.js";
+
+export {
+  BINARY_BLOAT_TOOLS,
+  DEFAULT_TOOL_BLOAT_CONFIG,
+  MAX_TOOL_RESULT_BYTES,
+} from "./tool-bloat.js";

package/src/agent/prompt/skill-index.js

@@ -0,0 +1,66 @@
+// Skill-rendering helpers used to inject skill bodies and metadata into
+// agent system prompts. Lives in agent/prompt/ because the rendering shape
+// is a kernel concern; data loading (loadSkills, parseSkillFrontmatter)
+// stays in core/skills.js.
+
+import { dirname, resolve } from "node:path";
+
+const SKILL_PATH_RULE = "Path rule: Files referenced by SKILL.md are bundled with the skill. Resolve `scripts/...`, `references/...`, and `assets/...` relative to that skill's directory; resolve `<skill-directory-name>/...` relative to the configured skills root.";
+
+function skillDir(skill) {
+  if (!skill?.assetsPath || typeof skill.assetsPath !== "string") return "";
+  return resolve(skill.assetsPath);
+}
+
+export function inferSkillsRoot(skills = []) {
+  const roots = [...new Set(skills.map(skillDir).filter(Boolean).map(dirname))];
+  return roots.length === 1 ? roots[0] : "";
+}
+
+export function getSkillAccessDirs(skills = []) {
+  const root = inferSkillsRoot(skills);
+  if (root) return [root];
+  return [...new Set(skills.map(skillDir).filter(Boolean))];
+}
+
+export function buildSkillPathNote({ assetsPath, skillsRoot } = {}) {
+  const lines = [];
+  if (skillsRoot) lines.push(`Configured skills root: ${resolve(skillsRoot)}`);
+  if (assetsPath) lines.push(`Skill directory: ${resolve(assetsPath)}`);
+  lines.push(SKILL_PATH_RULE);
+  return lines.join("\n");
+}
+
+export function formatSkillBodyWithPathNote({ body, assetsPath, skillsRoot, maxChars = 12000 } = {}) {
+  const text = [
+    buildSkillPathNote({ assetsPath, skillsRoot }),
+    String(body || "").trim(),
+  ].filter(Boolean).join("\n\n");
+  return maxChars ? text.slice(0, maxChars) : text;
+}
+
+export function buildSkillIndex(skills) {
+  const enabled = skills.filter((s) => s.enabled);
+  const lines = ["## Available skills", ""];
+  const skillsRoot = inferSkillsRoot(enabled);
+  if (skillsRoot) {
+    lines.push(buildSkillPathNote({ skillsRoot }), "");
+  }
+  for (const s of enabled) {
+    const assetsPath = skillDir(s);
+    if (s.priority === "always" && s.body) {
+      lines.push(
+        `### ${s.name}`,
+        "",
+        assetsPath ? buildSkillPathNote({ assetsPath }) : SKILL_PATH_RULE,
+        "",
+        s.body.trim(),
+        "",
+      );
+    } else {
+      const pathText = assetsPath ? ` (directory: ${assetsPath})` : "";
+      lines.push(`- ${s.name}: ${s.trigger}${pathText}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/agent/tool-bloat.js

@@ -0,0 +1,164 @@
+// Tool-result bloat containment.
+//
+// Single tool_result payloads can reach several megabytes and frequently trip
+// the context_bloat warning. This module caps tool_result payloads before they
+// reach the model and substitutes a compact reference text so the agent can
+// still cite the artifact.
+//
+// Persistence is delegated to the host via a `persistArtifact({ filename, buffer,
+// toolName, toolUseId }) -> path | null` callback. Host output sinks
+// in src/core/tool-artifacts.js writes to {runArtifactDir}/tool-output/<file>.
+// Hosts that don't care can pass null and the truncated payload is dropped.
+
+export const MAX_TOOL_RESULT_BYTES = 262144;
+
+export const BINARY_BLOAT_TOOLS = Object.freeze([
+  "mcp__playwright__browser_take_screenshot",
+  "mcp__playwright__browser_snapshot",
+]);
+
+export const DEFAULT_TOOL_BLOAT_CONFIG = Object.freeze({
+  maxBytes: MAX_TOOL_RESULT_BYTES,
+  binaryBloatTools: BINARY_BLOAT_TOOLS,
+});
+
+function blockBytes(block) {
+  if (!block || typeof block !== "object") return 0;
+  if (block.type === "text") return Buffer.byteLength(String(block.text || ""), "utf8");
+  if (block.type === "image") {
+    const data = String(block.data || "");
+    const clean = data.includes(",") ? data.slice(data.indexOf(",") + 1) : data;
+    return Math.floor(clean.length * 0.75);
+  }
+  try { return Buffer.byteLength(JSON.stringify(block), "utf8"); } catch { return 0; }
+}
+
+function totalBytes(blocks) {
+  if (!Array.isArray(blocks)) return 0;
+  return blocks.reduce((sum, block) => sum + blockBytes(block), 0);
+}
+
+function safeBasename(name) {
+  return String(name || "tool").replace(/[^A-Za-z0-9_.-]+/g, "_").slice(0, 80);
+}
+
+function imageExtension(block) {
+  const mime = block?.mimeType || block?.mime_type || "";
+  const m = /image\/([a-z0-9]+)/i.exec(mime);
+  return m ? `.${m[1].toLowerCase()}` : ".bin";
+}
+
+function persistBlock(toolName, block, idx, idTag, persistArtifact) {
+  if (typeof persistArtifact !== "function" || !block || typeof block !== "object") return null;
+  let filename;
+  let buffer;
+  if (block.type === "image") {
+    filename = `${safeBasename(toolName)}__${idTag}__${idx}${imageExtension(block)}`;
+    const data = String(block.data || "");
+    const clean = data.includes(",") ? data.slice(data.indexOf(",") + 1) : data;
+    buffer = Buffer.from(clean, "base64");
+  } else {
+    const text = block.type === "text"
+      ? String(block.text || "")
+      : (() => {
+          try { return JSON.stringify(block, null, 2); } catch { return String(block); }
+        })();
+    filename = `${safeBasename(toolName)}__${idTag}__${idx}.txt`;
+    buffer = Buffer.from(text, "utf8");
+  }
+  try {
+    const path = persistArtifact({ filename, buffer, toolName, toolUseId: idTag });
+    return typeof path === "string" && path.length ? path : null;
+  } catch {
+    return null;
+  }
+}
+
+function summaryText(toolName, originalBytes, maxBytes, savedPaths) {
+  const parts = [
+    `[truncated tool_result: ${originalBytes} bytes exceeded ${maxBytes} byte cap`,
+    `tool=${toolName}`,
+  ];
+  if (savedPaths.length === 1) parts.push(`saved_to=${savedPaths[0]}`);
+  else if (savedPaths.length > 1) parts.push(`saved_to=[${savedPaths.length} files]`);
+  else parts.push("persistence unavailable");
+  return `${parts.join("; ")}]`;
+}
+
+export function summarisePayload(toolName, contentBlocks, persistArtifact, options = {}) {
+  const {
+    maxBytes = MAX_TOOL_RESULT_BYTES,
+    toolUseId = null,
+    now = Date.now,
+  } = options;
+  const blocks = Array.isArray(contentBlocks) ? contentBlocks : [];
+  const originalBytes = totalBytes(blocks);
+  if (originalBytes <= maxBytes) {
+    return { rewrittenBlocks: blocks, savedPaths: [], originalBytes, truncated: false };
+  }
+
+  const stamp = String(now()).slice(-10);
+  const idTag = toolUseId ? safeBasename(toolUseId) : `payload-${stamp}`;
+  const savedPaths = [];
+  blocks.forEach((block, idx) => {
+    const path = persistBlock(toolName, block, idx, idTag, persistArtifact);
+    if (path) savedPaths.push(path);
+  });
+  return {
+    rewrittenBlocks: [{ type: "text", text: summaryText(toolName, originalBytes, maxBytes, savedPaths) }],
+    savedPaths,
+    originalBytes,
+    truncated: true,
+  };
+}
+
+export async function applyToolBloatGuard(toolName, executePromise, options = {}) {
+  const {
+    persistArtifact = null,
+    toolUseId = null,
+    maxBytes = MAX_TOOL_RESULT_BYTES,
+    onTruncate = null,
+  } = options;
+  const result = await executePromise;
+  if (!result || typeof result !== "object" || !Array.isArray(result.content)) return result;
+  const summary = summarisePayload(toolName, result.content, persistArtifact, { maxBytes, toolUseId });
+  if (!summary.truncated) return result;
+  if (typeof onTruncate === "function") {
+    try {
+      onTruncate({
+        tool: toolName,
+        tool_use_id: toolUseId,
+        original_bytes: summary.originalBytes,
+        max_bytes: maxBytes,
+        saved_paths: summary.savedPaths,
+      });
+    } catch { /* best-effort */ }
+  }
+  return {
+    ...result,
+    content: summary.rewrittenBlocks,
+    details: {
+      ...(result.details || {}),
+      tool_payload_truncated: true,
+      tool_payload_original_bytes: summary.originalBytes,
+      tool_payload_saved_paths: summary.savedPaths,
+    },
+  };
+}
+
+export function wrapToolsWithBloatGuard(tools, options = {}) {
+  const list = Array.isArray(tools) ? tools : [];
+  return list.map((tool) => {
+    if (!tool || typeof tool.execute !== "function") return tool;
+    const originalExecute = tool.execute.bind(tool);
+    return {
+      ...tool,
+      async execute(toolCallId, params, signal) {
+        return applyToolBloatGuard(tool.name, originalExecute(toolCallId, params, signal), {
+          ...options,
+          toolUseId: toolCallId,
+        });
+      },
+    };
+  });
+}

package/src/agent/tools/bash.js

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { prepareSandboxedCommand } from "@mono-agent/sandbox";
+import { DEFAULT_MAX_BASH_OUTPUT_CHARS } from "./shared/constants.js";
+import { capChars } from "./shared/output-truncation.js";
+import {
+  isPathAllowed,
+  isWorkdirAllowed,
+  workspaceRoot,
+} from "./shared/path-resolver.js";
+import { resolveSandboxPolicy } from "./shared/runtime-context.js";
+
+const DEFAULT_BASH_TIMEOUT_MS = 120000;
+const BASH_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+const KILL_GRACE_MS = 1000;
+
+export function normalizeBashTimeoutMs(value, fallback = DEFAULT_BASH_TIMEOUT_MS) {
+  const cap = Number.isFinite(Number(fallback)) && Number(fallback) > 0
+    ? Math.floor(Number(fallback))
+    : DEFAULT_BASH_TIMEOUT_MS;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return cap;
+  const floored = Math.floor(n);
+  const ms = floored <= 600 ? floored * 1000 : floored;
+  return Math.max(1000, Math.min(ms, cap));
+}
+
+function killProcessGroup(child, signal) {
+  if (!child?.pid) return;
+  try {
+    process.kill(process.platform === "win32" ? child.pid : -child.pid, signal);
+  } catch {
+    try { process.kill(child.pid, signal); } catch { /* already gone */ }
+  }
+}
+
+function appendChunk(chunks, chunk, state) {
+  state.bytes += chunk.length;
+  if (state.bytes > state.maxBufferBytes) {
+    state.bufferExceeded = true;
+    return false;
+  }
+  chunks.push(chunk);
+  return true;
+}
+
+function runCommand(commandSpec, { timeoutMs, signal, maxBufferBytes = BASH_MAX_BUFFER_BYTES }) {
+  return new Promise((resolve) => {
+    const child = spawn(commandSpec.command, commandSpec.args || [], {
+      cwd: commandSpec.cwd,
+      detached: true,
+      env: commandSpec.env ? { ...process.env, ...commandSpec.env } : process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout = [];
+    const stderr = [];
+    const state = {
+      aborted: false,
+      bufferExceeded: false,
+      bytes: 0,
+      maxBufferBytes,
+      spawnError: null,
+      timedOut: false,
+    };
+    let killTimer = null;
+    let settled = false;
+
+    function terminate() {
+      killProcessGroup(child, "SIGTERM");
+      if (!killTimer) {
+        killTimer = setTimeout(() => killProcessGroup(child, "SIGKILL"), KILL_GRACE_MS);
+        killTimer.unref?.();
+      }
+    }
+
+    const timeoutTimer = setTimeout(() => {
+      state.timedOut = true;
+      terminate();
+    }, timeoutMs);
+    timeoutTimer.unref?.();
+
+    const onAbort = () => {
+      state.aborted = true;
+      terminate();
+    };
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener?.("abort", onAbort, { once: true });
+
+    child.stdout?.on("data", (chunk) => {
+      if (!appendChunk(stdout, chunk, state)) terminate();
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (!appendChunk(stderr, chunk, state)) terminate();
+    });
+    child.once("error", (err) => {
+      state.spawnError = err;
+    });
+    child.once("close", (code, closeSignal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      signal?.removeEventListener?.("abort", onAbort);
+      resolve({
+        code,
+        signal: closeSignal,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        ...state,
+      });
+    });
+  });
+}
+
+export async function bashToolImpl({ command, timeout = DEFAULT_BASH_TIMEOUT_MS, max_output_chars, workdir }, { signal, sandboxPolicy, sandboxEngine } = {}) {
+  const policy = resolveSandboxPolicy(sandboxPolicy);
+  const pathOptions = { sandboxPolicy: policy };
+  if (workdir && !isWorkdirAllowed(workdir, pathOptions)) return `Error: Working directory not allowed: ${workdir}`;
+  const cwd = workspaceRoot(workdir);
+  if (!isPathAllowed(cwd, workdir, pathOptions)) return `Error: Working directory not allowed: ${cwd}`;
+  if (!existsSync(cwd)) return `Error: Working directory not found: ${cwd}`;
+  const maxChars = Number(max_output_chars) || DEFAULT_MAX_BASH_OUTPUT_CHARS;
+  const timeoutMs = normalizeBashTimeoutMs(timeout);
+  let prepared;
+  try {
+    prepared = await prepareSandboxedCommand({
+      policy,
+      engine: sandboxEngine ?? undefined,
+      command: { command: "/bin/bash", args: ["-lc", command], cwd },
+    });
+  } catch (err) {
+    return `Error: ${err?.message || String(err)}`;
+  }
+  let result;
+  try {
+    result = await runCommand(prepared, { timeoutMs, signal });
+  } finally {
+    await prepared.cleanup?.();
+  }
+  if (result.timedOut) return `Error: Command timed out after ${timeoutMs}ms`;
+  if (result.aborted) return "Error: Command aborted";
+  if (result.bufferExceeded) return `Error: Command output exceeded ${BASH_MAX_BUFFER_BYTES} bytes`;
+  if (result.spawnError) return `Exit code 1:\n${result.spawnError.message}`;
+  if (result.code && result.code !== 0) {
+    return capChars(`Exit code ${result.code || 1}:\n${result.stdout || ""}${result.stderr || ""}`, {
+      label: "Bash",
+      maxChars,
+      strategy: "head_tail",
+    });
+  }
+  if (result.signal) return `Exit code 1:\nCommand terminated by ${result.signal}`;
+  const output = result.stdout && result.stderr
+    ? `STDOUT:\n${result.stdout}\nSTDERR:\n${result.stderr}`
+    : (result.stdout || result.stderr || "(no output)");
+  return capChars(output, { label: "Bash", maxChars, strategy: "head_tail" });
+}

package/src/agent/tools/edit.js

@@ -0,0 +1,15 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isPathAllowed, isWritablePathAllowed, resolveToolPath } from "./shared/path-resolver.js";
+
+export async function editToolImpl({ file_path, old_string, new_string, replace_all = false, workdir }, { sandboxPolicy } = {}) {
+  const target = resolveToolPath(file_path, workdir);
+  const pathOptions = { sandboxPolicy };
+  if (!isPathAllowed(target, workdir, pathOptions) || !isWritablePathAllowed(target, workdir, pathOptions)) return `Error: Path not allowed: ${file_path}`;
+  if (!existsSync(target)) return `Error: File not found: ${file_path}`;
+  const content = readFileSync(target, "utf8");
+  const count = content.split(old_string).length - 1;
+  if (count === 0) return `Error: old_string not found in ${target}`;
+  if (!replace_all && count > 1) return `Error: old_string found ${count} times`;
+  writeFileSync(target, replace_all ? content.replaceAll(old_string, new_string) : content.replace(old_string, new_string), "utf8");
+  return `Successfully edited ${target}`;
+}

package/src/agent/tools/glob.js

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import {
+  DEFAULT_MAX_SEARCH_CHARS,
+  DEFAULT_MAX_SEARCH_LINES,
+  SEARCH_MAX_BUFFER,
+} from "./shared/constants.js";
+import { boundedInt, safeStat } from "./shared/dedup.js";
+import {
+  isPathAllowed,
+  resolveToolPath,
+  workspaceRoot,
+} from "./shared/path-resolver.js";
+import {
+  capLines,
+  excludedGlobArgs,
+  excludedPathSummary,
+  formatSearchLines,
+  normalizeGlobPattern,
+  resolveRgPath,
+  ripgrepMissingMessage,
+} from "./shared/ripgrep.js";
+
+const execFileAsync = promisify(execFile);
+
+export async function globToolImpl({ pattern, path, limit, offset = 0, max_matches, max_output_chars, workdir }, { sandboxPolicy } = {}) {
+  const cwd = resolveToolPath(path || workspaceRoot(workdir), workdir);
+  if (!isPathAllowed(cwd, workdir, { sandboxPolicy })) return `Error: Path not allowed: ${cwd}`;
+  const stat = safeStat(cwd);
+  if (!stat?.isDirectory()) return `Error: Glob path is not a directory: ${cwd}`;
+  const resultLimit = boundedInt(limit ?? max_matches, DEFAULT_MAX_SEARCH_LINES, { min: 1, max: 1000 });
+  const args = [
+    "--files",
+    "--hidden",
+    "--color=never",
+    "--glob",
+    normalizeGlobPattern(pattern),
+    ...excludedGlobArgs(),
+  ];
+  const rgPath = resolveRgPath();
+  if (!rgPath) return ripgrepMissingMessage();
+  try {
+    const { stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER });
+    const lines = stdout.trim().split("\n").filter(Boolean).sort((a, b) => {
+      const aStat = safeStat(resolve(cwd, a));
+      const bStat = safeStat(resolve(cwd, b));
+      return (bStat?.mtimeMs || 0) - (aStat?.mtimeMs || 0) || a.localeCompare(b);
+    });
+    const result = formatSearchLines(lines, {
+      label: "Glob",
+      noMatches: "No files found matching pattern.",
+      maxLines: resultLimit,
+      maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
+      offset,
+    });
+    return result === "No files found matching pattern." ? result : `${result}\n\n${excludedPathSummary()}`;
+  } catch (err) {
+    if (err.code === 1) return "No files found matching pattern.";
+    if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" || /maxBuffer/i.test(err.message || "")) {
+      return `${capLines(err.stdout || "", {
+        label: "Glob",
+        noMatches: "Glob result exceeded the output limit before any preview could be captured.",
+        maxLines: resultLimit,
+        maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
+        offset,
+      })}\n\n${excludedPathSummary()}`;
+    }
+    return `Error: ${err.message}`;
+  }
+}

package/src/agent/tools/grep.js

@@ -0,0 +1,84 @@
+import { execFile } from "node:child_process";
+import { basename, dirname } from "node:path";
+import { promisify } from "node:util";
+import {
+  DEFAULT_MAX_SEARCH_CHARS,
+  DEFAULT_MAX_SEARCH_LINES,
+  SEARCH_MAX_BUFFER,
+} from "./shared/constants.js";
+import { boundedInt, safeStat } from "./shared/dedup.js";
+import {
+  isPathAllowed,
+  resolveToolPath,
+  workspaceRoot,
+} from "./shared/path-resolver.js";
+import {
+  capLines,
+  excludedGlobArgs,
+  excludedPathSummary,
+  resolveRgPath,
+  ripgrepMissingMessage,
+} from "./shared/ripgrep.js";
+
+const execFileAsync = promisify(execFile);
+
+export async function grepToolImpl({
+  pattern,
+  path,
+  glob,
+  type,
+  output_mode = "files_with_matches",
+  context,
+  case_insensitive,
+  multiline,
+  head_limit,
+  offset = 0,
+  max_matches,
+  max_output_chars,
+  workdir,
+}, { sandboxPolicy } = {}) {
+  const target = resolveToolPath(path || workspaceRoot(workdir), workdir);
+  if (!isPathAllowed(target, workdir, { sandboxPolicy })) return `Error: Path not allowed: ${target}`;
+  const stat = safeStat(target);
+  if (!stat) return `Error: Path not found: ${target}`;
+  const cwd = stat.isDirectory() ? target : dirname(target);
+  const searchTarget = stat.isDirectory() ? "." : basename(target);
+  const mode = ["content", "count", "files_with_matches"].includes(output_mode) ? output_mode : "files_with_matches";
+  const args = ["--no-config", "--hidden", "--color=never"];
+  if (mode === "files_with_matches") args.push("--files-with-matches");
+  else if (mode === "count") args.push("--count-matches");
+  else args.push("--line-number");
+  if (case_insensitive) args.push("-i");
+  if (mode === "content" && context) args.push(`-C${boundedInt(context, 0, { min: 0, max: 20 })}`);
+  if (multiline) args.push("-U", "--multiline-dotall");
+  if (glob) args.push("--glob", glob);
+  if (type) args.push("--type", type);
+  args.push(...excludedGlobArgs(), "--", pattern, searchTarget);
+  const resultLimit = boundedInt(head_limit ?? max_matches, DEFAULT_MAX_SEARCH_LINES, { min: 1, max: 1000 });
+  const rgPath = resolveRgPath();
+  if (!rgPath) return ripgrepMissingMessage();
+  try {
+    const { stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER });
+    const normalized = stdout.trim().split("\n").filter(Boolean).map((line) => line.replace(/^\.\//, ""));
+    const formatted = capLines(normalized.join("\n"), {
+      label: "Grep",
+      noMatches: "No matches found.",
+      maxLines: resultLimit,
+      maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
+      offset,
+    });
+    return formatted === "No matches found." ? formatted : `${formatted}\n\n${excludedPathSummary()}`;
+  } catch (err) {
+    if (err.code === 1) return "No matches found.";
+    if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" || /maxBuffer/i.test(err.message || "")) {
+      return `${capLines(err.stdout || "", {
+        label: "Grep",
+        noMatches: "Grep result exceeded the output limit before any preview could be captured.",
+        maxLines: resultLimit,
+        maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
+        offset,
+      })}\n\n${excludedPathSummary()}`;
+    }
+    return `Error: ${err.message}`;
+  }
+}

package/src/agent/tools/index.js

@@ -0,0 +1,17 @@
+// Barrel re-exporting per-tool implementations and the small bit of shared
+// surface that callers outside this directory consume (the path/workdir
+// guards plus the ripgrep resolver used by the configured doctor command. Each tool
+// implementation lives in its own file under `./` and pulls helpers from
+// `./shared/`. `pi-bridge.js` imports the tool impls from this barrel.
+
+export { readToolImpl } from "./read.js";
+export { writeToolImpl } from "./write.js";
+export { editToolImpl } from "./edit.js";
+export { globToolImpl } from "./glob.js";
+export { grepToolImpl } from "./grep.js";
+export { bashToolImpl, normalizeBashTimeoutMs } from "./bash.js";
+export { webFetchToolImpl } from "./web-fetch.js";
+export { webSearchToolImpl } from "./web-search.js";
+
+export { isPathAllowed, isWorkdirAllowed } from "./shared/path-resolver.js";
+export { resolveRgPath } from "./shared/ripgrep.js";