@kb-labs/agent-tools 0.2.0

package/dist/index.js

@@ -0,0 +1,3983 @@
+import * as fs2 from 'fs';
+import * as path4 from 'path';
+import path4__default from 'path';
+import * as crypto from 'crypto';
+import { glob } from 'glob';
+import { execSync } from 'child_process';
+import { useLLM } from '@kb-labs/sdk';
+import * as readline from 'readline';
+import { useLLM as useLLM$1 } from '@kb-labs/sdk/hooks';
+
+// src/registry.ts
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  /**
+   * Register a tool
+   */
+  register(tool) {
+    this.tools.set(tool.definition.function.name, tool);
+  }
+  /**
+   * Get tool by name
+   */
+  get(name) {
+    return this.tools.get(name);
+  }
+  /**
+   * Get all tool definitions for LLM
+   */
+  getDefinitions() {
+    return Array.from(this.tools.values()).map((t) => t.definition);
+  }
+  /**
+   * Execute a tool with automatic required-argument validation.
+   * Returns a structured error if required args are missing/null/undefined,
+   * so the agent understands what went wrong and can correct its call.
+   */
+  async execute(name, input) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      return {
+        success: false,
+        output: `UNKNOWN_TOOL: "${name}" is not a registered tool. Available tools: ${this.getToolNames().join(", ")}`
+      };
+    }
+    const required = tool.definition.function.parameters?.required ?? [];
+    const missing = required.filter(
+      (key) => input[key] === void 0 || input[key] === null
+    );
+    if (missing.length > 0) {
+      const params = tool.definition.function.parameters?.properties ?? {};
+      const details = missing.map((k) => {
+        const desc = params[k]?.description ?? "";
+        return `  - ${k}${desc ? ": " + desc : ""}`;
+      }).join("\n");
+      return {
+        success: false,
+        output: `MISSING_REQUIRED_ARGUMENTS for tool "${name}":
+${details}
+
+Hint: if a string argument is missing, your response may have been cut off by the output token limit (stop_reason=max_tokens). For large content, write in multiple smaller calls instead of one large call.`
+      };
+    }
+    return tool.executor(input);
+  }
+  /**
+   * Get sorted list of registered tool names
+   */
+  getToolNames() {
+    return Array.from(this.tools.keys()).sort();
+  }
+  /**
+   * Get context
+   */
+  getContext() {
+    return this.context;
+  }
+};
+
+// src/tools/shared/tool-error.ts
+function toolError(input) {
+  const parts = [`${input.code}: ${input.message}`];
+  if (input.hint) {
+    parts.push(`
+Next step: ${input.hint}`);
+  }
+  if (input.retryable === false) {
+    parts.push("(This error cannot be resolved by retrying the same call.)");
+  }
+  const error = parts.join("\n");
+  return {
+    success: false,
+    error,
+    errorDetails: {
+      code: input.code,
+      message: input.message,
+      retryable: input.retryable,
+      hint: input.hint,
+      details: input.details
+    },
+    metadata: {
+      errorCode: input.code,
+      retryable: input.retryable ?? false,
+      ...input.details || {}
+    }
+  };
+}
+
+// src/config.ts
+var FILESYSTEM_CONFIG = {
+  /** Hard cap on file size to read (500KB) — prevents context overflow */
+  maxFileSize: 5e5,
+  /** Hard cap on lines returned per read — prevents context overflow */
+  maxLinesPerRead: 2e3,
+  /** Default lines to return when not specified — read whole file up to maxLinesPerRead */
+  defaultLines: 2e3,
+  /** Hard cap on content size for write operations (1MB) */
+  maxWriteSize: 1e6,
+  /** Default limit for directory listing */
+  defaultListLimit: 50,
+  /** Maximum limit for directory listing */
+  maxListLimit: 200,
+  /** Max output characters before trimming (prevents context explosion) */
+  maxOutputChars: 12e3
+};
+var SEARCH_CONFIG = {
+  /** Timeout for search commands (15s) — fail fast, don't burn iterations */
+  timeoutMs: 15e3,
+  /** Max stdout buffer for search commands (8MB) */
+  maxBuffer: 8 * 1024 * 1024,
+  /** Default result limit — enough for actionable results */
+  defaultResultLimit: 50,
+  /** Maximum result limit */
+  maxResultLimit: 200,
+  /** Max output characters before trimming */
+  maxOutputChars: 8e3,
+  /**
+   * Directories excluded from search by default.
+   * These are never useful for code understanding and often huge.
+   * Pass exclude=[] to override entirely, or exclude=[...custom] to replace the list.
+   */
+  defaultExcludes: [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".kb",
+    ".pnpm",
+    "coverage",
+    "__pycache__",
+    ".venv",
+    ".cache"
+  ]
+};
+var SHELL_CONFIG = {
+  /** Max stdout buffer — aligned with SEARCH_CONFIG (16MB) */
+  maxBuffer: 16 * 1024 * 1024
+};
+var TODO_CONFIG = {
+  /** Cache key prefix for todo lists */
+  cachePrefix: "agent:todo:",
+  /** TTL for cached todo lists (7 days) */
+  cacheTtlMs: 7 * 24 * 60 * 60 * 1e3
+};
+var DELEGATION_CONFIG = {
+  /** Default max iterations for spawned sub-agents (safety net — token budget is primary control) */
+  defaultMaxIterations: 100,
+  /** Default budget fraction (50% of parent remaining — sub-agents need real budget) */
+  defaultBudgetFraction: 0.5
+};
+var SUB_AGENT_PRESETS = {
+  /** Read-only exploration and evidence gathering. */
+  research: {
+    tools: /* @__PURE__ */ new Set([
+      "fs_read",
+      "fs_list",
+      "glob_search",
+      "grep_search",
+      "find_definition",
+      "code_stats",
+      "memory_get",
+      "memory_finding",
+      "archive_recall",
+      "todo_get",
+      "report"
+    ]),
+    maxIterations: 50
+  },
+  /** Full read/write capabilities for implementation tasks. */
+  execute: {
+    tools: /* @__PURE__ */ new Set([
+      "fs_read",
+      "fs_write",
+      "fs_patch",
+      "fs_replace",
+      "fs_list",
+      "mass_replace",
+      "glob_search",
+      "grep_search",
+      "find_definition",
+      "code_stats",
+      "shell_exec",
+      "memory_get",
+      "memory_finding",
+      "memory_blocker",
+      "memory_correction",
+      "todo_create",
+      "todo_update",
+      "todo_get",
+      "plan_write",
+      "ask_user",
+      "report"
+    ]),
+    maxIterations: 100
+  },
+  /** Code review and verification: read + shell (linters, tests). */
+  review: {
+    tools: /* @__PURE__ */ new Set([
+      "fs_read",
+      "fs_list",
+      "glob_search",
+      "grep_search",
+      "find_definition",
+      "code_stats",
+      "shell_exec",
+      "memory_get",
+      "memory_finding",
+      "archive_recall",
+      "todo_get",
+      "report"
+    ]),
+    maxIterations: 50
+  },
+  /**
+   * Adversarial verification: independent agent that checks another agent's work.
+   * Has read + shell access to run tests, check imports, verify builds.
+   * Reports PASS/FAIL verdict with evidence.
+   */
+  verification: {
+    tools: /* @__PURE__ */ new Set([
+      "fs_read",
+      "fs_list",
+      "glob_search",
+      "grep_search",
+      "find_definition",
+      "code_stats",
+      "shell_exec",
+      "report"
+    ]),
+    maxIterations: 25
+  }
+};
+var MASS_REPLACE_CONFIG = {
+  /** Hard cap on file size to process (1MB) — same as maxWriteSize */
+  maxFileSize: 1e6,
+  /** Maximum number of files to process in one operation */
+  maxFiles: 100
+};
+var PLAN_READ_ONLY_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "fs_read",
+  "fs_list",
+  "glob_search",
+  "grep_search",
+  "find_definition",
+  "code_stats",
+  "memory_get",
+  "memory_finding",
+  "memory_blocker",
+  "archive_recall",
+  "todo_create",
+  "todo_update",
+  "todo_get",
+  "ask_user",
+  "report",
+  "task_submit",
+  // plan-writer can delegate research to async sub-agents
+  "task_status",
+  // check progress of delegated tasks
+  "task_collect",
+  // wait for and collect sub-agent results
+  "plan_validate",
+  // LLM-based plan quality gate (agent calls this to self-assess before report)
+  "plan_write"
+  // Write/update plan file on disk (iterative plan building)
+]);
+var SOURCE_FILE_EXTENSIONS = {
+  typescript: ["ts", "tsx"],
+  javascript: ["js", "jsx"],
+  python: ["py"],
+  csharp: ["cs"],
+  java: ["java"],
+  go: ["go"],
+  rust: ["rs"],
+  ruby: ["rb"],
+  php: ["php"],
+  swift: ["swift"],
+  kotlin: ["kt"],
+  scala: ["scala"],
+  cpp: ["cpp", "c", "h", "cc", "cxx"]
+};
+var ALL_SOURCE_EXTENSIONS = Object.values(SOURCE_FILE_EXTENSIONS).flat();
+function toRgIncludes(exts) {
+  return exts.map((e) => `--include="*.${e}"`).join(" ");
+}
+function toFindNames(exts) {
+  return exts.map((e) => `-name "*.${e}"`).join(" -o ");
+}
+function normalizeOffsetLimit(input, config) {
+  const rawOffset = Number(input.offset);
+  const rawLimit = Number(input.limit);
+  const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? Math.floor(rawOffset) : 0;
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(config.maxLimit, Math.floor(rawLimit)) : config.defaultLimit;
+  return { offset, limit };
+}
+function validatePath(workingDir, filePath) {
+  let resolved = path4.resolve(workingDir, filePath);
+  try {
+    if (fs2.existsSync(resolved)) {
+      resolved = fs2.realpathSync(resolved);
+    }
+  } catch {
+  }
+  const relative3 = path4.relative(workingDir, resolved);
+  if (relative3.startsWith("..")) {
+    return {
+      valid: false,
+      resolved,
+      error: `PATH_TRAVERSAL_ERROR: Cannot access "${filePath}" - path is outside working directory.
+
+HOW TO FIX: Use paths relative to the working directory. Do not use ".." to navigate above it.
+WORKING_DIR: ${workingDir}
+ATTEMPTED_PATH: ${resolved}`
+    };
+  }
+  return { valid: true, resolved };
+}
+function suggestDirectory(workingDir, requestedDir) {
+  const clean = requestedDir.replace(/^\.\//, "").replace(/\/$/, "");
+  if (!clean || clean === ".") {
+    return null;
+  }
+  const parts = clean.split("/");
+  if (parts.length < 2) {
+    return null;
+  }
+  const candidate = `${parts[0]}-${parts[1]}`;
+  const rest = parts.slice(2).join("/");
+  const fullCandidate = rest ? path4.join(candidate, rest) : candidate;
+  const resolved = path4.resolve(workingDir, fullCandidate);
+  if (fs2.existsSync(resolved) && fs2.statSync(resolved).isDirectory()) {
+    return fullCandidate;
+  }
+  return null;
+}
+
+// src/tools/filesystem/filesystem.ts
+var MAX_FILE_SIZE = FILESYSTEM_CONFIG.maxFileSize;
+var MAX_LINES_PER_READ = FILESYSTEM_CONFIG.maxLinesPerRead;
+var DEFAULT_LINES = FILESYSTEM_CONFIG.defaultLines;
+var MAX_WRITE_SIZE = FILESYSTEM_CONFIG.maxWriteSize;
+var DEFAULT_LIST_LIMIT = FILESYSTEM_CONFIG.defaultListLimit;
+var MAX_LIST_LIMIT = FILESYSTEM_CONFIG.maxListLimit;
+var MAX_OUTPUT_CHARS = FILESYSTEM_CONFIG.maxOutputChars;
+function trimOutput(output, maxChars, continuationHint) {
+  if (output.length <= maxChars) {
+    return output;
+  }
+  const trimmed = output.slice(0, maxChars);
+  return `${trimmed}
+
+\u26A0\uFE0F OUTPUT TRIMMED (${output.length.toLocaleString()} chars \u2192 ${maxChars.toLocaleString()} shown)
+${continuationHint}`;
+}
+function formatSize(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} bytes`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function computeHash(content) {
+  return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function normalizeListWindow(input) {
+  return normalizeOffsetLimit(input, { defaultLimit: DEFAULT_LIST_LIMIT, maxLimit: MAX_LIST_LIMIT });
+}
+function createFsReadTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "fs_read",
+        description: `Read file contents. By default reads the entire file (up to ${MAX_LINES_PER_READ} lines). For very large files, use offset+limit to read specific sections. Prefer reading the whole file when possible \u2014 partial reads waste iterations.`,
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "File path relative to working directory"
+            },
+            offset: {
+              type: "number",
+              description: "Line number to start from (1-indexed, default: 1)"
+            },
+            limit: {
+              type: "number",
+              description: `Number of lines to read (default: all, max: ${MAX_LINES_PER_READ}). Only use for very large files \u2014 prefer reading the whole file.`
+            }
+          },
+          required: ["path"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const filePath = input.path;
+      const offset = Math.max(1, input.offset || 1);
+      const requestedLimit = input.limit || DEFAULT_LINES;
+      const limit = Math.min(requestedLimit, MAX_LINES_PER_READ);
+      const pathValidation = validatePath(context.workingDir, filePath);
+      if (!pathValidation.valid) {
+        return toolError({
+          code: "PATH_VALIDATION_FAILED",
+          message: pathValidation.error || "Invalid path",
+          retryable: false,
+          hint: "Use a path inside working directory.",
+          details: { filePath, workingDir: context.workingDir }
+        });
+      }
+      const fullPath = pathValidation.resolved;
+      if (!fs2.existsSync(fullPath)) {
+        return toolError({
+          code: "FILE_NOT_FOUND",
+          message: `"${filePath}" does not exist.`,
+          retryable: true,
+          hint: `Use fs_list(path="${path4.dirname(filePath) || "."}") to inspect available files.`,
+          details: { filePath, workingDir: context.workingDir }
+        });
+      }
+      const stats = fs2.statSync(fullPath);
+      if (stats.isDirectory()) {
+        return toolError({
+          code: "NOT_A_FILE",
+          message: `"${filePath}" is a directory, not a file.`,
+          retryable: false,
+          hint: "Use fs_list for directories or provide a file path.",
+          details: { filePath }
+        });
+      }
+      if (stats.size > MAX_FILE_SIZE) {
+        return toolError({
+          code: "FILE_TOO_LARGE",
+          message: `"${filePath}" is ${formatSize(stats.size)}, exceeds limit ${formatSize(MAX_FILE_SIZE)}.`,
+          retryable: true,
+          hint: `Use fs_read(path="${filePath}", offset=<line>, limit=<small number>).`,
+          details: { filePath, size: stats.size, maxSize: MAX_FILE_SIZE }
+        });
+      }
+      const content = fs2.readFileSync(fullPath, "utf-8");
+      const allLines = content.split("\n");
+      const totalLines = allLines.length;
+      if (offset > totalLines) {
+        return toolError({
+          code: "OFFSET_OUT_OF_RANGE",
+          message: `Requested offset ${offset} but file has ${totalLines} lines.`,
+          retryable: true,
+          hint: `Use offset between 1 and ${totalLines}.`,
+          details: { filePath, offset, totalLines }
+        });
+      }
+      const startIndex = offset - 1;
+      const endIndex = Math.min(startIndex + limit, totalLines);
+      const selectedLines = allLines.slice(startIndex, endIndex);
+      const numberedLines = selectedLines.map((line, i) => {
+        const lineNum = (startIndex + i + 1).toString().padStart(5, " ");
+        return `${lineNum}\u2192${line}`;
+      });
+      const hasMore = endIndex < totalLines;
+      const linesRemaining = totalLines - endIndex;
+      const warnings = [];
+      if (requestedLimit > MAX_LINES_PER_READ) {
+        warnings.push(`\u26A0\uFE0F Limit capped at ${MAX_LINES_PER_READ} (you requested ${requestedLimit})`);
+      }
+      if (hasMore) {
+        warnings.push(`\u26A0\uFE0F PARTIAL READ: ${linesRemaining} lines unread. Next chunk: fs_read(path="${filePath}", offset=${endIndex + 1})`);
+      }
+      const header = [
+        `File: ${filePath}`,
+        `Lines: ${offset}-${endIndex} of ${totalLines}`,
+        hasMore ? `(${Math.round((endIndex - offset + 1) / totalLines * 100)}% read so far \u2014 ${linesRemaining} lines remain)` : "(end of file \u2713)",
+        ...warnings,
+        "\u2500".repeat(60)
+      ].filter(Boolean).join("\n");
+      const rawOutput = `${header}
+${numberedLines.join("\n")}`;
+      const continuationHint = hasMore ? `Next chunk: fs_read(path="${filePath}", offset=${endIndex + 1})` : "";
+      const hash = computeHash(content);
+      context.filesRead?.add(filePath);
+      context.filesReadHash?.set(filePath, hash);
+      return {
+        success: true,
+        output: trimOutput(rawOutput, MAX_OUTPUT_CHARS, continuationHint),
+        metadata: {
+          filePath,
+          totalLines,
+          readFrom: offset,
+          readTo: endIndex,
+          hasMore,
+          fileSize: stats.size,
+          contentHash: hash
+        }
+      };
+    }
+  };
+}
+function createFsWriteTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "fs_write",
+        description: `Write a new file or completely rewrite an existing one. Creates parent directories if needed. IMPORTANT: Prefer fs_replace for modifying existing files \u2014 it only sends the diff. Only use fs_write to create NEW files or for complete rewrites where the entire content changes. If you're modifying an existing file, use fs_replace instead.`,
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "File path relative to working directory"
+            },
+            content: {
+              type: "string",
+              description: "Content to write to the file"
+            }
+          },
+          required: ["path", "content"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const filePath = input.path;
+      const content = input.content;
+      const pathValidation = validatePath(context.workingDir, filePath);
+      if (!pathValidation.valid) {
+        return toolError({
+          code: "PATH_VALIDATION_FAILED",
+          message: pathValidation.error || "Invalid path",
+          retryable: false,
+          hint: "Use a path inside working directory.",
+          details: { filePath, workingDir: context.workingDir }
+        });
+      }
+      const fullPath = pathValidation.resolved;
+      const contentSize = Buffer.byteLength(content, "utf-8");
+      if (contentSize > MAX_WRITE_SIZE) {
+        return {
+          success: false,
+          error: `CONTENT_TOO_LARGE: Content is ${formatSize(contentSize)}, exceeds limit of ${formatSize(MAX_WRITE_SIZE)}.
+
+HOW TO FIX: Split the content into smaller files, or write in chunks.`
+        };
+      }
+      const isOverwrite = fs2.existsSync(fullPath);
+      const beforeContent = isOverwrite ? fs2.readFileSync(fullPath, "utf-8") : void 0;
+      const dir = path4.dirname(fullPath);
+      if (!fs2.existsSync(dir)) {
+        fs2.mkdirSync(dir, { recursive: true });
+      }
+      fs2.writeFileSync(fullPath, content, "utf-8");
+      const writeHash = computeHash(content);
+      context.filesRead?.add(filePath);
+      context.filesReadHash?.set(filePath, writeHash);
+      const lineCount = content.split("\n").length;
+      return {
+        success: true,
+        output: `${isOverwrite ? "Overwrote" : "Created"} file: ${filePath}
+Size: ${formatSize(contentSize)}
+Lines: ${lineCount}`,
+        metadata: {
+          filePath,
+          fileContent: content,
+          size: contentSize,
+          lines: lineCount,
+          isOverwrite,
+          uiHint: "code",
+          // Consumed by ChangeTrackingMiddleware
+          changeSnapshot: {
+            operation: "write",
+            beforeContent,
+            afterContent: content,
+            isOverwrite
+          }
+        }
+      };
+    }
+  };
+}
+function createFsPatchTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "fs_patch",
+        description: `Replace a range of lines by line numbers. Use fs_replace instead when possible \u2014 it's more reliable. Only use fs_patch for large block replacements where fs_replace match text would be too long. You must fs_read the file first. Line numbers are 1-indexed and inclusive.`,
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "File path relative to working directory"
+            },
+            startLine: {
+              type: "number",
+              description: "First line to replace (1-indexed, inclusive)"
+            },
+            endLine: {
+              type: "number",
+              description: "Last line to replace (1-indexed, inclusive)"
+            },
+            newContent: {
+              type: "string",
+              description: "New content to replace the line range with"
+            }
+          },
+          required: ["path", "startLine", "endLine", "newContent"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const filePath = input.path;
+      const startLine = input.startLine;
+      const endLine = input.endLine;
+      const newContent = input.newContent;
+      const pathValidation = validatePath(context.workingDir, filePath);
+      if (!pathValidation.valid) {
+        return { success: false, error: pathValidation.error };
+      }
+      const fullPath = pathValidation.resolved;
+      if (context.filesRead && !context.filesRead.has(filePath)) {
+        return toolError({
+          code: "CANNOT_EDIT_UNREAD_FILE",
+          message: `File has not been read yet. You must read a file before editing it.`,
+          retryable: true,
+          hint: `Call fs_read(path="${filePath}") to read the file first, then retry this edit.`,
+          details: { filePath, startLine, endLine }
+        });
+      }
+      if (!fs2.existsSync(fullPath)) {
+        return toolError({
+          code: "FILE_NOT_FOUND",
+          message: `"${filePath}" does not exist.`,
+          retryable: true,
+          hint: "Use fs_list to find files or fs_write to create a new file.",
+          details: { filePath }
+        });
+      }
+      const currentContent = fs2.readFileSync(fullPath, "utf-8");
+      if (context.filesReadHash) {
+        const savedHash = context.filesReadHash.get(filePath);
+        const currentHash = computeHash(currentContent);
+        if (savedHash && savedHash !== currentHash) {
+          return toolError({
+            code: "FILE_CHANGED_SINCE_READ",
+            message: `File was modified since you last read it (possibly by a linter, formatter, or another tool).`,
+            retryable: true,
+            hint: `Call fs_read(path="${filePath}") to get the current content, then retry the edit with updated line numbers.`,
+            details: { filePath, startLine, endLine }
+          });
+        }
+      }
+      const allLines = currentContent.split("\n");
+      const totalLines = allLines.length;
+      if (startLine < 1 || startLine > totalLines) {
+        return toolError({
+          code: "INVALID_START_LINE",
+          message: `startLine ${startLine} is out of range (file has ${totalLines} lines).`,
+          retryable: true,
+          hint: `Use startLine between 1 and ${totalLines}.`,
+          details: { filePath, startLine, totalLines }
+        });
+      }
+      if (endLine < startLine || endLine > totalLines) {
+        return toolError({
+          code: "INVALID_END_LINE",
+          message: `endLine ${endLine} is invalid (startLine=${startLine}, file has ${totalLines} lines).`,
+          retryable: true,
+          hint: `Use endLine between ${startLine} and ${totalLines}.`,
+          details: { filePath, startLine, endLine, totalLines }
+        });
+      }
+      const beforeLines = allLines.slice(0, startLine - 1);
+      const afterLines = allLines.slice(endLine);
+      const newLines = newContent ? newContent.split("\n") : [];
+      const patchedContent = [...beforeLines, ...newLines, ...afterLines].join("\n");
+      const removedCount = endLine - startLine + 1;
+      const addedCount = newLines.length;
+      const netChange = addedCount - removedCount;
+      fs2.writeFileSync(fullPath, patchedContent, "utf-8");
+      const patchedHash = computeHash(patchedContent);
+      context.filesRead?.add(filePath);
+      context.filesReadHash?.set(filePath, patchedHash);
+      let action;
+      if (addedCount === 0) {
+        action = `Deleted ${removedCount} line(s)`;
+      } else if (removedCount === addedCount) {
+        action = `Replaced ${removedCount} line(s)`;
+      } else if (netChange > 0) {
+        action = `Replaced ${removedCount} line(s) with ${addedCount} line(s) (+${netChange})`;
+      } else {
+        action = `Replaced ${removedCount} line(s) with ${addedCount} line(s) (${netChange})`;
+      }
+      return {
+        success: true,
+        output: `${action} in ${filePath}
+Lines ${startLine}-${endLine} \u2192 ${addedCount} new line(s)
+File now has ${beforeLines.length + newLines.length + afterLines.length} lines (was ${totalLines})`,
+        metadata: {
+          filePath,
+          startLine,
+          endLine,
+          linesRemoved: removedCount,
+          linesAdded: addedCount,
+          netChange,
+          totalLinesBefore: totalLines,
+          totalLinesAfter: beforeLines.length + newLines.length + afterLines.length,
+          // Consumed by ChangeTrackingMiddleware
+          changeSnapshot: {
+            operation: "patch",
+            beforeContent: currentContent,
+            afterContent: patchedContent,
+            startLine,
+            endLine,
+            linesAdded: addedCount,
+            linesRemoved: removedCount
+          }
+        }
+      };
+    }
+  };
+}
+function createFsReplaceTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "fs_replace",
+        description: `PREFERRED tool for editing existing files. Finds exact text and replaces it \u2014 only sends the diff, not the whole file. You must fs_read the file first. Use the smallest match text that uniquely identifies the target \u2014 usually 2-4 lines is enough. The match must appear exactly once (unless replace_all=true). If multiple matches, add more surrounding context to make it unique.`,
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "File path relative to working directory"
+            },
+            match: {
+              type: "string",
+              description: "Exact text to find in the file (copy from fs_read output)"
+            },
+            replacement: {
+              type: "string",
+              description: "Text to replace the match with"
+            },
+            replace_all: {
+              type: "boolean",
+              description: "Replace all occurrences (default: false \u2014 requires unique match)"
+            }
+          },
+          required: ["path", "match", "replacement"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const filePath = input.path;
+      const match = input.match;
+      const replacement = input.replacement;
+      const replaceAll = input.replace_all || false;
+      const pathValidation = validatePath(context.workingDir, filePath);
+      if (!pathValidation.valid) {
+        return toolError({
+          code: "PATH_VALIDATION_FAILED",
+          message: pathValidation.error || "Invalid path",
+          retryable: false,
+          hint: "Use a path inside working directory.",
+          details: { filePath, workingDir: context.workingDir }
+        });
+      }
+      const fullPath = pathValidation.resolved;
+      if (context.filesRead && !context.filesRead.has(filePath)) {
+        return toolError({
+          code: "CANNOT_EDIT_UNREAD_FILE",
+          message: "File has not been read yet. You must read a file before editing it.",
+          retryable: true,
+          hint: `Call fs_read(path="${filePath}") to read the file first, then retry this edit.`,
+          details: { filePath }
+        });
+      }
+      if (!fs2.existsSync(fullPath)) {
+        return toolError({
+          code: "FILE_NOT_FOUND",
+          message: `"${filePath}" does not exist.`,
+          retryable: true,
+          hint: "Use fs_list to find files or fs_write to create a new file.",
+          details: { filePath }
+        });
+      }
+      const currentContent = fs2.readFileSync(fullPath, "utf-8");
+      if (context.filesReadHash) {
+        const savedHash = context.filesReadHash.get(filePath);
+        const currentHash = computeHash(currentContent);
+        if (savedHash && savedHash !== currentHash) {
+          return toolError({
+            code: "FILE_CHANGED_SINCE_READ",
+            message: "File was modified since you last read it (possibly by a linter, formatter, or another tool).",
+            retryable: true,
+            hint: `Call fs_read(path="${filePath}") to get the current content, then retry the edit.`,
+            details: { filePath }
+          });
+        }
+      }
+      if (match === replacement) {
+        return toolError({
+          code: "NO_CHANGE",
+          message: "The match and replacement text are identical. No changes needed.",
+          retryable: false,
+          hint: "Provide different replacement text, or skip this edit if no change is needed.",
+          details: { filePath }
+        });
+      }
+      if (!currentContent.includes(match)) {
+        return toolError({
+          code: "MATCH_NOT_FOUND",
+          message: "The match text was not found in the file.",
+          retryable: true,
+          hint: `Call fs_read(path="${filePath}") to see the current file content, then copy the exact text you want to replace.`,
+          details: { filePath, matchLength: match.length }
+        });
+      }
+      const occurrences = currentContent.split(match).length - 1;
+      if (occurrences > 1 && !replaceAll) {
+        return toolError({
+          code: "AMBIGUOUS_MATCH",
+          message: `Found ${occurrences} occurrences of the match text, but replace_all is false.`,
+          retryable: true,
+          hint: `Include more surrounding context in the match text to make it unique (only 1 occurrence), or set replace_all=true to replace all ${occurrences} occurrences.`,
+          details: { filePath, occurrences }
+        });
+      }
+      const updatedContent = replaceAll ? currentContent.replaceAll(match, replacement) : currentContent.replace(match, replacement);
+      fs2.writeFileSync(fullPath, updatedContent, "utf-8");
+      const newHash = computeHash(updatedContent);
+      context.filesRead?.add(filePath);
+      context.filesReadHash?.set(filePath, newHash);
+      const matchLines = match.split("\n").length;
+      const replacementLines = replacement.split("\n").length;
+      const netChange = replacementLines - matchLines;
+      const action = replaceAll ? `Replaced ${occurrences} occurrence(s)` : "Replaced 1 occurrence";
+      return {
+        success: true,
+        output: `${action} in ${filePath}
+Match: ${matchLines} line(s) \u2192 Replacement: ${replacementLines} line(s) (${netChange >= 0 ? "+" : ""}${netChange})
+File now has ${updatedContent.split("\n").length} lines`,
+        metadata: {
+          filePath,
+          occurrences: replaceAll ? occurrences : 1,
+          matchLines,
+          replacementLines,
+          netChange,
+          totalLinesAfter: updatedContent.split("\n").length,
+          changeSnapshot: {
+            operation: "replace",
+            beforeContent: currentContent,
+            afterContent: updatedContent,
+            match,
+            replacement,
+            replaceAll
+          }
+        }
+      };
+    }
+  };
+}
+function createFsListTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "fs_list",
+        description: `List files and directories at a path. Non-recursive by default. IMPORTANT: node_modules/, dist/, .git/, build/, .next/ are hidden by default \u2014 they contain no useful source code. Use include_ignored=true only if you specifically need to inspect build artifacts.`,
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: 'Directory path relative to working directory (default: ".")'
+            },
+            recursive: {
+              type: "boolean",
+              description: "Include subdirectories recursively (default: false, max depth: 3)"
+            },
+            include_ignored: {
+              type: "boolean",
+              description: "Include normally-hidden dirs: node_modules, dist, build, .next, .git (default: false). Only use when you explicitly need to inspect build artifacts or dependencies."
+            },
+            offset: {
+              type: "number",
+              description: "Result offset for pagination (default: 0)"
+            },
+            limit: {
+              type: "number",
+              description: `Result limit per page (default: ${DEFAULT_LIST_LIMIT}, max: ${MAX_LIST_LIMIT})`
+            }
+          }
+        }
+      }
+    },
+    executor: async (input) => {
+      const dirPath = input.path || ".";
+      const recursive = input.recursive || false;
+      const includeIgnored = input.include_ignored || false;
+      const { offset, limit } = normalizeListWindow(input);
+      const IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", ".next", ".git", ".pnpm", ".cache", "coverage", "__pycache__"]);
+      const pathValidation = validatePath(context.workingDir, dirPath);
+      if (!pathValidation.valid) {
+        return toolError({
+          code: "PATH_VALIDATION_FAILED",
+          message: pathValidation.error || "Invalid path",
+          retryable: false,
+          hint: "Use a path inside working directory.",
+          details: { path: dirPath, workingDir: context.workingDir }
+        });
+      }
+      const fullPath = pathValidation.resolved;
+      if (!fs2.existsSync(fullPath)) {
+        const suggestion = suggestDirectory(context.workingDir, dirPath);
+        return toolError({
+          code: "DIRECTORY_NOT_FOUND",
+          message: `"${dirPath}" does not exist.`,
+          retryable: true,
+          hint: suggestion ? `Did you mean "${suggestion}"?` : "Use fs_list on parent directory to discover valid paths.",
+          details: { path: dirPath, workingDir: context.workingDir }
+        });
+      }
+      const stats = fs2.statSync(fullPath);
+      if (!stats.isDirectory()) {
+        return toolError({
+          code: "NOT_A_DIRECTORY",
+          message: `"${dirPath}" is a file, not a directory.`,
+          retryable: false,
+          hint: "Use fs_read for files or provide a directory path.",
+          details: { path: dirPath }
+        });
+      }
+      const entries = fs2.readdirSync(fullPath, { withFileTypes: true });
+      const files = entries.filter((e) => e.isFile()).map((e) => e.name).filter((name) => !name.startsWith(".")).sort();
+      const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).filter((name) => {
+        if (name.startsWith(".")) {
+          return false;
+        }
+        if (!includeIgnored && IGNORED_DIRS.has(name)) {
+          return false;
+        }
+        return true;
+      }).sort();
+      const hiddenDirCount = includeIgnored ? 0 : entries.filter((e) => e.isDirectory() && IGNORED_DIRS.has(e.name)).length;
+      const combinedEntries = [
+        ...dirs.map((name) => ({ type: "dir", name })),
+        ...files.map((name) => ({ type: "file", name }))
+      ];
+      const pageEntries = combinedEntries.slice(offset, offset + limit);
+      const hasMore = offset + limit < combinedEntries.length;
+      const nextOffset = hasMore ? offset + limit : null;
+      const pageDirs = pageEntries.filter((entry) => entry.type === "dir");
+      const pageFiles = pageEntries.filter((entry) => entry.type === "file");
+      const ignoredNote = hiddenDirCount > 0 ? `[${hiddenDirCount} ignored dir(s) hidden: node_modules/dist/build/etc \u2014 use include_ignored=true to show]` : "";
+      const outputParts = [
+        `\u{1F4C1} ${dirPath === "." ? "Working Directory" : dirPath} (showing ${pageEntries.length}/${combinedEntries.length}, offset=${offset}, limit=${limit})`,
+        ignoredNote,
+        ""
+      ].filter(Boolean);
+      if (pageDirs.length > 0) {
+        outputParts.push(`Directories (${dirs.length}):`);
+        for (const d of pageDirs) {
+          outputParts.push(`  \u{1F4C1} ${d.name}/`);
+        }
+        outputParts.push("");
+      }
+      if (pageFiles.length > 0) {
+        outputParts.push(`Files (${files.length}):`);
+        for (const f of pageFiles) {
+          const filePath = path4.join(fullPath, f.name);
+          const fileStats = fs2.statSync(filePath);
+          outputParts.push(`  \u{1F4C4} ${f.name} (${formatSize(fileStats.size)})`);
+        }
+      }
+      if (combinedEntries.length === 0) {
+        outputParts.push("(empty directory)");
+      }
+      if (recursive && dirs.length > 0) {
+        outputParts.push("");
+        outputParts.push("\u2500".repeat(40));
+        outputParts.push("Recursive structure (depth 2):");
+        for (const d of dirs.slice(0, 10)) {
+          outputParts.push(`
+\u{1F4C1} ${d}/`);
+          const subPath = path4.join(fullPath, d);
+          try {
+            const subEntries = fs2.readdirSync(subPath, { withFileTypes: true });
+            const subDirs = subEntries.filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules");
+            const subFiles = subEntries.filter((e) => e.isFile() && !e.name.startsWith("."));
+            for (const sd of subDirs.slice(0, 5)) {
+              outputParts.push(`  \u{1F4C1} ${sd.name}/`);
+            }
+            if (subDirs.length > 5) {
+              outputParts.push(`  ... and ${subDirs.length - 5} more directories`);
+            }
+            for (const sf of subFiles.slice(0, 5)) {
+              outputParts.push(`  \u{1F4C4} ${sf.name}`);
+            }
+            if (subFiles.length > 5) {
+              outputParts.push(`  ... and ${subFiles.length - 5} more files`);
+            }
+          } catch {
+            outputParts.push("  (unable to read)");
+          }
+        }
+        if (dirs.length > 10) {
+          outputParts.push(`
+... and ${dirs.length - 10} more directories`);
+        }
+      }
+      const rawOutput = outputParts.join("\n");
+      const continuationHint = hasMore ? `Next page: fs_list(path="${dirPath}", offset=${nextOffset}, limit=${limit})` : "";
+      return {
+        success: true,
+        output: trimOutput(rawOutput, MAX_OUTPUT_CHARS, continuationHint),
+        metadata: {
+          path: dirPath,
+          directoryCount: dirs.length,
+          fileCount: files.length,
+          directories: dirs,
+          files,
+          totalEntries: combinedEntries.length,
+          offset,
+          limit,
+          hasMore,
+          nextOffset
+        }
+      };
+    }
+  };
+}
+var MAX_FILE_SIZE2 = MASS_REPLACE_CONFIG.maxFileSize;
+var MAX_FILES = MASS_REPLACE_CONFIG.maxFiles;
+function createMassReplaceTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "mass_replace",
+        description: `Batch find-and-replace across multiple files. Supports literal and regex modes. Use dryRun=true to preview. Changes are tracked for rollback.`,
+        parameters: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: "Text or regex pattern to search for. For regex mode, use JavaScript regex syntax (without / delimiters)."
+            },
+            replacement: {
+              type: "string",
+              description: "Replacement text. In regex mode, can use $1, $2 for capture groups."
+            },
+            scope: {
+              type: "string",
+              description: 'REQUIRED: Directory to limit search scope (e.g., "src", "packages/agent-core", "."). Prevents accidental project-wide changes. Use "." for current directory only.'
+            },
+            files: {
+              type: "string",
+              description: 'Glob pattern for files within scope (e.g., "**/*.ts", "*.js"). Combined with scope to form full path.'
+            },
+            mode: {
+              type: "string",
+              enum: ["literal", "regex"],
+              description: 'Replacement mode: "literal" for exact string match (default), "regex" for regex patterns.'
+            },
+            dryRun: {
+              type: "boolean",
+              description: "Preview changes without applying them. Shows what would be changed."
+            },
+            caseInsensitive: {
+              type: "boolean",
+              description: 'For regex mode: make pattern case-insensitive (adds "i" flag).'
+            }
+          },
+          required: ["pattern", "replacement", "scope", "files"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const pattern = String(input.pattern || "");
+      const replacement = String(input.replacement || "");
+      const scope = String(input.scope || "");
+      const filesPattern = String(input.files || "");
+      const mode = String(input.mode || "literal");
+      const dryRun = Boolean(input.dryRun);
+      const caseInsensitive = Boolean(input.caseInsensitive);
+      if (!pattern) {
+        return {
+          success: false,
+          error: 'VALIDATION_ERROR: "pattern" is required.'
+        };
+      }
+      if (!scope) {
+        return {
+          success: false,
+          error: 'VALIDATION_ERROR: "scope" is required. Specify directory to limit search (e.g., "src", "packages/agent-core", or "." for current dir).'
+        };
+      }
+      if (!filesPattern) {
+        return {
+          success: false,
+          error: 'VALIDATION_ERROR: "files" glob pattern is required.'
+        };
+      }
+      if (mode !== "literal" && mode !== "regex") {
+        return {
+          success: false,
+          error: `VALIDATION_ERROR: Invalid mode "${mode}". Must be "literal" or "regex".`
+        };
+      }
+      try {
+        const scopeValidation = validatePath(context.workingDir, scope);
+        if (!scopeValidation.valid) {
+          return {
+            success: false,
+            error: scopeValidation.error
+          };
+        }
+        const scopePath = scopeValidation.resolved;
+        if (!fs2.existsSync(scopePath)) {
+          return {
+            success: false,
+            error: `SCOPE_ERROR: Directory "${scope}" does not exist.`
+          };
+        }
+        if (!fs2.statSync(scopePath).isDirectory()) {
+          return {
+            success: false,
+            error: `SCOPE_ERROR: "${scope}" is not a directory.`
+          };
+        }
+        const matches = await glob(filesPattern, {
+          cwd: scopePath,
+          nodir: true,
+          absolute: false,
+          ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**"]
+        });
+        if (matches.length === 0) {
+          return {
+            success: true,
+            output: `No files matched pattern: "${filesPattern}" in scope: "${scope}"`,
+            metadata: {
+              filesMatched: 0,
+              filesChanged: 0,
+              totalReplacements: 0,
+              scope
+            }
+          };
+        }
+        if (matches.length > MAX_FILES) {
+          return {
+            success: false,
+            error: `TOO_MANY_FILES: Pattern matched ${matches.length} files, but limit is ${MAX_FILES}. Use more specific glob pattern.`
+          };
+        }
+        let searchPattern;
+        if (mode === "regex") {
+          const flags = caseInsensitive ? "gi" : "g";
+          try {
+            searchPattern = new RegExp(pattern, flags);
+          } catch (err) {
+            return {
+              success: false,
+              error: `REGEX_ERROR: Invalid regex pattern "${pattern}": ${err.message}`
+            };
+          }
+        } else {
+          const escapedPattern = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+          const flags = caseInsensitive ? "gi" : "g";
+          searchPattern = new RegExp(escapedPattern, flags);
+        }
+        const results = [];
+        let totalReplacements = 0;
+        let filesChanged = 0;
+        for (const relPath of matches) {
+          const scopedPath = path4.join(scope, relPath);
+          const validation = validatePath(context.workingDir, scopedPath);
+          if (!validation.valid) {
+            return {
+              success: false,
+              error: validation.error
+            };
+          }
+          const fullPath = validation.resolved;
+          if (!fs2.existsSync(fullPath)) {
+            continue;
+          }
+          const stats = fs2.statSync(fullPath);
+          if (stats.size > MAX_FILE_SIZE2) {
+            results.push({
+              file: scopedPath,
+              replacements: 0,
+              preview: `[SKIPPED: File too large (${(stats.size / 1024).toFixed(1)} KB > ${MAX_FILE_SIZE2 / 1024} KB)]`
+            });
+            continue;
+          }
+          const beforeContent = fs2.readFileSync(fullPath, "utf-8");
+          const afterContent = beforeContent.replace(searchPattern, replacement);
+          if (beforeContent === afterContent) {
+            continue;
+          }
+          const matchCount = (beforeContent.match(searchPattern) || []).length;
+          totalReplacements += matchCount;
+          filesChanged++;
+          if (dryRun) {
+            const lines = beforeContent.split("\n");
+            const changedLines = [];
+            let previewCount = 0;
+            for (let i = 0; i < lines.length && previewCount < 3; i++) {
+              const line = lines[i];
+              if (searchPattern.test(line)) {
+                const newLine = line.replace(searchPattern, replacement);
+                changedLines.push(`  Line ${i + 1}:`);
+                changedLines.push(`    - ${line.slice(0, 80)}`);
+                changedLines.push(`    + ${newLine.slice(0, 80)}`);
+                previewCount++;
+              }
+            }
+            results.push({
+              file: scopedPath,
+              replacements: matchCount,
+              preview: changedLines.join("\n")
+            });
+          } else {
+            fs2.writeFileSync(fullPath, afterContent, "utf-8");
+            const hash = crypto.createHash("sha256").update(afterContent, "utf-8").digest("hex");
+            context.filesRead?.add(scopedPath);
+            context.filesReadHash?.set(scopedPath, hash);
+            results.push({
+              file: scopedPath,
+              replacements: matchCount
+            });
+          }
+        }
+        const summary = dryRun ? `[DRY RUN] Would replace in ${filesChanged} file(s):` : `\u2705 Replaced in ${filesChanged} file(s):`;
+        const details = results.map((r) => {
+          if (r.preview) {
+            return `${r.file}: ${r.replacements} replacement(s)
+${r.preview}`;
+          }
+          return `${r.file}: ${r.replacements} replacement(s)`;
+        }).join("\n\n");
+        const output = `${summary}
+
+${details}
+
+Scope: ${scope}
+Total replacements: ${totalReplacements}
+Files matched: ${matches.length}
+Files changed: ${filesChanged}` + (dryRun ? "\n\n\u26A0\uFE0F DRY RUN: No files were modified. Remove dryRun=true to apply changes." : "");
+        return {
+          success: true,
+          output,
+          metadata: {
+            scope,
+            filesMatched: matches.length,
+            filesChanged,
+            totalReplacements,
+            dryRun,
+            pattern,
+            replacement,
+            mode
+          }
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: `EXECUTION_ERROR: ${error.message}`
+        };
+      }
+    }
+  };
+}
+function trimOutput2(output, maxChars, continuationHint) {
+  if (output.length <= maxChars) {
+    return output;
+  }
+  const trimmed = output.slice(0, maxChars);
+  return `${trimmed}
+
+\u26A0\uFE0F OUTPUT TRIMMED (${output.length.toLocaleString()} chars \u2192 ${maxChars.toLocaleString()} shown)
+${continuationHint}`;
+}
+var DEFAULT_EXCLUDES = SEARCH_CONFIG.defaultExcludes;
+var MAX_OUTPUT_CHARS2 = SEARCH_CONFIG.maxOutputChars;
+function buildFindExcludes(excludes) {
+  return excludes.map((d) => `! -path "*/${d}/*"`).join(" ");
+}
+function buildGrepExcludes(excludes) {
+  return excludes.map((d) => `--exclude-dir=${d}`).join(" ");
+}
+function toSingleQuoted(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+var SEARCH_TIMEOUT_MS = SEARCH_CONFIG.timeoutMs;
+var SEARCH_MAX_BUFFER = SEARCH_CONFIG.maxBuffer;
+var DEFAULT_RESULT_LIMIT = SEARCH_CONFIG.defaultResultLimit;
+var MAX_RESULT_LIMIT = SEARCH_CONFIG.maxResultLimit;
+function validateDirectory(workingDir, directory) {
+  const fullPath = path4.resolve(workingDir, directory);
+  if (fs2.existsSync(fullPath) && fs2.statSync(fullPath).isDirectory()) {
+    return null;
+  }
+  let hint = "";
+  try {
+    const entries = fs2.readdirSync(workingDir, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules").map((e) => e.name).sort();
+    if (dirs.length > 0) {
+      hint = `
+Available directories: ${dirs.slice(0, 15).join(", ")}${dirs.length > 15 ? ` ... (${dirs.length} total)` : ""}`;
+    }
+  } catch {
+  }
+  const suggestion = suggestDirectory(workingDir, directory);
+  const didYouMean = suggestion ? `
+Did you mean: "${suggestion}"?` : "";
+  return `Directory "${directory}" not found (resolved to ${fullPath}). Use "." to search from project root.${hint}${didYouMean}`;
+}
+function normalizeOffsetLimit2(input) {
+  return normalizeOffsetLimit(input, { defaultLimit: DEFAULT_RESULT_LIMIT, maxLimit: MAX_RESULT_LIMIT });
+}
+function paginate(items, offset, limit) {
+  const page = items.slice(offset, offset + limit);
+  const hasMore = offset + limit < items.length;
+  return {
+    page,
+    hasMore,
+    nextOffset: hasMore ? offset + limit : null
+  };
+}
+function createGlobSearchTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "glob_search",
+        description: `Find files by name pattern (glob). Pattern matches filename only \u2014 use "*.ts" or "user.ts", not bare words. IMPORTANT: node_modules/, dist/, build/, .git/ are excluded by default \u2014 they contain no source code. Omit directory to search the entire working directory. Returns up to ${DEFAULT_RESULT_LIMIT} results.`,
+        parameters: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: 'Glob pattern (e.g., "*.ts", "user.ts", "*user*.ts")'
+            },
+            directory: {
+              type: "string",
+              description: "Directory to search in (default: working directory root). Narrow to a subfolder when you already know the scope."
+            },
+            exclude: {
+              type: "array",
+              items: { type: "string" },
+              description: "Extra directories to exclude on top of defaults (node_modules, dist, .git, build, .next, .kb, .pnpm, coverage are always excluded). Rarely needed."
+            },
+            offset: {
+              type: "number",
+              description: "Result offset for pagination (default: 0)"
+            },
+            limit: {
+              type: "number",
+              description: `Max results per page (default: ${DEFAULT_RESULT_LIMIT}, max: ${MAX_RESULT_LIMIT})`
+            }
+          },
+          required: ["pattern"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const pattern = input.pattern;
+      const directory = input.directory || ".";
+      const extra = input.exclude;
+      const excludes = extra && extra.length > 0 ? [.../* @__PURE__ */ new Set([...DEFAULT_EXCLUDES, ...extra])] : DEFAULT_EXCLUDES;
+      const { offset, limit } = normalizeOffsetLimit2(input);
+      try {
+        const fullPath = path4.resolve(context.workingDir, directory);
+        const dirError = validateDirectory(context.workingDir, directory);
+        if (dirError) {
+          return { success: true, output: dirError };
+        }
+        const windowSize = Math.min(2e3, Math.max(500, offset + limit));
+        const cmd = `find "${fullPath}" -type f -iname "${pattern}" ${buildFindExcludes(excludes)} | head -${windowSize}`;
+        const output = execSync(cmd, {
+          cwd: context.workingDir,
+          encoding: "utf-8",
+          maxBuffer: SEARCH_MAX_BUFFER,
+          timeout: SEARCH_TIMEOUT_MS
+        });
+        const files = output.trim().split("\n").filter(Boolean).map((f) => path4.relative(context.workingDir, f));
+        if (files.length === 0) {
+          return {
+            success: true,
+            output: `No files found matching pattern: ${pattern} in ${directory === "." ? "project root" : directory}. Note: glob_search matches filenames only. To search file contents, use grep_search. To find class/function definitions, use find_definition.`
+          };
+        }
+        const page = paginate(files, offset, limit);
+        const excludeNote = `[Excluded: ${DEFAULT_EXCLUDES.join(", ")}${extra && extra.length > 0 ? ` + ${extra.join(", ")}` : ""}]`;
+        const result = [
+          `Found ${files.length} file(s) matching "${pattern}" in "${directory}" (showing ${page.page.length}, offset=${offset}, limit=${limit})`,
+          excludeNote,
+          "",
+          ...page.page.map((f) => `  ${f}`),
+          page.hasMore ? "" : ""
+        ].filter((s) => s !== void 0).join("\n");
+        const continuationHint = page.hasMore ? `Next page: glob_search(pattern="${pattern}", directory="${directory}", offset=${page.nextOffset}, limit=${limit})` : "";
+        return {
+          success: true,
+          output: trimOutput2(result, MAX_OUTPUT_CHARS2, continuationHint),
+          metadata: {
+            totalMatches: files.length,
+            offset,
+            limit,
+            hasMore: page.hasMore,
+            nextOffset: page.nextOffset
+          }
+        };
+      } catch (error) {
+        if (error instanceof Error && "killed" in error && error.killed) {
+          return toolError({
+            code: "SEARCH_TIMEOUT",
+            message: `Glob search timed out after ${SEARCH_TIMEOUT_MS / 1e3}s.`,
+            retryable: true,
+            hint: "Narrow directory/pattern or lower limit.",
+            details: { directory, pattern, timeoutMs: SEARCH_TIMEOUT_MS }
+          });
+        }
+        if (error.code === "ENOBUFS") {
+          return toolError({
+            code: "SEARCH_BUFFER_OVERFLOW",
+            message: "Search output exceeded buffer.",
+            retryable: true,
+            hint: "Narrow directory/pattern or reduce limit.",
+            details: { directory, pattern, offset, limit }
+          });
+        }
+        return toolError({
+          code: "SEARCH_FAILED",
+          message: `Glob search failed: ${error instanceof Error ? error.message : String(error)}`,
+          retryable: true,
+          hint: "Check pattern syntax and directory.",
+          details: { directory, pattern }
+        });
+      }
+    }
+  };
+}
+function createGrepSearchTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "grep_search",
+        description: `Search for text/regex in files. Returns file:line matches. IMPORTANT: node_modules/, dist/, build/ excluded by default. Omit directory to search the entire working directory. Add filePattern (e.g. "*.ts") to limit to specific file types. Returns up to ${DEFAULT_RESULT_LIMIT} matches.`,
+        parameters: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: "Text pattern to search for (can be regex)"
+            },
+            directory: {
+              type: "string",
+              description: "Directory to search in (default: working directory root). Narrow to a subfolder when you already know the scope."
+            },
+            filePattern: {
+              type: "string",
+              description: 'Filter by file extension (e.g., "*.ts", "*.md"). STRONGLY RECOMMENDED: always set this to avoid scanning binary/generated files.'
+            },
+            exclude: {
+              type: "array",
+              items: { type: "string" },
+              description: "Extra directories to exclude on top of defaults (node_modules, dist, .git, build, .next, .kb, .pnpm, coverage are always excluded). Rarely needed."
+            },
+            mode: {
+              type: "string",
+              enum: ["auto", "regex", "literal"],
+              description: "Search mode: auto (default), regex, or literal"
+            },
+            offset: {
+              type: "number",
+              description: "Result offset for pagination (default: 0)"
+            },
+            limit: {
+              type: "number",
+              description: `Max matches per page (default: ${DEFAULT_RESULT_LIMIT}, max: ${MAX_RESULT_LIMIT})`
+            }
+          },
+          required: ["pattern"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const pattern = input.pattern;
+      const directory = input.directory || ".";
+      const filePattern = input.filePattern;
+      const extra = input.exclude;
+      const excludes = extra && extra.length > 0 ? [.../* @__PURE__ */ new Set([...DEFAULT_EXCLUDES, ...extra])] : DEFAULT_EXCLUDES;
+      const mode = (input.mode || "auto").toLowerCase();
+      const { offset, limit } = normalizeOffsetLimit2(input);
+      try {
+        const fullPath = path4.resolve(context.workingDir, directory);
+        const dirError = validateDirectory(context.workingDir, directory);
+        if (dirError) {
+          return { success: true, output: dirError };
+        }
+        const windowSize = Math.min(2e3, Math.max(500, offset + limit));
+        const regexCmd = `grep -rIn ${toSingleQuoted(pattern)} "${fullPath}" ${buildGrepExcludes(excludes)}${filePattern ? ` --include="${filePattern}"` : ""}`;
+        const literalCmd = `grep -rIFn ${toSingleQuoted(pattern)} "${fullPath}" ${buildGrepExcludes(excludes)}${filePattern ? ` --include="${filePattern}"` : ""}`;
+        let cmd = mode === "literal" ? literalCmd : regexCmd;
+        cmd += ` | head -${windowSize}`;
+        let output = "";
+        let usedLiteralFallback = false;
+        try {
+          output = execSync(cmd, {
+            cwd: context.workingDir,
+            encoding: "utf-8",
+            maxBuffer: SEARCH_MAX_BUFFER,
+            timeout: SEARCH_TIMEOUT_MS
+          });
+        } catch (error) {
+          const status = error.status;
+          const stderrRaw = error.stderr;
+          const stderr = typeof stderrRaw === "string" ? stderrRaw : stderrRaw instanceof Buffer ? stderrRaw.toString("utf-8") : "";
+          const looksLikeInvalidRegex = status === 2 && /(unbalanced|parentheses|invalid regular expression|regular expression)/i.test(stderr);
+          if (!looksLikeInvalidRegex) {
+            throw error;
+          }
+          usedLiteralFallback = true;
+          if (mode === "regex") {
+            throw error;
+          }
+          output = execSync(`${literalCmd} | head -${windowSize}`, {
+            cwd: context.workingDir,
+            encoding: "utf-8",
+            maxBuffer: SEARCH_MAX_BUFFER,
+            timeout: SEARCH_TIMEOUT_MS
+          });
+        }
+        const lines = output.trim().split("\n").filter(Boolean);
+        if (lines.length === 0) {
+          return {
+            success: true,
+            output: `No matches found for "${pattern}" in ${directory === "." ? "project root" : directory}.${filePattern ? "" : ' Try adding filePattern (e.g. "*.ts") to narrow the search.'}`
+          };
+        }
+        const page = paginate(lines, offset, limit);
+        const excludeNote = `[Excluded: ${DEFAULT_EXCLUDES.join(", ")}${extra && extra.length > 0 ? ` + ${extra.join(", ")}` : ""}]`;
+        const result = [
+          `Found ${lines.length} match(es) for "${pattern}" in "${directory}"${filePattern ? ` (${filePattern})` : ""}${usedLiteralFallback ? " (literal fallback)" : ""} (showing ${page.page.length}, offset=${offset}, limit=${limit})`,
+          excludeNote,
+          "",
+          ...page.page.map((line) => {
+            const match = line.match(/^(.+?):(\d+):(.+)$/);
+            if (match) {
+              const [, filePath, lineNum, content] = match;
+              const relPath = path4.relative(context.workingDir, filePath);
+              return `  ${relPath}:${lineNum}
+    ${content.trim()}`;
+            }
+            return `  ${line}`;
+          }),
+          page.hasMore ? "" : ""
+        ].filter((s) => s !== void 0).join("\n");
+        const continuationHint = page.hasMore ? `Next page: grep_search(pattern="${pattern}", directory="${directory}", offset=${page.nextOffset}, limit=${limit})` : "";
+        return {
+          success: true,
+          output: trimOutput2(result, MAX_OUTPUT_CHARS2, continuationHint),
+          metadata: {
+            totalMatches: lines.length,
+            offset,
+            limit,
+            hasMore: page.hasMore,
+            nextOffset: page.nextOffset,
+            modeUsed: usedLiteralFallback ? "literal" : mode === "auto" ? "regex" : mode
+          }
+        };
+      } catch (error) {
+        if (error instanceof Error && "status" in error && error.status === 1) {
+          return {
+            success: true,
+            output: `No matches found for "${pattern}" in ${directory === "." ? "project root" : directory}.${filePattern ? "" : ' Try adding filePattern (e.g. "*.ts") to narrow the search.'}`
+          };
+        }
+        if (error instanceof Error && "killed" in error && error.killed) {
+          return toolError({
+            code: "SEARCH_TIMEOUT",
+            message: `Grep search timed out after ${SEARCH_TIMEOUT_MS / 1e3}s.`,
+            retryable: true,
+            hint: "Narrow directory, add filePattern, or lower limit.",
+            details: { directory, pattern, timeoutMs: SEARCH_TIMEOUT_MS }
+          });
+        }
+        if (error.code === "ENOBUFS") {
+          return toolError({
+            code: "SEARCH_BUFFER_OVERFLOW",
+            message: "Search output exceeded buffer.",
+            retryable: true,
+            hint: "Narrow directory, add filePattern, or reduce limit.",
+            details: { directory, pattern, filePattern, offset, limit, mode }
+          });
+        }
+        return toolError({
+          code: "SEARCH_FAILED",
+          message: `Grep search failed: ${error instanceof Error ? error.message : String(error)}`,
+          retryable: true,
+          hint: 'Try mode="literal" for special characters, or narrow directory.',
+          details: { directory, pattern, filePattern, mode }
+        });
+      }
+    }
+  };
+}
+function createListFilesTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "list_files",
+        description: "List files and directories at a path. Good for exploring what exists.",
+        parameters: {
+          type: "object",
+          properties: {
+            directory: {
+              type: "string",
+              description: 'Directory to list (default: "." for current directory)'
+            },
+            recursive: {
+              type: "boolean",
+              description: "Include subdirectories (default: false)"
+            },
+            offset: {
+              type: "number",
+              description: "Result offset for pagination (default: 0)"
+            },
+            limit: {
+              type: "number",
+              description: `Max results per page (default: ${DEFAULT_RESULT_LIMIT}, max: ${MAX_RESULT_LIMIT})`
+            }
+          }
+        }
+      }
+    },
+    executor: async (input) => {
+      const directory = input.directory || ".";
+      const recursive = input.recursive || false;
+      const { offset, limit } = normalizeOffsetLimit2(input);
+      try {
+        const fullPath = path4.resolve(context.workingDir, directory);
+        let cmd;
+        if (recursive) {
+          cmd = `find "${fullPath}" -type f             ! -path "*/node_modules/*"             ! -path "*/.git/*"             ! -path "*/dist/*"             ! -path "*/.kb/*"             | head -100`;
+        } else {
+          cmd = `ls -la "${fullPath}" 2>/dev/null || echo "Directory not found"`;
+        }
+        const output = execSync(cmd, {
+          cwd: context.workingDir,
+          encoding: "utf-8",
+          maxBuffer: 1024 * 1024
+        });
+        if (recursive) {
+          const files = output.trim().split("\n").filter(Boolean).map((f) => path4.relative(context.workingDir, f));
+          const page = paginate(files, offset, limit);
+          return {
+            success: true,
+            output: files.length > 0 ? `Files in ${directory} (recursive, showing ${page.page.length}/${files.length}, offset=${offset}, limit=${limit}):
+
+${page.page.map((f) => `  ${f}`).join("\n")}${page.hasMore ? `
+
+Next page: list_files(directory="${directory}", recursive=true, offset=${page.nextOffset}, limit=${limit})` : ""}` : `No files found in ${directory}`,
+            metadata: {
+              totalMatches: files.length,
+              offset,
+              limit,
+              hasMore: page.hasMore,
+              nextOffset: page.nextOffset
+            }
+          };
+        }
+        return {
+          success: true,
+          output: `Contents of ${directory}:
+
+${output}`
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: `List files failed: ${error instanceof Error ? error.message : String(error)}`
+        };
+      }
+    }
+  };
+}
+function createFindDefinitionTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "find_definition",
+        description: "Find where a symbol (class, function, interface, type, etc.) is defined. Works with any language. Uses project root as default directory, which works well for monorepos with nested packages.",
+        parameters: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name of the symbol to find (class, function, interface, type, struct, etc.)"
+            },
+            directory: {
+              type: "string",
+              description: 'Directory to search in (default: ".")'
+            },
+            filePattern: {
+              type: "string",
+              description: 'File pattern to search (e.g., "*.cs" for C#, "*.py" for Python). If not specified, searches all source files.'
+            }
+          },
+          required: ["name"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const name = input.name;
+      const directory = input.directory || ".";
+      const filePattern = input.filePattern;
+      try {
+        const fullPath = path4.resolve(context.workingDir, directory);
+        const dirError = validateDirectory(context.workingDir, directory);
+        if (dirError) {
+          return { success: true, output: dirError };
+        }
+        const patterns = [
+          // Common across languages
+          `class ${name}`,
+          `interface ${name}`,
+          `struct ${name}`,
+          `enum ${name}`,
+          // TypeScript/JavaScript
+          `function ${name}`,
+          `const ${name}`,
+          `let ${name}`,
+          `var ${name}`,
+          `type ${name}`,
+          `export.*${name}`,
+          // Python
+          `def ${name}`,
+          // C#/Java
+          `public.*${name}`,
+          `private.*${name}`,
+          `protected.*${name}`,
+          `static.*${name}`,
+          // Go
+          `func ${name}`,
+          `func \\(.*\\) ${name}`,
+          // Rust
+          `fn ${name}`,
+          `impl ${name}`,
+          `trait ${name}`,
+          `mod ${name}`
+        ];
+        let includeFlags = "";
+        if (filePattern) {
+          includeFlags = `--include="${filePattern}"`;
+        } else {
+          includeFlags = toRgIncludes(ALL_SOURCE_EXTENSIONS);
+        }
+        const cmd = `grep -rn -E "(${patterns.join("|")})" "${fullPath}"           ${includeFlags}           ${buildGrepExcludes(DEFAULT_EXCLUDES)}           --exclude-dir=bin           --exclude-dir=obj           --exclude-dir=target           | head -30`;
+        const output = execSync(cmd, {
+          cwd: context.workingDir,
+          encoding: "utf-8",
+          maxBuffer: 1024 * 1024,
+          timeout: SEARCH_TIMEOUT_MS
+        });
+        const lines = output.trim().split("\n").filter(Boolean);
+        if (lines.length === 0) {
+          return {
+            success: true,
+            output: `No definition found for "${name}" in ${directory === "." ? "project root" : directory}. Try: grep_search for text matching, or glob_search with "*${name.toLowerCase()}*" for filename matching.`
+          };
+        }
+        const result = lines.map((line) => {
+          const match = line.match(/^(.+?):(\d+):(.+)$/);
+          if (match) {
+            const [, filePath, lineNum, content] = match;
+            const relPath = path4.relative(context.workingDir, filePath);
+            return `${relPath}:${lineNum}
+  ${content.trim()}`;
+          }
+          return line;
+        });
+        return {
+          success: true,
+          output: `Found definition(s) for "${name}":
+
+${result.join("\n\n")}`
+        };
+      } catch (error) {
+        if (error instanceof Error && "status" in error && error.status === 1) {
+          return {
+            success: true,
+            output: `No definition found for "${name}" in ${directory === "." ? "project root" : directory}. Try: grep_search for text matching, or glob_search with "*${name.toLowerCase()}*" for filename matching.`
+          };
+        }
+        if (error instanceof Error && "killed" in error && error.killed) {
+          return {
+            success: false,
+            error: `Find definition timed out after ${SEARCH_TIMEOUT_MS / 1e3}s. Try specifying a narrower directory.`
+          };
+        }
+        return {
+          success: false,
+          error: `Find definition failed: ${error instanceof Error ? error.message : String(error)}`
+        };
+      }
+    }
+  };
+}
+function createCodeStatsTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "code_stats",
+        description: "Get line counts and file counts by extension for a directory scope (not single-file line counts).",
+        parameters: {
+          type: "object",
+          properties: {
+            directory: {
+              type: "string",
+              description: 'Directory to analyze (default: "."). If a file path is provided by mistake, use its parent directory.'
+            },
+            extensions: {
+              type: "string",
+              description: 'Comma-separated list of extensions to count (e.g., "ts,tsx,js" or "cs,csproj" or "py"). If not specified, counts all source files.'
+            },
+            offset: {
+              type: "number",
+              description: "Offset for extension summary rows (default: 0)"
+            },
+            limit: {
+              type: "number",
+              description: `Rows per page for extension summary (default: ${DEFAULT_RESULT_LIMIT}, max: ${MAX_RESULT_LIMIT})`
+            }
+          }
+        }
+      }
+    },
+    executor: async (input) => {
+      const directory = input.directory || ".";
+      const extensionsInput = input.extensions;
+      const { offset, limit } = normalizeOffsetLimit2(input);
+      try {
+        const fullPath = path4.resolve(context.workingDir, directory);
+        const dirError = validateDirectory(context.workingDir, directory);
+        if (dirError) {
+          return { success: true, output: dirError };
+        }
+        let extFilter;
+        if (extensionsInput) {
+          const exts = extensionsInput.split(",").map((e) => e.trim());
+          extFilter = toFindNames(exts);
+        } else {
+          extFilter = toFindNames(ALL_SOURCE_EXTENSIONS);
+        }
+        const totalCmd = `find "${fullPath}" -type f \\( ${extFilter} \\)           ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/.git/*"           ! -path "*/bin/*" ! -path "*/obj/*" ! -path "*/target/*" ! -path "*/__pycache__/*"           -exec wc -l {} + 2>/dev/null | tail -1 || echo "0 total"`;
+        const totalOutput = execSync(totalCmd, {
+          cwd: context.workingDir,
+          encoding: "utf-8"
+        }).trim();
+        const countByExtCmd = `find "${fullPath}" -type f \\( ${extFilter} \\)           ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/.git/*"           ! -path "*/bin/*" ! -path "*/obj/*" ! -path "*/target/*" ! -path "*/__pycache__/*"           | sed 's/.*\\.//' | sort | uniq -c | sort -rn | head -200`;
+        const countByExt = execSync(countByExtCmd, {
+          cwd: context.workingDir,
+          encoding: "utf-8"
+        }).trim().split("\n").filter(Boolean);
+        const fileCountCmd = `find "${fullPath}" -type f \\( ${extFilter} \\)           ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/.git/*"           ! -path "*/bin/*" ! -path "*/obj/*" ! -path "*/target/*" ! -path "*/__pycache__/*" | wc -l`;
+        const fileCount = execSync(fileCountCmd, {
+          cwd: context.workingDir,
+          encoding: "utf-8"
+        }).trim();
+        const page = paginate(countByExt, offset, limit);
+        return {
+          success: true,
+          output: `Code statistics for directory ${directory}:
+
+Total lines: ${totalOutput}
+Total files: ${fileCount}
+
+Files by extension (showing ${page.page.length}/${countByExt.length}, offset=${offset}, limit=${limit}):
+${page.page.join("\n")}${page.hasMore ? `
+
+Next page: code_stats(directory="${directory}", offset=${page.nextOffset}, limit=${limit})` : ""}
+
+Note: This is directory-level aggregate. For a single file line count, use fs_read on that file and rely on metadata.totalLines.`,
+          metadata: {
+            totalExtensionRows: countByExt.length,
+            offset,
+            limit,
+            hasMore: page.hasMore,
+            nextOffset: page.nextOffset
+          }
+        };
+      } catch (error) {
+        return toolError({
+          code: "CODE_STATS_FAILED",
+          message: `Code stats failed: ${error instanceof Error ? error.message : String(error)}`,
+          retryable: true,
+          hint: "Narrow directory or provide extensions.",
+          details: { directory, extensions: extensionsInput }
+        });
+      }
+    }
+  };
+}
+function getMemoryPath(context) {
+  const memoryDir = path4.join(context.workingDir, ".kb", "memory", "shared");
+  if (!fs2.existsSync(memoryDir)) {
+    fs2.mkdirSync(memoryDir, { recursive: true });
+  }
+  return path4.join(memoryDir, "memory.json");
+}
+function loadSharedMemory(context) {
+  const memoryPath = getMemoryPath(context);
+  const defaultMemory = {
+    preferences: [],
+    constraints: [],
+    sessions: [],
+    projectContext: {
+      name: "",
+      description: "",
+      technologies: [],
+      structure: ""
+    }
+  };
+  if (!fs2.existsSync(memoryPath)) {
+    return defaultMemory;
+  }
+  try {
+    const content = fs2.readFileSync(memoryPath, "utf-8");
+    const parsed = JSON.parse(content);
+    if (parsed.facts && Array.isArray(parsed.facts)) {
+      const preferences = parsed.facts.filter((f) => f.type === "user_preference");
+      const constraints = parsed.facts.filter((f) => f.type === "constraint");
+      return {
+        preferences,
+        constraints,
+        sessions: parsed.sessions || [],
+        projectContext: parsed.projectContext || defaultMemory.projectContext
+      };
+    }
+    return {
+      ...defaultMemory,
+      ...parsed
+    };
+  } catch {
+    return defaultMemory;
+  }
+}
+function saveSharedMemory(context, memory) {
+  const memoryPath = getMemoryPath(context);
+  fs2.writeFileSync(memoryPath, JSON.stringify(memory, null, 2), "utf-8");
+}
+async function loadCanonicalSessionMemory(context) {
+  if (!context.sessionMemory) {
+    return { constraints: [], corrections: [] };
+  }
+  const kernel = await context.sessionMemory.loadKernelState();
+  if (!kernel) {
+    return { constraints: [], corrections: [] };
+  }
+  return {
+    constraints: kernel.constraints,
+    corrections: kernel.memory.corrections.map((item) => item.content)
+  };
+}
+function createMemoryGetTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "memory_get",
+        description: "Get stored user preferences, project constraints, and session history.",
+        parameters: {
+          type: "object",
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "Optional session ID to get specific session context"
+            }
+          }
+        }
+      }
+    },
+    executor: async (input) => {
+      const sessionId = input.sessionId;
+      const memory = loadSharedMemory(context);
+      const canonicalSession = await loadCanonicalSessionMemory(context);
+      const preferencesText = memory.preferences.length > 0 ? memory.preferences.map((p) => `- ${p.content}`).join("\n") : "No preferences set";
+      const constraintsText = memory.constraints.length > 0 ? memory.constraints.map((c) => `- ${c.content}`).join("\n") : "No constraints set";
+      const sessionConstraintsText = canonicalSession.constraints.length > 0 ? canonicalSession.constraints.map((item) => `- ${item}`).join("\n") : "No session constraints set";
+      const sessionCorrectionsText = canonicalSession.corrections.length > 0 ? canonicalSession.corrections.map((item) => `- ${item}`).join("\n") : "No session corrections recorded";
+      const sessions = sessionId ? memory.sessions.filter((s) => s.sessionId === sessionId) : memory.sessions.slice(-5);
+      const sessionInfo = sessions.map((s) => {
+        const tasks = s.tasks.join(", ");
+        return `Session ${s.sessionId} (${s.timestamp}):
+  Tasks: ${tasks}
+  Learnings: ${s.learnings}`;
+      }).join("\n\n");
+      const output = [
+        "=== Shared Memory ===",
+        "",
+        "## \u{1F464} User Preferences (persistent)",
+        preferencesText,
+        "",
+        "## \u{1F6AB} Constraints (persistent)",
+        constraintsText,
+        "",
+        "## Session Constraints (canonical)",
+        sessionConstraintsText,
+        "",
+        "## Session Corrections (canonical)",
+        sessionCorrectionsText,
+        "",
+        "## Project Context",
+        `Name: ${memory.projectContext.name || "Unknown"}`,
+        `Description: ${memory.projectContext.description || "N/A"}`,
+        `Technologies: ${memory.projectContext.technologies.join(", ") || "N/A"}`,
+        "",
+        "## Session History",
+        sessionInfo || "No sessions yet",
+        "",
+        "---",
+        "Note: Corrections, findings, and blockers are stored in session memory."
+      ].join("\n");
+      return {
+        success: true,
+        output
+      };
+    }
+  };
+}
+function createMemoryPreferenceTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "memory_preference",
+        description: "Store a persistent user preference (coding style, tool choices, etc.).",
+        parameters: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: 'The preference to store (e.g., "Always use TypeScript strict mode")'
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: 'Optional tags for categorization (e.g., ["typescript", "style"])'
+            }
+          },
+          required: ["content"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const content = input.content;
+      const tags = input.tags;
+      const memory = loadSharedMemory(context);
+      const preference = {
+        content,
+        category: "user_input",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: "user_preference",
+        metadata: {
+          importance: 0.9,
+          source: "user",
+          scope: "project",
+          tags
+        }
+      };
+      memory.preferences.push(preference);
+      if (memory.preferences.length > 50) {
+        memory.preferences = memory.preferences.slice(-50);
+      }
+      saveSharedMemory(context, memory);
+      return {
+        success: true,
+        output: `\u{1F464} Preference stored: ${content}`
+      };
+    }
+  };
+}
+function createMemoryConstraintTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "memory_constraint",
+        description: "Store a persistent project constraint or rule. Use this for durable project-wide rules, not session-only instructions.",
+        parameters: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: 'The constraint (e.g., "Do not modify files in /legacy/ directory")'
+            }
+          },
+          required: ["content"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const content = input.content;
+      if (context.sessionMemory) {
+        await context.sessionMemory.recordConstraint(content);
+      }
+      const memory = loadSharedMemory(context);
+      const constraint = {
+        content,
+        category: "project_rules",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: "constraint",
+        metadata: {
+          importance: 1,
+          source: "user",
+          scope: "project"
+        }
+      };
+      memory.constraints.push(constraint);
+      if (memory.constraints.length > 50) {
+        memory.constraints = memory.constraints.slice(-50);
+      }
+      saveSharedMemory(context, memory);
+      return {
+        success: true,
+        output: `\u{1F6AB} Constraint stored: ${content}`
+      };
+    }
+  };
+}
+function getSessionMemoryPath(context, sessionId) {
+  const id = sessionId || `session-${Date.now()}`;
+  const sessionDir = path4.join(context.workingDir, ".kb", "memory", id);
+  if (!fs2.existsSync(sessionDir)) {
+    fs2.mkdirSync(sessionDir, { recursive: true });
+  }
+  return sessionDir;
+}
+function saveToSession(context, entry, sessionId) {
+  const sessionDir = getSessionMemoryPath(context, sessionId);
+  const entryId = `mem-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+  const filePath = path4.join(sessionDir, `${entryId}.json`);
+  fs2.writeFileSync(filePath, JSON.stringify({ ...entry, id: entryId }, null, 2), "utf-8");
+}
+function createMemoryCorrectionTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "memory_correction",
+        description: "Store a user correction for the current session. Use this immediately after the user corrects you or changes active instructions. Set constraint=true if the correction should remain an active session constraint.",
+        parameters: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: 'The correction (e.g., "AuthService is in packages/auth/, not src/services/")'
+            },
+            supersedes: {
+              type: "string",
+              description: "Optional: what this correction replaces"
+            },
+            invalidates: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional: assumption IDs invalidated by this correction"
+            },
+            constraint: {
+              type: "boolean",
+              description: "Set true if this correction should also become an active session constraint"
+            },
+            sessionId: {
+              type: "string",
+              description: "Optional: session ID (defaults to current timestamp-based session)"
+            }
+          },
+          required: ["content"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const content = input.content;
+      const supersedes = input.supersedes;
+      const invalidates = Array.isArray(input.invalidates) ? input.invalidates.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
+      const asConstraint = input.constraint === true;
+      const sessionId = input.sessionId;
+      if (context.sessionMemory) {
+        await context.sessionMemory.recordCorrection({
+          content,
+          invalidates,
+          asConstraint
+        });
+      }
+      const correction = {
+        content,
+        category: "user_input",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: "user_correction",
+        metadata: {
+          importance: 1,
+          source: "user",
+          supersedes,
+          scope: "session"
+        }
+      };
+      saveToSession(context, correction, sessionId);
+      const supersedesInfo = supersedes ? ` (replaces: ${supersedes})` : "";
+      const constraintInfo = asConstraint ? " [active session constraint]" : "";
+      return {
+        success: true,
+        output: `\u26A0\uFE0F Correction stored in session${supersedesInfo}${constraintInfo}: ${content}`
+      };
+    }
+  };
+}
+function createMemoryFindingTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "memory_finding",
+        description: "Store a codebase finding with confidence level (session-scoped).",
+        parameters: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: 'The finding (e.g., "All services use Repository pattern")'
+            },
+            confidence: {
+              type: "number",
+              description: "Confidence level 0-1 (e.g., 0.9 for high confidence)"
+            },
+            sources: {
+              type: "array",
+              items: { type: "string" },
+              description: "Source files that support this finding"
+            },
+            sessionId: {
+              type: "string",
+              description: "Optional: session ID"
+            }
+          },
+          required: ["content", "confidence"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const content = input.content;
+      const confidence = input.confidence;
+      const sources = input.sources;
+      const sessionId = input.sessionId;
+      const finding = {
+        content,
+        category: "learning",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: "finding",
+        metadata: {
+          importance: confidence,
+          confidence,
+          source: "agent",
+          tags: sources,
+          scope: "session"
+        }
+      };
+      saveToSession(context, finding, sessionId);
+      return {
+        success: true,
+        output: `\u{1F50D} Finding stored (confidence: ${(confidence * 100).toFixed(0)}%): ${content}`
+      };
+    }
+  };
+}
+function createMemoryBlockerTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "memory_blocker",
+        description: "Store a blocker that prevents progress (session-scoped).",
+        parameters: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: 'The blocker (e.g., "Cannot find database config. Need DATABASE_URL")'
+            },
+            taskId: {
+              type: "string",
+              description: "Optional: related task ID"
+            },
+            sessionId: {
+              type: "string",
+              description: "Optional: session ID"
+            }
+          },
+          required: ["content"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const content = input.content;
+      const taskId = input.taskId;
+      const sessionId = input.sessionId;
+      const blocker = {
+        content,
+        category: "agent_state",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: "blocker",
+        metadata: {
+          importance: 1,
+          source: "agent",
+          taskId,
+          scope: "session"
+        }
+      };
+      saveToSession(context, blocker, sessionId);
+      return {
+        success: true,
+        output: `\u{1F6D1} Blocker stored: ${content}`
+      };
+    }
+  };
+}
+function createSessionSaveTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "session_save",
+        description: "Save session summary and learnings to persistent memory.",
+        parameters: {
+          type: "object",
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "Session identifier"
+            },
+            tasks: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of tasks completed in this session"
+            },
+            learnings: {
+              type: "string",
+              description: "Summary of what was learned or discovered"
+            }
+          },
+          required: ["sessionId", "tasks", "learnings"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const sessionId = input.sessionId;
+      const tasks = input.tasks;
+      const learnings = input.learnings;
+      const memory = loadSharedMemory(context);
+      const session = {
+        sessionId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        tasks,
+        learnings
+      };
+      memory.sessions.push(session);
+      if (memory.sessions.length > 50) {
+        memory.sessions = memory.sessions.slice(-50);
+      }
+      saveSharedMemory(context, memory);
+      return {
+        success: true,
+        output: `Session ${sessionId} saved with ${tasks.length} task(s)`
+      };
+    }
+  };
+}
+
+// src/tools/memory/archive-recall.ts
+function createArchiveRecallTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "archive_recall",
+        description: "Retrieve full content from previously-read files or tool outputs WITHOUT re-reading them. Use this to recall file contents, grep results, or any tool output from earlier iterations. Specify exactly one query mode: file_path, keyword, list_files, tool_name, or iteration.",
+        parameters: {
+          type: "object",
+          properties: {
+            file_path: {
+              type: "string",
+              description: "Recall the last read of this file (full content)"
+            },
+            keyword: {
+              type: "string",
+              description: "Search across all archived outputs for this keyword"
+            },
+            list_files: {
+              type: "boolean",
+              description: "List all file paths that have been archived"
+            },
+            tool_name: {
+              type: "string",
+              description: "Recall recent outputs of a specific tool (e.g., grep_search)"
+            },
+            iteration: {
+              type: "number",
+              description: "Recall all tool outputs from a specific iteration number"
+            },
+            limit: {
+              type: "number",
+              description: "Maximum number of results to return (default: 5)"
+            }
+          }
+        }
+      }
+    },
+    executor: async (input) => {
+      const archive = context.archiveMemory;
+      if (!archive) {
+        return {
+          success: false,
+          error: "Archive memory not available. This tool requires the two-tier memory system."
+        };
+      }
+      const limit = input.limit || 5;
+      if (input.file_path) {
+        const filePath = input.file_path;
+        const entry = archive.recallByFilePath(filePath);
+        if (!entry) {
+          return {
+            success: false,
+            output: `File not found in archive: ${filePath}
+
+Archived files:
+${archive.getArchivedFilePaths().join("\n") || "(none)"}`
+          };
+        }
+        return {
+          success: true,
+          output: `[Archive] File: ${filePath} (read in iteration ${entry.iteration} via ${entry.toolName})
+
+${entry.fullOutput}`
+        };
+      }
+      if (input.keyword) {
+        const keyword = input.keyword;
+        const results = archive.search(keyword, limit);
+        if (results.length === 0) {
+          return {
+            success: true,
+            output: `No archived outputs contain "${keyword}"`
+          };
+        }
+        const formatted = results.map((r, i) => {
+          const fileInfo = r.filePath ? ` (file: ${r.filePath})` : "";
+          const preview = r.fullOutput.length > 500 ? r.fullOutput.substring(0, 500) + `
+... (${r.fullOutput.length} chars total)` : r.fullOutput;
+          return `--- Result ${i + 1}: ${r.toolName} @ iter ${r.iteration}${fileInfo} ---
+${preview}`;
+        }).join("\n\n");
+        return {
+          success: true,
+          output: `[Archive] Found ${results.length} result(s) for "${keyword}":
+
+${formatted}`
+        };
+      }
+      if (input.list_files) {
+        const files = archive.getArchivedFilePaths();
+        if (files.length === 0) {
+          return { success: true, output: "No files archived yet." };
+        }
+        return {
+          success: true,
+          output: `[Archive] ${files.length} file(s) archived:
+${files.join("\n")}`
+        };
+      }
+      if (input.tool_name) {
+        const toolName = input.tool_name;
+        const results = archive.recallByToolName(toolName, limit);
+        if (results.length === 0) {
+          return {
+            success: true,
+            output: `No archived outputs for tool "${toolName}"`
+          };
+        }
+        const formatted = results.map((r, i) => {
+          const fileInfo = r.filePath ? ` (file: ${r.filePath})` : "";
+          const preview = r.fullOutput.length > 500 ? r.fullOutput.substring(0, 500) + `
+... (${r.fullOutput.length} chars total)` : r.fullOutput;
+          return `--- ${toolName} #${i + 1} @ iter ${r.iteration}${fileInfo} ---
+${preview}`;
+        }).join("\n\n");
+        return {
+          success: true,
+          output: `[Archive] ${results.length} output(s) from "${toolName}":
+
+${formatted}`
+        };
+      }
+      if (input.iteration !== void 0) {
+        const iteration = input.iteration;
+        const results = archive.recallByIteration(iteration);
+        if (results.length === 0) {
+          return {
+            success: true,
+            output: `No archived outputs from iteration ${iteration}`
+          };
+        }
+        const formatted = results.map((r, i) => {
+          const fileInfo = r.filePath ? ` (file: ${r.filePath})` : "";
+          const preview = r.fullOutput.length > 500 ? r.fullOutput.substring(0, 500) + `
+... (${r.fullOutput.length} chars total)` : r.fullOutput;
+          return `--- ${r.toolName} #${i + 1}${fileInfo} ---
+${preview}`;
+        }).join("\n\n");
+        return {
+          success: true,
+          output: `[Archive] ${results.length} output(s) from iteration ${iteration}:
+
+${formatted}`
+        };
+      }
+      return {
+        success: false,
+        error: "Specify at least one query parameter: file_path, keyword, list_files, tool_name, or iteration"
+      };
+    }
+  };
+}
+
+// src/tools/planning/todo.ts
+var todoLists = /* @__PURE__ */ new Map();
+var TODO_CACHE_PREFIX = TODO_CONFIG.cachePrefix;
+var TODO_CACHE_TTL_MS = TODO_CONFIG.cacheTtlMs;
+function getTodoCacheKey(sessionId) {
+  return `${TODO_CACHE_PREFIX}${sessionId}`;
+}
+async function loadTodoList(context, sessionId) {
+  if (context.cache) {
+    const cached = await context.cache.get(getTodoCacheKey(sessionId));
+    if (cached) {
+      todoLists.set(sessionId, cached);
+      return cached;
+    }
+  }
+  return todoLists.get(sessionId) ?? null;
+}
+async function persistTodoList(context, todoList) {
+  todoLists.set(todoList.sessionId, todoList);
+  if (context.cache) {
+    await context.cache.set(getTodoCacheKey(todoList.sessionId), todoList, TODO_CACHE_TTL_MS);
+  }
+}
+function resolveTodoItem(todoList, sessionId, itemId) {
+  const direct = todoList.items.find((i) => i.id === itemId);
+  if (direct) {
+    return direct;
+  }
+  const asIndex = Number(itemId);
+  if (Number.isFinite(asIndex) && asIndex >= 1) {
+    const indexed = todoList.items.find((i) => i.id === `${sessionId}-${Math.floor(asIndex)}`);
+    if (indexed) {
+      return indexed;
+    }
+  }
+  const normalized = itemId.trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  const descriptionMatches = todoList.items.filter(
+    (i) => i.description.toLowerCase().includes(normalized)
+  );
+  if (descriptionMatches.length === 1) {
+    return descriptionMatches[0];
+  }
+  return null;
+}
+function createTodoCreateTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "todo_create",
+        description: "Create a TODO list to track task progress. Optional - use if helpful for planning complex tasks.",
+        parameters: {
+          type: "object",
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "Session identifier to associate TODO list"
+            },
+            items: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  description: {
+                    type: "string",
+                    description: "Task description"
+                  },
+                  priority: {
+                    type: "string",
+                    enum: ["low", "medium", "high"],
+                    description: "Task priority"
+                  }
+                },
+                required: ["description"]
+              },
+              description: "List of tasks"
+            }
+          },
+          required: ["sessionId", "items"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const sessionId = input.sessionId;
+      const items = input.items;
+      const todoItems = items.map((item, index) => ({
+        id: `${sessionId}-${index + 1}`,
+        description: item.description,
+        status: "pending",
+        priority: item.priority || "medium",
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+      const todoList = {
+        sessionId,
+        items: todoItems,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await persistTodoList(context, todoList);
+      const output = [
+        `TODO list created for session: ${sessionId}`,
+        "",
+        ...todoItems.map(
+          (item, i) => `${i + 1}. [ ] ${item.description} (${item.priority})`
+        )
+      ].join("\n");
+      return {
+        success: true,
+        output,
+        metadata: {
+          uiHint: "todo",
+          structured: { todoList }
+        }
+      };
+    }
+  };
+}
+function createTodoUpdateTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "todo_update",
+        description: "Update status of a TODO item. Use to mark tasks as in-progress or completed.",
+        parameters: {
+          type: "object",
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "Session identifier"
+            },
+            itemId: {
+              type: "string",
+              description: "TODO item ID to update"
+            },
+            status: {
+              type: "string",
+              enum: ["pending", "in-progress", "completed", "blocked"],
+              description: "New status"
+            },
+            notes: {
+              type: "string",
+              description: "Optional notes about the update"
+            }
+          },
+          required: ["sessionId", "itemId", "status"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const sessionId = input.sessionId;
+      const itemId = input.itemId;
+      const status = input.status;
+      const notes = input.notes;
+      const todoList = await loadTodoList(context, sessionId);
+      if (!todoList) {
+        return toolError({
+          code: "TODO_LIST_NOT_FOUND",
+          message: `No TODO list found for session: ${sessionId}`,
+          retryable: true,
+          hint: "Call todo_create first, then todo_update.",
+          details: { sessionId }
+        });
+      }
+      const item = resolveTodoItem(todoList, sessionId, itemId);
+      if (!item) {
+        return toolError({
+          code: "TODO_ITEM_NOT_FOUND",
+          message: `TODO item not found: ${itemId}`,
+          retryable: true,
+          hint: "Use todo_get to list valid item IDs, then retry with exact itemId.",
+          details: {
+            sessionId,
+            itemId,
+            knownIds: todoList.items.map((i) => i.id)
+          }
+        });
+      }
+      item.status = status;
+      item.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      if (notes) {
+        item.notes = notes;
+      }
+      todoList.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await persistTodoList(context, todoList);
+      const statusIcon = status === "completed" ? "\u2713" : status === "in-progress" ? "\u23F3" : status === "blocked" ? "\u{1F6AB}" : " ";
+      const updatedList = await loadTodoList(context, sessionId);
+      return {
+        success: true,
+        output: `[${statusIcon}] ${item.description} \u2192 ${status}${notes ? `
+  Note: ${notes}` : ""}`,
+        metadata: {
+          uiHint: "todo",
+          structured: { todoList: updatedList }
+        }
+      };
+    }
+  };
+}
+function createTodoGetTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "todo_get",
+        description: "Get current TODO list with task statuses. Use to check progress.",
+        parameters: {
+          type: "object",
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "Session identifier"
+            }
+          },
+          required: ["sessionId"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const sessionId = input.sessionId;
+      const todoList = await loadTodoList(context, sessionId);
+      if (!todoList) {
+        return toolError({
+          code: "TODO_LIST_NOT_FOUND",
+          message: `No TODO list found for session: ${sessionId}`,
+          retryable: true,
+          hint: "Create a TODO list with todo_create before calling todo_get.",
+          details: { sessionId }
+        });
+      }
+      const completed = todoList.items.filter((i) => i.status === "completed").length;
+      const total = todoList.items.length;
+      const output = [
+        `TODO List for ${sessionId} (${completed}/${total} completed)`,
+        "",
+        ...todoList.items.map((item) => {
+          const icon = item.status === "completed" ? "\u2713" : item.status === "in-progress" ? "\u23F3" : item.status === "blocked" ? "\u{1F6AB}" : " ";
+          return `[${icon}] ${item.description} (${item.priority})${item.notes ? `
+    ${item.notes}` : ""}`;
+        })
+      ].join("\n");
+      return {
+        success: true,
+        output,
+        metadata: {
+          uiHint: "todo",
+          structured: { todoList }
+        }
+      };
+    }
+  };
+}
+var EVAL_SYSTEM_PROMPT = `You are a plan quality evaluator. Evaluate implementation plans written by AI agents.
+
+You will receive the original user task and the plan markdown.
+
+Score the plan on four dimensions (0.0\u20131.0 each):
+
+**specificity** (weight 0.30)
+- Does the plan reference real file paths from the codebase?
+- Are function names, class names, or line numbers mentioned where relevant?
+- For simple tasks (1-2 files), mentioning those files is sufficient for a high score.
+- For complex tasks (many files), more paths are expected.
+
+**actionability** (weight 0.35)
+- Can each step be executed without guessing what to do?
+- Steps should contain: what file to edit, what to change, or what command to run.
+- "Edit X to add Y" is actionable. "Update the configuration" is not.
+
+**completeness** (weight 0.15)
+- Does the plan have: task description, steps, verification?
+- Are sections substantive (not just headings)?
+
+**verification** (weight 0.20)
+- Does the plan include concrete commands to verify correctness?
+- At least one build or test command expected.
+
+Respond in EXACTLY this format (no other text before or after):
+SCORE: 0.XX
+SPECIFICITY: 0.XX
+ACTIONABILITY: 0.XX
+COMPLETENESS: 0.XX
+VERIFICATION: 0.XX
+FEEDBACK:
+<One paragraph per dimension scoring below 0.7. Quote the weak part, explain the problem, give a fix example. If all dimensions \u2265 0.7, write "Plan meets quality threshold.">
+
+IMPORTANT: Only output the format above. Do NOT output tool calls, code blocks, or any other format.`;
+function buildEvalPrompt(task, planMarkdown) {
+  return `## Original user task
+
+${task}
+
+## Plan to evaluate
+
+${planMarkdown}`;
+}
+var PASS_THRESHOLD = 0.55;
+function formatResult(raw, tier) {
+  const lines = raw.split("\n");
+  const get = (key) => {
+    const line = lines.find((l) => l.toUpperCase().startsWith(key.toUpperCase() + ":"));
+    return line?.slice(line.indexOf(":") + 1).trim() ?? "";
+  };
+  const specificity = parseFloat(get("SPECIFICITY") || "0");
+  const actionability = parseFloat(get("ACTIONABILITY") || "0");
+  const completeness = parseFloat(get("COMPLETENESS") || "0");
+  const verification = parseFloat(get("VERIFICATION") || "0");
+  const composite = specificity * 0.3 + actionability * 0.35 + completeness * 0.15 + verification * 0.2;
+  const passed = composite >= PASS_THRESHOLD;
+  if (specificity === 0 && actionability === 0 && completeness === 0 && verification === 0) {
+    return [
+      `\u26A0\uFE0F EVAL_ERROR \u2014 LLM returned unparseable response (${tier} tier)`,
+      "",
+      "Raw response (first 300 chars):",
+      raw.slice(0, 300),
+      "",
+      "ACTION: Try again with a different tier, or call report() if you believe the plan is ready."
+    ].join("\n");
+  }
+  const feedbackIdx = raw.toUpperCase().indexOf("FEEDBACK:");
+  const feedback = feedbackIdx >= 0 ? raw.slice(feedbackIdx + "FEEDBACK:".length).trim() : "";
+  const status = passed ? "\u2705 PASSED" : "\u274C FAILED";
+  const scoreBar = Math.round(composite * 10);
+  const bar = "\u2588".repeat(scoreBar) + "\u2591".repeat(10 - scoreBar);
+  return [
+    `${status} \u2014 score: ${composite.toFixed(2)} [${bar}] (threshold ${PASS_THRESHOLD}, ${tier} tier)`,
+    "",
+    `  specificity:   ${specificity.toFixed(2)}  (weight 0.30)`,
+    `  actionability: ${actionability.toFixed(2)}  (weight 0.35)`,
+    `  completeness:  ${completeness.toFixed(2)}  (weight 0.15)`,
+    `  verification:  ${verification.toFixed(2)}  (weight 0.20)`,
+    "",
+    ...feedback ? ["\u2500\u2500\u2500 Feedback \u2500\u2500\u2500", feedback, ""] : [],
+    passed ? "ACTION: Call report() with the plan \u2014 it is ready for user approval." : "ACTION: Revise the plan addressing the feedback above, then call plan_validate again.\n        After 3 failed validations, call ask_user() with the plan and this feedback."
+  ].join("\n");
+}
+function createPlanValidateTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "plan_validate",
+        description: `Evaluate a plan draft against quality criteria using an LLM judge.
+Returns pass/fail, per-dimension scores, and concrete actionable feedback on what to fix.
+Call this after writing a plan draft, before calling report().
+If it fails, revise the plan based on the feedback and call plan_validate again.
+After 3 consecutive failures, call ask_user() with the plan and the feedback to escalate to the human.`,
+        parameters: {
+          type: "object",
+          properties: {
+            task: {
+              type: "string",
+              description: "The original user task/request that the plan is supposed to address. Copied verbatim \u2014 the evaluator needs this to judge relevance."
+            },
+            plan_markdown: {
+              type: "string",
+              description: "The full plan markdown to evaluate."
+            },
+            tier: {
+              type: "string",
+              enum: ["small", "medium", "large"],
+              description: "LLM tier for evaluation. Default: small (fast, cheap). Use medium/large for complex plans or if small gives inconsistent results."
+            }
+          },
+          required: ["task", "plan_markdown"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const task = input.task;
+      const planMarkdown = input.plan_markdown;
+      const tier = input.tier ?? "small";
+      if (!task?.trim()) {
+        return { success: false, output: "ERROR: task is required \u2014 provide the original user request so the evaluator can judge plan relevance." };
+      }
+      if (!planMarkdown?.trim()) {
+        return { success: false, output: "ERROR: plan_markdown is required \u2014 provide the full plan markdown to evaluate." };
+      }
+      const llm = useLLM({ tier });
+      if (!llm) {
+        return { success: false, output: `ERROR: LLM tier "${tier}" is not available. Try a different tier or check platform configuration.` };
+      }
+      try {
+        const response = await llm.complete(buildEvalPrompt(task, planMarkdown), {
+          systemPrompt: EVAL_SYSTEM_PROMPT,
+          maxTokens: 1500
+        });
+        const formatted = formatResult(response.content, tier);
+        if (formatted.startsWith("\u2705 PASSED") || formatted.startsWith("\u26A0\uFE0F EVAL_ERROR")) {
+          context.planValidationPassed = true;
+        }
+        return { success: true, output: formatted };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, output: `ERROR: LLM evaluation failed: ${message}` };
+      }
+    }
+  };
+}
+function createPlanWriteTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "plan_write",
+        description: `Write or update the plan file for this session. The plan is saved to disk and survives context compaction. Use this to iteratively build your plan during exploration \u2014 write what you've learned so far, then continue exploring. The user can view the plan file at any time.`,
+        parameters: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: "Full markdown content for the plan file (replaces previous content)"
+            },
+            append: {
+              type: "string",
+              description: "Text to append to the existing plan (mutually exclusive with content)"
+            }
+          }
+        }
+      }
+    },
+    executor: async (input) => {
+      const content = input.content;
+      const append = input.append;
+      if (!content && !append) {
+        return toolError({
+          code: "MISSING_INPUT",
+          message: "Either content or append must be provided.",
+          retryable: false,
+          hint: "Provide content= for full replacement, or append= to add to existing plan."
+        });
+      }
+      if (content && append) {
+        return toolError({
+          code: "AMBIGUOUS_INPUT",
+          message: "Cannot use both content and append at the same time.",
+          retryable: false,
+          hint: "Use content= to replace the entire plan, or append= to add a section."
+        });
+      }
+      const sessionId = context.sessionId;
+      if (!sessionId) {
+        return toolError({
+          code: "NO_SESSION",
+          message: "No session ID available. Plan write requires an active session.",
+          retryable: false
+        });
+      }
+      const planDir = path4.join(context.workingDir, ".kb", "agents", "sessions", sessionId);
+      const planPath = path4.join(planDir, "plan.md");
+      if (!fs2.existsSync(planDir)) {
+        fs2.mkdirSync(planDir, { recursive: true });
+      }
+      let finalContent;
+      if (content) {
+        finalContent = content;
+      } else {
+        let existing = "";
+        try {
+          existing = fs2.readFileSync(planPath, "utf-8");
+        } catch {
+        }
+        finalContent = existing ? `${existing.trimEnd()}
+
+${append}` : append;
+      }
+      fs2.writeFileSync(planPath, finalContent, "utf-8");
+      const lineCount = finalContent.split("\n").length;
+      const mode = content ? "replaced" : "appended to";
+      return {
+        success: true,
+        output: `Plan ${mode}: ${planPath}
+Lines: ${lineCount}`,
+        metadata: {
+          planPath,
+          lineCount,
+          mode: content ? "replace" : "append"
+        }
+      };
+    }
+  };
+}
+var MAX_OUTPUT_CHARS3 = 8e3;
+function trimOutput3(output, label) {
+  if (output.length <= MAX_OUTPUT_CHARS3) {
+    return output;
+  }
+  const head = output.slice(0, MAX_OUTPUT_CHARS3 * 0.3);
+  const tail = output.slice(-Math.floor(MAX_OUTPUT_CHARS3 * 0.7));
+  return `${head}
+
+\u26A0\uFE0F ${label.toUpperCase()} TRIMMED (${output.length.toLocaleString()} chars, showing head+tail)
+\u{1F4A1} Pipe through grep/head/tail in your command to get focused output.
+
+...${tail}`;
+}
+function createShellExecTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "shell_exec",
+        description: "Execute a shell command and return output. Use for running builds, tests, git commands, etc. Commands run in the working directory.",
+        parameters: {
+          type: "object",
+          properties: {
+            command: {
+              type: "string",
+              description: "Shell command to execute"
+            },
+            cwd: {
+              type: "string",
+              description: "Optional working directory relative to agent workingDir. Use to run command in a specific package/subdirectory."
+            }
+          },
+          required: ["command"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const command = input.command;
+      const requestedCwd = typeof input.cwd === "string" ? input.cwd.trim() : "";
+      const resolvedCwd = requestedCwd ? path4__default.resolve(context.workingDir, requestedCwd) : context.workingDir;
+      const relative3 = path4__default.relative(context.workingDir, resolvedCwd);
+      if (relative3.startsWith("..") || path4__default.isAbsolute(relative3)) {
+        return toolError({
+          code: "INVALID_CWD",
+          message: `Invalid cwd "${requestedCwd}" - outside working directory.`,
+          retryable: false,
+          hint: "Use cwd relative to the agent working directory.",
+          details: { requestedCwd, resolvedCwd, workingDir: context.workingDir }
+        });
+      }
+      try {
+        const output = execSync(command, {
+          cwd: resolvedCwd,
+          encoding: "utf-8",
+          maxBuffer: SHELL_CONFIG.maxBuffer,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        const trimmed = trimOutput3(output || "", "stdout");
+        return {
+          success: true,
+          output: `[cwd: ${resolvedCwd}]
+${trimmed || "(command completed with no output)"}`,
+          metadata: {
+            cwd: resolvedCwd,
+            outputLength: output?.length ?? 0,
+            trimmed: (output?.length ?? 0) > MAX_OUTPUT_CHARS3
+          }
+        };
+      } catch (error) {
+        const stderr = error.stderr?.toString() || "";
+        const stdout = error.stdout?.toString() || "";
+        const exitCode = error.status ?? -1;
+        const commandText = typeof command === "string" ? command.trim() : "";
+        if (error.code === "ETIMEDOUT" || error.signal === "SIGTERM") {
+          return toolError({
+            code: "SHELL_TIMEOUT",
+            message: `Command timed out in ${resolvedCwd}`,
+            retryable: true,
+            hint: "Use a narrower command or run package-scoped command via cwd.",
+            details: { cwd: resolvedCwd, command: commandText, exitCode }
+          });
+        }
+        if (/command not found/i.test(stderr) || exitCode === 127) {
+          return toolError({
+            code: "COMMAND_NOT_FOUND",
+            message: `Command not found: ${commandText}`,
+            retryable: false,
+            hint: "Check binary name or ensure dependency is installed in this workspace.",
+            details: { cwd: resolvedCwd, command: commandText, exitCode }
+          });
+        }
+        if (/permission denied/i.test(stderr) || exitCode === 126) {
+          return toolError({
+            code: "PERMISSION_DENIED",
+            message: `Permission denied while executing command in ${resolvedCwd}`,
+            retryable: false,
+            hint: "Check file permissions and executable bits.",
+            details: { cwd: resolvedCwd, command: commandText, exitCode }
+          });
+        }
+        const stdoutDisplay = trimOutput3(stdout, "stdout");
+        const stderrDisplay = trimOutput3(stderr, "stderr");
+        return toolError({
+          code: "NON_ZERO_EXIT",
+          message: `Command failed with exit code ${exitCode}`,
+          retryable: true,
+          hint: "Inspect stderr/stdout below. Pipe output through grep/head/tail to narrow it down.",
+          details: {
+            cwd: resolvedCwd,
+            exitCode,
+            stdout: stdoutDisplay || void 0,
+            stderr: stderrDisplay || void 0
+          }
+        });
+      }
+    }
+  };
+}
+
+// src/tools/execution/async-tasks.ts
+function createTaskSubmitTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "task_submit",
+        description: "Start a sub-agent task in the background. Returns immediately with a task ID.\nThe sub-agent runs concurrently \u2014 you can continue working while it executes.\nUse task_status to check progress or task_collect to wait for results.",
+        parameters: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "Short description of the task (for tracking)."
+            },
+            task: {
+              type: "string",
+              description: "Detailed task description for the sub-agent."
+            },
+            preset: {
+              type: "string",
+              enum: ["research", "execute", "review"],
+              description: 'Sub-agent preset (default: "research").'
+            },
+            budgetPercent: {
+              type: "number",
+              description: "Percent of remaining budget to allocate (1-100, default: 20)."
+            }
+          },
+          required: ["description", "task"]
+        }
+      }
+    },
+    executor: async (input) => {
+      if (!context.taskManager) {
+        return {
+          success: false,
+          error: "Async task system not available. Task delegation is not enabled for this agent."
+        };
+      }
+      const description = input.description;
+      const task = input.task;
+      const presetId = input.preset ?? "research";
+      const preset = SUB_AGENT_PRESETS[presetId];
+      if (!preset) {
+        return { success: false, error: `Unknown preset: "${presetId}".` };
+      }
+      const budgetPercent = input.budgetPercent ?? 50;
+      const budgetFraction = Math.min(1, Math.max(0, budgetPercent / 100));
+      try {
+        const asyncTask = await context.taskManager.submit(description, {
+          task,
+          preset: presetId,
+          allowedTools: Array.from(preset.tools),
+          maxIterations: preset.maxIterations,
+          budgetFraction
+        });
+        return {
+          success: true,
+          output: `Task submitted: ${asyncTask.id}
+Description: ${description}
+Preset: ${presetId}
+Status: ${asyncTask.status}
+
+Use task_status("${asyncTask.id}") to check progress or task_collect("${asyncTask.id}") to wait for results.`
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: `Failed to submit task: ${error instanceof Error ? error.message : String(error)}`
+        };
+      }
+    }
+  };
+}
+function createTaskStatusTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "task_status",
+        description: "Check status of one or all async tasks.\nWithout taskId: returns all tasks.\nWith taskId: returns details for that specific task.",
+        parameters: {
+          type: "object",
+          properties: {
+            taskId: {
+              type: "string",
+              description: "Specific task ID to check (omit for all tasks)."
+            }
+          },
+          required: []
+        }
+      }
+    },
+    executor: async (input) => {
+      if (!context.taskManager) {
+        return { success: false, error: "Async task system not available." };
+      }
+      const taskId = input.taskId;
+      const result = context.taskManager.getStatus(taskId);
+      if (result === null) {
+        return { success: false, error: `Task not found: "${taskId}"` };
+      }
+      const tasks = Array.isArray(result) ? result : [result];
+      if (tasks.length === 0) {
+        return { success: true, output: "No async tasks." };
+      }
+      const lines = tasks.map((t) => {
+        const status = t.status === "completed" ? "\u2705" : t.status === "failed" ? "\u274C" : t.status === "running" ? "\u23F3" : "\u23F8\uFE0F";
+        let line = `${status} ${t.id}: ${t.description} [${t.status}]`;
+        if (t.result) {
+          line += `
+   Result: ${t.result.slice(0, 200)}`;
+        }
+        if (t.error) {
+          line += `
+   Error: ${t.error}`;
+        }
+        return line;
+      });
+      return { success: true, output: lines.join("\n") };
+    }
+  };
+}
+function createTaskCollectTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "task_collect",
+        description: "Wait for a specific async task to complete and return its full result.\nBlocks until the task is done. Use task_status to check without waiting.",
+        parameters: {
+          type: "object",
+          properties: {
+            taskId: {
+              type: "string",
+              description: "The task ID to wait for."
+            }
+          },
+          required: ["taskId"]
+        }
+      }
+    },
+    executor: async (input) => {
+      if (!context.taskManager) {
+        return { success: false, error: "Async task system not available." };
+      }
+      const taskId = input.taskId;
+      try {
+        const result = await context.taskManager.collect(taskId);
+        const status = result.success ? "completed successfully" : "failed";
+        const lines = [
+          `Task ${taskId} ${status} [preset=${result.preset}, ${result.iterations} iters, ${result.tokensUsed.toLocaleString()} tokens, ${(result.durationMs / 1e3).toFixed(1)}s]`
+        ];
+        if (result.filesRead.length > 0) {
+          lines.push(`Files read: ${result.filesRead.length}`);
+        }
+        if (result.filesModified.length > 0) {
+          lines.push(`Files modified: ${result.filesModified.join(", ")}`);
+        }
+        if (result.filesCreated.length > 0) {
+          lines.push(`Files created: ${result.filesCreated.join(", ")}`);
+        }
+        lines.push("", result.summary);
+        if (result.error) {
+          lines.push("", `Error: ${result.error}`);
+        }
+        return { success: result.success, output: lines.join("\n") };
+      } catch (error) {
+        return {
+          success: false,
+          error: `Failed to collect task: ${error instanceof Error ? error.message : String(error)}`
+        };
+      }
+    }
+  };
+}
+function createAskUserTool(_context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "ask_user",
+        description: "Ask the user a question and wait for their response. Use when you need clarification or additional information. In non-interactive mode, returns a default answer.",
+        parameters: {
+          type: "object",
+          properties: {
+            question: {
+              type: "string",
+              description: "Question to ask the user"
+            }
+          },
+          required: ["question"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const question = input.question;
+      const isInteractive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;
+      if (!isInteractive) {
+        return {
+          success: true,
+          output: `[Auto-answer] Question was: "${question}". Proceeding with default behavior.`
+        };
+      }
+      return new Promise((resolve3) => {
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+        rl.question(`
+\u2753 ${question}
+> `, (answer) => {
+          rl.close();
+          if (!answer || answer.trim() === "") {
+            resolve3({
+              success: false,
+              error: "No answer provided"
+            });
+          } else {
+            resolve3({
+              success: true,
+              output: answer.trim()
+            });
+          }
+        });
+      });
+    }
+  };
+}
+async function hasPendingCorrectionCommit(context) {
+  const kernel = await context.sessionMemory?.loadKernelState();
+  if (!kernel) {
+    return false;
+  }
+  return kernel.memory.pendingActions.some(
+    (action) => action.status !== "done" && action.content.startsWith("Persist user correction via memory_correction:")
+  );
+}
+var VERIFY_REPORT_CLAIMS_PROMPT = [
+  "Evaluate whether the proposed final agent answer is sufficiently supported by the provided session evidence.",
+  "Prefer blocking only when the answer makes unsupported code, file, architecture, or behavioral claims.",
+  "Allow simple session recall when kernel evidence is enough.",
+  "If evidence is partial, prefer warn instead of block unless the answer states unsupported details as facts.",
+  "Return strict JSON only."
+].join(" ");
+async function verifyReportClaims(context, answer) {
+  const kernel = await context.sessionMemory?.loadKernelState();
+  const requirements = await resolveResponseRequirements(context, answer, kernel);
+  const evidence = kernel?.memory.evidence ?? [];
+  const recallFastPath = verifyEvidenceBackedRecall(answer, kernel, requirements);
+  if (recallFastPath) {
+    return recallFastPath;
+  }
+  const fallback = deterministicVerification(answer, kernel, requirements);
+  const llm = useLLM$1({ tier: "small" });
+  if (!llm?.complete) {
+    return fallback;
+  }
+  try {
+    const response = await llm.complete(buildClaimVerificationPrompt(answer, kernel, context), {
+      systemPrompt: VERIFY_REPORT_CLAIMS_PROMPT,
+      temperature: 0,
+      maxTokens: 350
+    });
+    return normalizeClaimVerification(response.content, fallback, evidence);
+  } catch {
+    return fallback;
+  }
+}
+async function resolveResponseRequirements(context, answer, kernel) {
+  if (!context.responseRequirementsResolver) {
+    return null;
+  }
+  try {
+    return await context.responseRequirementsResolver({
+      task: context.currentTask,
+      answer,
+      kernel: kernel ?? null
+    });
+  } catch {
+    return null;
+  }
+}
+function buildClaimVerificationPrompt(answer, kernel, context) {
+  const recentEvidence = (kernel?.memory.evidence ?? []).slice(-6).map((item) => ({
+    toolName: item.toolName ?? item.source,
+    toolInputSummary: item.toolInputSummary,
+    summary: item.summary
+  }));
+  const archiveEvidence = (kernel?.memory.evidence ?? []).slice(-4).flatMap((item) => {
+    if (!item.toolInputSummary || !context.archiveMemory?.hasFile(item.toolInputSummary)) {
+      return [];
+    }
+    const archived = context.archiveMemory.recallByFilePath(item.toolInputSummary);
+    if (!archived) {
+      return [];
+    }
+    return [{
+      filePath: item.toolInputSummary,
+      toolName: archived.toolName,
+      excerpt: truncateText(archived.fullOutput, 1200)
+    }];
+  });
+  return JSON.stringify({
+    answer,
+    objective: kernel?.objective ?? kernel?.currentTask ?? "",
+    constraints: kernel?.constraints ?? [],
+    recentCorrections: kernel?.memory.corrections.slice(-3).map((item) => item.content) ?? [],
+    recentEvidence,
+    archiveEvidence,
+    schema: {
+      verdict: "allow | warn | block",
+      rationale: "short explanation",
+      requirements: {
+        allowsMemoryOnlyRecall: "boolean",
+        needsDirectToolEvidence: "boolean",
+        needsFileBackedClaims: "boolean",
+        allowsInference: "boolean",
+        maxUnsupportedClaims: "number"
+      },
+      supportedClaims: ["string"],
+      unsupportedClaims: ["string"]
+    }
+  }, null, 2);
+}
+function normalizeClaimVerification(content, fallback, evidence) {
+  const parsed = extractJsonObject(content);
+  if (!parsed) {
+    return fallback;
+  }
+  const requirements = normalizeEvidenceRequirements(parsed.requirements, fallback.requirements);
+  const verdict = parsed.verdict === "allow" || parsed.verdict === "warn" || parsed.verdict === "block" ? parsed.verdict : fallback.verdict;
+  const supportedClaims = normalizeStringArray(parsed.supportedClaims);
+  const unsupportedClaims = normalizeStringArray(parsed.unsupportedClaims);
+  const rationale = typeof parsed.rationale === "string" && parsed.rationale.trim() ? parsed.rationale.trim() : fallback.rationale;
+  if (verdict === "block" && unsupportedClaims.length === 0 && evidence.length > 0) {
+    return fallback;
+  }
+  return {
+    verdict,
+    rationale,
+    requirements,
+    supportedClaims,
+    unsupportedClaims
+  };
+}
+function deterministicVerification(answer, kernel, responseRequirements) {
+  const evidence = kernel?.memory.evidence ?? [];
+  const shellRecall = /shell command|previous shell command|used in this session|latest shell command/i.test(answer);
+  const fileLikeClaims = /RuntimeEngine|projectKernelPrompt|compactKernelState|plugins\/|packages\/|\.ts\b|line \d+/i.test(answer);
+  const hasFileEvidence = evidence.some((item) => item.toolName === "fs_read");
+  const hasShellEvidence = evidence.some((item) => item.toolName === "shell_exec");
+  const requirements = responseRequirements?.requirements;
+  if (shellRecall && hasShellEvidence) {
+    return {
+      verdict: "allow",
+      rationale: "Shell recall answer is grounded in stored shell_exec evidence.",
+      requirements: {
+        allowsMemoryOnlyRecall: true,
+        needsDirectToolEvidence: false,
+        needsFileBackedClaims: false,
+        allowsInference: false,
+        maxUnsupportedClaims: 0
+      },
+      supportedClaims: ["Session shell recall supported by shell_exec evidence."],
+      unsupportedClaims: []
+    };
+  }
+  if (fileLikeClaims && !hasFileEvidence) {
+    return {
+      verdict: "block",
+      rationale: "Code/file claims require fs_read-backed evidence before report is allowed.",
+      requirements: {
+        allowsMemoryOnlyRecall: false,
+        needsDirectToolEvidence: true,
+        needsFileBackedClaims: true,
+        allowsInference: false,
+        maxUnsupportedClaims: 0
+      },
+      supportedClaims: [],
+      unsupportedClaims: ["Answer makes file/code claims without fs_read evidence."]
+    };
+  }
+  return {
+    verdict: "allow",
+    rationale: "No unsupported claims were detected by deterministic fallback.",
+    requirements: requirements ?? {
+      allowsMemoryOnlyRecall: true,
+      needsDirectToolEvidence: false,
+      needsFileBackedClaims: false,
+      allowsInference: true,
+      maxUnsupportedClaims: 1
+    },
+    supportedClaims: [],
+    unsupportedClaims: []
+  };
+}
+function verifyEvidenceBackedRecall(answer, kernel, responseRequirements) {
+  if (!responseRequirements?.requirements.allowsMemoryOnlyRecall) {
+    return null;
+  }
+  const evidence = kernel?.memory.evidence ?? [];
+  const fileEvidence = evidence.filter((item) => item.toolName === "fs_read" && item.toolInputSummary).map((item) => item.toolInputSummary);
+  const mentionedFiles = extractMentionedFilePaths(answer);
+  if (mentionedFiles.length > 0 && mentionedFiles.every((filePath) => fileEvidence.includes(filePath))) {
+    return {
+      verdict: "allow",
+      rationale: "Answer is a direct recall of file evidence already recorded in the session.",
+      requirements: responseRequirements.requirements,
+      supportedClaims: mentionedFiles.map((filePath) => `Read evidence exists for ${filePath}.`),
+      unsupportedClaims: []
+    };
+  }
+  return null;
+}
+function extractMentionedFilePaths(answer) {
+  const matches = answer.match(/plugins\/[^\s`*]+|packages\/[^\s`*]+/g) ?? [];
+  return [...new Set(matches)];
+}
+function normalizeEvidenceRequirements(value, fallback) {
+  if (!value || typeof value !== "object") {
+    return fallback;
+  }
+  const input = value;
+  return {
+    allowsMemoryOnlyRecall: typeof input.allowsMemoryOnlyRecall === "boolean" ? input.allowsMemoryOnlyRecall : fallback.allowsMemoryOnlyRecall,
+    needsDirectToolEvidence: typeof input.needsDirectToolEvidence === "boolean" ? input.needsDirectToolEvidence : fallback.needsDirectToolEvidence,
+    needsFileBackedClaims: typeof input.needsFileBackedClaims === "boolean" ? input.needsFileBackedClaims : fallback.needsFileBackedClaims,
+    allowsInference: typeof input.allowsInference === "boolean" ? input.allowsInference : fallback.allowsInference,
+    maxUnsupportedClaims: typeof input.maxUnsupportedClaims === "number" ? input.maxUnsupportedClaims : fallback.maxUnsupportedClaims
+  };
+}
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function extractJsonObject(content) {
+  const start = content.indexOf("{");
+  const end = content.lastIndexOf("}");
+  if (start === -1 || end === -1 || end <= start) {
+    return null;
+  }
+  try {
+    return JSON.parse(content.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+}
+function truncateText(value, maxChars) {
+  const normalized = value.trim();
+  if (normalized.length <= maxChars) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxChars - 1).trimEnd()}\u2026`;
+}
+function createAskParentTool(_context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "ask_parent",
+        description: `Ask the parent agent for help when stuck or need clarification.`,
+        parameters: {
+          type: "object",
+          properties: {
+            question: {
+              type: "string",
+              description: "Your question for the parent agent. Be specific about what you need help with."
+            },
+            reason: {
+              type: "string",
+              enum: ["stuck", "uncertain", "blocker", "clarification"],
+              description: "Why are you asking? stuck=repeating tools, uncertain=unclear approach, blocker=cannot proceed, clarification=need more info"
+            },
+            context: {
+              type: "object",
+              description: "Relevant context: tools tried, iteration number, what you attempted"
+            }
+          },
+          required: ["question", "reason"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const question = input.question;
+      const reason = input.reason;
+      const context = input.context;
+      return {
+        success: true,
+        output: "",
+        // Will be populated by parent agent
+        metadata: {
+          question,
+          reason,
+          context,
+          needsParentHelp: true
+        }
+      };
+    }
+  };
+}
+function createReportTool(context) {
+  return {
+    definition: {
+      type: "function",
+      function: {
+        name: "report",
+        description: `Report your answer and exit. Include specific findings with file paths and code snippets as evidence.`,
+        parameters: {
+          type: "object",
+          properties: {
+            answer: {
+              type: "string",
+              description: "Synthesized answer with specific details, file references, and code snippets. Be concise but complete."
+            },
+            confidence: {
+              type: "number",
+              description: "How confident you are in this answer (0.0-1.0). Use 0.8+ if you found concrete evidence, 0.5-0.7 if partial, <0.5 if uncertain."
+            }
+          },
+          required: ["answer", "confidence"]
+        }
+      }
+    },
+    executor: async (input) => {
+      const answer = input.answer;
+      const confidence = input.confidence;
+      const inPlanMode = context.allowedTools?.has("plan_validate") ?? false;
+      if (inPlanMode && !context.planValidationPassed) {
+        const planPath = context.sessionId ? path4.join(context.workingDir, ".kb", "agents", "sessions", context.sessionId, "plan.md") : null;
+        const hasPlanFile = planPath && fs2.existsSync(planPath);
+        if (!hasPlanFile) {
+          return {
+            success: false,
+            output: "BLOCKED: You must either (1) call plan_validate first, or (2) save your plan via plan_write and then call report. Call plan_write with your plan content now."
+          };
+        }
+      }
+      if (await hasPendingCorrectionCommit(context)) {
+        return {
+          success: false,
+          output: "BLOCKED: You must call memory_correction before report because this session has an unpersisted user correction or active instruction. Persist it first, then report.",
+          metadata: {
+            code: "PENDING_MEMORY_COMMIT"
+          }
+        };
+      }
+      const verification = await verifyReportClaims(context, answer);
+      if (verification.verdict === "block") {
+        return {
+          success: false,
+          output: `BLOCKED: Report claims are not sufficiently supported by session evidence. ${verification.rationale}`,
+          metadata: {
+            code: "INSUFFICIENT_EVIDENCE",
+            verification
+          }
+        };
+      }
+      return {
+        success: true,
+        output: "",
+        // Intentionally empty - agent should exit after calling this
+        metadata: {
+          answer,
+          confidence,
+          earlyExit: true,
+          verification
+        }
+      };
+    }
+  };
+}
+
+// src/tools/index.ts
+function createToolRegistry(context) {
+  const allowed = context.allowedTools;
+  const allow = (name) => !allowed || allowed.has(name);
+  const registry = new ToolRegistry(context);
+  if (allow("fs_write")) {
+    registry.register(createFsWriteTool(context));
+  }
+  if (allow("fs_read")) {
+    registry.register(createFsReadTool(context));
+  }
+  if (allow("fs_patch")) {
+    registry.register(createFsPatchTool(context));
+  }
+  if (allow("fs_replace")) {
+    registry.register(createFsReplaceTool(context));
+  }
+  if (allow("fs_list")) {
+    registry.register(createFsListTool(context));
+  }
+  if (allow("mass_replace")) {
+    registry.register(createMassReplaceTool(context));
+  }
+  if (allow("glob_search")) {
+    registry.register(createGlobSearchTool(context));
+  }
+  if (allow("grep_search")) {
+    registry.register(createGrepSearchTool(context));
+  }
+  if (allow("find_definition")) {
+    registry.register(createFindDefinitionTool(context));
+  }
+  if (allow("code_stats")) {
+    registry.register(createCodeStatsTool(context));
+  }
+  if (allow("shell_exec")) {
+    registry.register(createShellExecTool(context));
+  }
+  if (context.taskManager) {
+    if (allow("task_submit")) {
+      registry.register(createTaskSubmitTool(context));
+    }
+    if (allow("task_status")) {
+      registry.register(createTaskStatusTool(context));
+    }
+    if (allow("task_collect")) {
+      registry.register(createTaskCollectTool(context));
+    }
+  }
+  if (allow("memory_get")) {
+    registry.register(createMemoryGetTool(context));
+  }
+  if (allow("memory_preference")) {
+    registry.register(createMemoryPreferenceTool(context));
+  }
+  if (allow("memory_constraint")) {
+    registry.register(createMemoryConstraintTool(context));
+  }
+  if (allow("session_save")) {
+    registry.register(createSessionSaveTool(context));
+  }
+  if (allow("memory_correction")) {
+    registry.register(createMemoryCorrectionTool(context));
+  }
+  if (allow("memory_finding")) {
+    registry.register(createMemoryFindingTool(context));
+  }
+  if (allow("memory_blocker")) {
+    registry.register(createMemoryBlockerTool(context));
+  }
+  if (context.archiveMemory && allow("archive_recall")) {
+    registry.register(createArchiveRecallTool(context));
+  }
+  if (allow("todo_create")) {
+    registry.register(createTodoCreateTool(context));
+  }
+  if (allow("todo_update")) {
+    registry.register(createTodoUpdateTool(context));
+  }
+  if (allow("todo_get")) {
+    registry.register(createTodoGetTool(context));
+  }
+  if (allow("plan_validate")) {
+    registry.register(createPlanValidateTool(context));
+  }
+  if (allow("plan_write")) {
+    registry.register(createPlanWriteTool(context));
+  }
+  if (allow("ask_user")) {
+    registry.register(createAskUserTool());
+  }
+  if (allow("ask_parent")) {
+    registry.register(createAskParentTool());
+  }
+  if (allow("report")) {
+    registry.register(createReportTool(context));
+  }
+  return registry;
+}
+
+// src/gateway.ts
+var DEFAULT_TOOL_CAPABILITIES = {
+  fs_write: ["filesystem"],
+  fs_read: ["filesystem"],
+  fs_patch: ["filesystem"],
+  fs_list: ["filesystem"],
+  mass_replace: ["filesystem"],
+  glob_search: ["search"],
+  grep_search: ["search"],
+  list_files: ["search"],
+  find_definition: ["code-navigation"],
+  code_stats: ["search"],
+  shell_exec: ["shell"],
+  memory_get: ["memory"],
+  memory_preference: ["memory"],
+  memory_constraint: ["memory"],
+  session_save: ["memory"],
+  memory_correction: ["memory"],
+  memory_finding: ["memory"],
+  memory_blocker: ["memory"],
+  archive_recall: ["memory"],
+  todo_create: ["todo"],
+  todo_update: ["todo"],
+  todo_get: ["todo"],
+  ask_user: ["interaction"],
+  ask_parent: ["reporting"],
+  report: ["reporting"],
+  task_submit: ["delegation"],
+  task_status: ["delegation"],
+  task_collect: ["delegation"],
+  plan_validate: ["planning"]
+};
+function toArtifact(toolName, result) {
+  const summary = result.output || result.error || `${toolName} completed`;
+  return {
+    status: result.success ? "success" : "error",
+    summary,
+    artifact: result.metadata,
+    evidence: summary ? [{
+      id: `ev-${Date.now()}-${toolName}`,
+      summary,
+      source: toolName,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      artifact: result.metadata
+    }] : [],
+    mutations: typeof result.metadata?.filePath === "string" ? { filesRead: [result.metadata.filePath] } : void 0,
+    followUpHints: typeof result.metadata?.summary === "string" ? [String(result.metadata.summary)] : void 0
+  };
+}
+var ToolGateway = class {
+  constructor(context, policies = []) {
+    this.context = context;
+    this.policies = policies;
+    this.registry = createToolRegistry(context);
+  }
+  registry;
+  getDefinitions() {
+    return this.registry.getDefinitions().filter(
+      (definition) => this.isAllowed(definition.function.name)
+    );
+  }
+  getToolNames() {
+    return this.getDefinitions().map((definition) => definition.function.name);
+  }
+  async execute(name, input) {
+    const allowed = this.isAllowed(name);
+    if (!allowed) {
+      const artifact = {
+        status: "error",
+        summary: `Tool "${name}" blocked by policy`,
+        evidence: []
+      };
+      return {
+        result: { success: false, error: artifact.summary },
+        artifact
+      };
+    }
+    const result = await this.registry.execute(name, input);
+    return {
+      result,
+      artifact: toArtifact(name, result)
+    };
+  }
+  isAllowed(toolName) {
+    const capabilities = this.getToolCapabilities(toolName);
+    return this.policies.every(
+      (policy) => policy.allows(toolName, this.context) && capabilities.every((capability) => policy.allowsCapability?.(capability, this.context, toolName) ?? true)
+    );
+  }
+  getToolCapabilities(toolName) {
+    const mapped = this.context.toolCapabilitiesByName?.get(toolName);
+    return mapped ?? DEFAULT_TOOL_CAPABILITIES[toolName] ?? [];
+  }
+};
+
+// src/remote-workspace-provider.ts
+var RemoteWorkspaceProvider = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async readFile(path9, offset, limit) {
+    const result = await this.opts.dispatch("filesystem", "readFile", [path9]);
+    const content = result;
+    const lines = content.split("\n");
+    const start = (offset ?? 1) - 1;
+    const count = limit ?? lines.length;
+    const sliced = lines.slice(start, start + count);
+    return {
+      content: sliced.join("\n"),
+      totalLines: lines.length,
+      truncated: sliced.length < lines.length
+    };
+  }
+  async writeFile(path9, content) {
+    await this.opts.dispatch("filesystem", "writeFile", [path9, content]);
+  }
+  async listDir(path9, limit) {
+    const result = await this.opts.dispatch("filesystem", "listDir", [path9]);
+    const entries = result;
+    return limit ? entries.slice(0, limit) : entries;
+  }
+  async stat(path9) {
+    return await this.opts.dispatch("filesystem", "stat", [path9]);
+  }
+  async exists(path9) {
+    return await this.opts.dispatch("filesystem", "exists", [path9]);
+  }
+  async grep(pattern, directory, options) {
+    return await this.opts.dispatch("search", "grep", [pattern, directory, options]);
+  }
+  async glob(pattern, directory, options) {
+    return await this.opts.dispatch("search", "glob", [pattern, directory, options]);
+  }
+  async shellExec(command, options) {
+    return await this.opts.dispatch("shell", "exec", [command, options]);
+  }
+};
+
+export { ALL_SOURCE_EXTENSIONS, DELEGATION_CONFIG, FILESYSTEM_CONFIG, MASS_REPLACE_CONFIG, PLAN_READ_ONLY_TOOL_NAMES, RemoteWorkspaceProvider, SEARCH_CONFIG, SHELL_CONFIG, SOURCE_FILE_EXTENSIONS, SUB_AGENT_PRESETS, TODO_CONFIG, ToolGateway, ToolRegistry, createArchiveRecallTool, createAskParentTool, createAskUserTool, createCodeStatsTool, createFindDefinitionTool, createFsListTool, createFsPatchTool, createFsReadTool, createFsReplaceTool, createFsWriteTool, createGlobSearchTool, createGrepSearchTool, createListFilesTool, createMassReplaceTool, createMemoryBlockerTool, createMemoryConstraintTool, createMemoryCorrectionTool, createMemoryFindingTool, createMemoryGetTool, createMemoryPreferenceTool, createPlanValidateTool, createPlanWriteTool, createReportTool, createSessionSaveTool, createShellExecTool, createTaskCollectTool, createTaskStatusTool, createTaskSubmitTool, createTodoCreateTool, createTodoGetTool, createTodoUpdateTool, createToolRegistry, normalizeOffsetLimit, suggestDirectory, toFindNames, toRgIncludes, validatePath };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map