@mastra/core 1.4.0 → 1.5.0-alpha.1

package/dist/{chunk-4EHGOATH.js → chunk-FZ5DRHKE.js}

@@ -1,9 +1,11 @@
-import { createTool } from './chunk-RS6CZXGA.js';
+import { createTool } from './chunk-BQHWJLXU.js';
 import { MastraBase } from './chunk-WCAFTXGK.js';
 import { RegisteredLogger } from './chunk-X2WMFSPB.js';
+import posixPath from 'path/posix';
 import { constants } from 'fs';
 import * as fs2 from 'fs/promises';
 import * as nodePath from 'path';
+import picomatch from 'picomatch';
 import * as crypto from 'crypto';
 import { createHash } from 'crypto';
 import matter from 'gray-matter';
@@ -22,6 +24,12 @@ var WorkspaceError = class extends Error {
     this.name = "WorkspaceError";
   }
 };
+var WorkspaceNotAvailableError = class extends WorkspaceError {
+  constructor() {
+    super("Workspace not available. Ensure the agent has a workspace configured.", "NO_WORKSPACE");
+    this.name = "WorkspaceNotAvailableError";
+  }
+};
 var FilesystemNotAvailableError = class extends WorkspaceError {
   constructor() {
     super("Workspace does not have a filesystem configured", "NO_FILESYSTEM");
@@ -141,6 +149,7 @@ var CompositeFilesystem = class {
   id;
   name = "CompositeFilesystem";
   provider = "composite";
+  readOnly;
   status = "ready";
   _mounts;
   constructor(config) {
@@ -153,6 +162,7 @@ var CompositeFilesystem = class {
     if (this._mounts.size === 0) {
       throw new Error("CompositeFilesystem requires at least one mount");
     }
+    this.readOnly = [...this._mounts.values()].every((fs5) => fs5.readOnly) || void 0;
     const mountPaths = [...this._mounts.keys()];
     for (const a of mountPaths) {
       for (const b of mountPaths) {
@@ -170,10 +180,29 @@ var CompositeFilesystem = class {
   }
   /**
    * Get the mounts map.
+   * Returns a typed map where `get()` preserves the concrete filesystem type per mount path.
    */
   get mounts() {
     return this._mounts;
   }
+  /**
+   * Get status and metadata for this composite filesystem.
+   * Includes info from each mounted filesystem in `metadata.mounts`.
+   */
+  async getInfo() {
+    const mounts = {};
+    for (const [mountPath, fs5] of this._mounts) {
+      mounts[mountPath] = await fs5.getInfo?.() ?? null;
+    }
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      readOnly: this.readOnly,
+      metadata: { mounts }
+    };
+  }
   /**
    * Get the underlying filesystem for a given path.
    * Returns undefined if the path doesn't resolve to any mount.
@@ -192,7 +221,8 @@ var CompositeFilesystem = class {
   }
   normalizePath(path4) {
     if (!path4 || path4 === "/") return "/";
-    let n = path4.startsWith("/") ? path4 : `/${path4}`;
+    let n = posixPath.normalize(path4);
+    if (!n.startsWith("/")) n = `/${n}`;
     if (n.length > 1 && n.endsWith("/")) n = n.slice(0, -1);
     return n;
   }
@@ -426,8 +456,7 @@ var CompositeFilesystem = class {
       return `- ${mountPath}: ${name} ${access2}`;
     }).join("\n");
     return `Mounted filesystems:
-${mountDescriptions}
-Files written via workspace tools are accessible at the same paths in sandbox commands.`;
+${mountDescriptions}`;
   }
 };
 
@@ -737,6 +766,7 @@ var LocalFilesystem = class extends MastraFilesystem {
   status = "pending";
   _basePath;
   _contained;
+  _allowedPaths;
   /**
    * The absolute base path on disk where files are stored.
    * Useful for understanding how workspace paths map to disk paths.
@@ -744,16 +774,51 @@ var LocalFilesystem = class extends MastraFilesystem {
   get basePath() {
     return this._basePath;
   }
+  /**
+   * Current set of additional allowed paths (absolute, resolved).
+   * These paths are permitted beyond basePath when containment is enabled.
+   */
+  get allowedPaths() {
+    return this._allowedPaths;
+  }
+  /**
+   * Update allowed paths. Accepts a direct array or an updater callback
+   * receiving the current paths (React setState pattern).
+   *
+   * @example
+   * ```typescript
+   * // Set directly
+   * fs.setAllowedPaths(['/home/user/.config']);
+   *
+   * // Update with callback
+   * fs.setAllowedPaths(prev => [...prev, '/home/user/.ssh']);
+   * ```
+   */
+  setAllowedPaths(pathsOrUpdater) {
+    const newPaths = typeof pathsOrUpdater === "function" ? pathsOrUpdater(this._allowedPaths) : pathsOrUpdater;
+    this._allowedPaths = newPaths.map((p) => nodePath.resolve(p));
+  }
   constructor(options) {
     super({ ...options, name: "LocalFilesystem" });
     this.id = options.id ?? this.generateId();
     this._basePath = nodePath.resolve(options.basePath);
     this._contained = options.contained ?? true;
     this.readOnly = options.readOnly;
+    this._allowedPaths = (options.allowedPaths ?? []).map((p) => nodePath.resolve(p));
   }
   generateId() {
     return `local-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
+  /**
+   * Check if an absolute path falls within basePath or any allowed path.
+   */
+  _isWithinAnyRoot(absolutePath) {
+    const roots = [this._basePath, ...this._allowedPaths];
+    return roots.some((root) => {
+      const relative2 = nodePath.relative(root, absolutePath);
+      return !relative2.startsWith("..") && !nodePath.isAbsolute(relative2);
+    });
+  }
   toBuffer(content) {
     if (Buffer.isBuffer(content)) return content;
     if (content instanceof Uint8Array) return Buffer.from(content);
@@ -765,8 +830,7 @@ var LocalFilesystem = class extends MastraFilesystem {
       absolutePath = nodePath.normalize(inputPath);
     } else if (this._contained && nodePath.isAbsolute(inputPath)) {
       const normalized = nodePath.normalize(inputPath);
-      const relative2 = nodePath.relative(this._basePath, normalized);
-      if (!relative2.startsWith("..") && !nodePath.isAbsolute(relative2)) {
+      if (this._isWithinAnyRoot(normalized)) {
         absolutePath = normalized;
       } else {
         const cleanedPath = inputPath.replace(/^\/+/, "");
@@ -777,8 +841,7 @@ var LocalFilesystem = class extends MastraFilesystem {
       absolutePath = nodePath.resolve(this._basePath, nodePath.normalize(cleanedPath));
     }
     if (this._contained) {
-      const relative2 = nodePath.relative(this._basePath, absolutePath);
-      if (relative2.startsWith("..") || nodePath.isAbsolute(relative2)) {
+      if (!this._isWithinAnyRoot(absolutePath)) {
         throw new PermissionError(inputPath, "access");
       }
     }
@@ -798,14 +861,19 @@ var LocalFilesystem = class extends MastraFilesystem {
    */
   async assertPathContained(absolutePath) {
     if (!this._contained) return;
-    let baseReal;
-    try {
-      baseReal = await fs2.realpath(this._basePath);
-    } catch (error) {
-      if (isEnoentError(error)) {
-        throw new DirectoryNotFoundError(this._basePath);
+    const rootReals = [];
+    for (const root of [this._basePath, ...this._allowedPaths]) {
+      try {
+        rootReals.push(await fs2.realpath(root));
+      } catch (error) {
+        if (isEnoentError(error)) {
+          continue;
+        }
+        throw error;
       }
-      throw error;
+    }
+    if (rootReals.length === 0) {
+      throw new DirectoryNotFoundError(this._basePath);
     }
     let targetReal;
     try {
@@ -832,7 +900,10 @@ var LocalFilesystem = class extends MastraFilesystem {
         throw error;
       }
     }
-    if (targetReal !== baseReal && !targetReal.startsWith(baseReal + nodePath.sep)) {
+    const isWithinRoot = rootReals.some(
+      (rootReal) => targetReal === rootReal || targetReal.startsWith(rootReal + nodePath.sep)
+    );
+    if (!isWithinRoot) {
       throw new PermissionError(absolutePath, "access");
     }
   }
@@ -1191,15 +1262,17 @@ var LocalFilesystem = class extends MastraFilesystem {
       error: this.error,
       metadata: {
         basePath: this.basePath,
-        contained: this._contained
+        contained: this._contained,
+        ...this._allowedPaths.length > 0 && { allowedPaths: [...this._allowedPaths] }
       }
     };
   }
   getInstructions() {
+    const allowedNote = this._allowedPaths.length > 0 ? ` Additionally, the following paths outside basePath are accessible: ${this._allowedPaths.join(", ")}.` : "";
     if (this._contained) {
-      return `Local filesystem at "${this.basePath}". Files at workspace path "/foo" are stored at "${this.basePath}/foo" on disk.`;
+      return `Local filesystem at "${this.basePath}". Files at workspace path "/foo" are stored at "${this.basePath}/foo" on disk.${allowedNote}`;
     }
-    return `Local filesystem rooted at "${this.basePath}". Containment is disabled so absolute paths access the real filesystem. Use paths relative to "${this.basePath}" (e.g. "foo/bar.txt") for workspace files. Avoid unnecessary listing "/" as it would traverse the entire host filesystem.`;
+    return `Local filesystem rooted at "${this.basePath}". Containment is disabled so absolute paths access the real filesystem. Use paths relative to "${this.basePath}" (e.g. "foo/bar.txt") for workspace files. Avoid unnecessary listing "/" as it would traverse the entire host filesystem.${allowedNote}`;
   }
 };
 var InMemoryFileReadTracker = class {
@@ -1242,6 +1315,38 @@ var InMemoryFileReadTracker = class {
     return normalized.replace(/\/$/, "") || "/";
   }
 };
+var GLOB_CHARS = /[*?{}[\]]/;
+function isGlobPattern(input) {
+  return GLOB_CHARS.test(input);
+}
+function extractGlobBase(pattern) {
+  const firstMeta = pattern.search(GLOB_CHARS);
+  if (firstMeta === -1) {
+    return pattern;
+  }
+  const prefix = pattern.slice(0, firstMeta);
+  const lastSlash = prefix.lastIndexOf("/");
+  if (lastSlash <= 0) {
+    return "/";
+  }
+  return prefix.slice(0, lastSlash);
+}
+function normalizeForMatch(input) {
+  if (input.startsWith("./")) return input.slice(2);
+  if (input.startsWith("/")) return input.slice(1);
+  return input;
+}
+function createGlobMatcher(patterns, options) {
+  const patternArray = (Array.isArray(patterns) ? patterns : [patterns]).map(normalizeForMatch);
+  const matcher = picomatch(patternArray, {
+    posix: true,
+    dot: options?.dot ?? false
+  });
+  return (path4) => matcher(normalizeForMatch(path4));
+}
+function matchGlob(path4, pattern, options) {
+  return createGlobMatcher(pattern, options)(path4);
+}
 
 // src/workspace/sandbox/errors.ts
 var SandboxError = class extends Error {
@@ -2695,11 +2800,211 @@ var LocalSkillSource = class {
     const entries = await fs2.readdir(resolved, { withFileTypes: true });
     return entries.map((entry) => ({
       name: entry.name,
-      type: entry.isDirectory() ? "directory" : "file"
+      type: entry.isDirectory() ? "directory" : "file",
+      isSymlink: entry.isSymbolicLink() || void 0
     }));
   }
 };
-var WorkspaceSkillsImpl = class {
+
+// src/workspace/skills/versioned-skill-source.ts
+var VersionedSkillSource = class {
+  #tree;
+  #blobStore;
+  #versionCreatedAt;
+  /** Computed set of directory paths from the tree entries */
+  #directories;
+  constructor(tree, blobStore, versionCreatedAt) {
+    this.#tree = tree;
+    this.#blobStore = blobStore;
+    this.#versionCreatedAt = versionCreatedAt;
+    this.#directories = this.#computeDirectories();
+  }
+  /**
+   * Compute all directory paths implied by the file tree.
+   * For a file at "references/api.md", this adds "" (root), "references".
+   */
+  #computeDirectories() {
+    const dirs = /* @__PURE__ */ new Set();
+    dirs.add("");
+    dirs.add(".");
+    for (const filePath of Object.keys(this.#tree.entries)) {
+      const parts = filePath.split("/");
+      for (let i = 1; i < parts.length; i++) {
+        dirs.add(parts.slice(0, i).join("/"));
+      }
+    }
+    return dirs;
+  }
+  /**
+   * Normalize a path by stripping leading/trailing slashes and dots.
+   */
+  #normalizePath(path4) {
+    let normalized = path4.replace(/^[./\\]+|[/\\]+$/g, "");
+    if (normalized === "") return "";
+    return normalized;
+  }
+  async exists(path4) {
+    const normalized = this.#normalizePath(path4);
+    if (this.#tree.entries[normalized]) return true;
+    return this.#directories.has(normalized);
+  }
+  async stat(path4) {
+    const normalized = this.#normalizePath(path4);
+    const name = normalized.split("/").pop() || normalized || ".";
+    const entry = this.#tree.entries[normalized];
+    if (entry) {
+      return {
+        name,
+        type: "file",
+        size: entry.size,
+        createdAt: this.#versionCreatedAt,
+        modifiedAt: this.#versionCreatedAt,
+        mimeType: entry.mimeType
+      };
+    }
+    if (this.#directories.has(normalized)) {
+      return {
+        name,
+        type: "directory",
+        size: 0,
+        createdAt: this.#versionCreatedAt,
+        modifiedAt: this.#versionCreatedAt
+      };
+    }
+    throw new Error(`Path not found in skill version tree: ${path4}`);
+  }
+  async readFile(path4) {
+    const normalized = this.#normalizePath(path4);
+    const entry = this.#tree.entries[normalized];
+    if (!entry) {
+      throw new Error(`File not found in skill version tree: ${path4}`);
+    }
+    const blob = await this.#blobStore.get(entry.blobHash);
+    if (!blob) {
+      throw new Error(`Blob not found for hash ${entry.blobHash} (file: ${path4})`);
+    }
+    if (entry.encoding === "base64") {
+      return Buffer.from(blob.content, "base64");
+    }
+    return blob.content;
+  }
+  async readdir(path4) {
+    const normalized = this.#normalizePath(path4);
+    if (!this.#directories.has(normalized)) {
+      throw new Error(`Directory not found in skill version tree: ${path4}`);
+    }
+    const prefix = normalized === "" ? "" : normalized + "/";
+    const seen = /* @__PURE__ */ new Set();
+    const entries = [];
+    for (const filePath of Object.keys(this.#tree.entries)) {
+      if (!filePath.startsWith(prefix)) continue;
+      const remaining = filePath.slice(prefix.length);
+      const nextSegment = remaining.split("/")[0];
+      if (!nextSegment || seen.has(nextSegment)) continue;
+      seen.add(nextSegment);
+      const isDirectory = remaining.includes("/");
+      entries.push({
+        name: nextSegment,
+        type: isDirectory ? "directory" : "file"
+      });
+    }
+    return entries;
+  }
+};
+
+// src/workspace/skills/composite-versioned-skill-source.ts
+var CompositeVersionedSkillSource = class {
+  #sources = /* @__PURE__ */ new Map();
+  #fallback;
+  #fallbackSkills;
+  constructor(entries, blobStore, options) {
+    for (const entry of entries) {
+      this.#sources.set(entry.dirName, new VersionedSkillSource(entry.tree, blobStore, entry.versionCreatedAt));
+    }
+    this.#fallback = options?.fallback;
+    this.#fallbackSkills = new Set(options?.fallbackSkills ?? []);
+  }
+  #normalizePath(path4) {
+    return path4.replace(/^[./\\]+|[/\\]+$/g, "");
+  }
+  /**
+   * Route a path to the correct source.
+   * Returns the source and the remaining path within that source.
+   */
+  #routePath(path4) {
+    const normalized = this.#normalizePath(path4);
+    if (normalized === "") return null;
+    const segments = normalized.split("/");
+    const skillDir = segments[0];
+    const subPath = segments.slice(1).join("/");
+    if (this.#fallbackSkills.has(skillDir) && this.#fallback) {
+      return { source: this.#fallback, subPath: normalized };
+    }
+    const versionedSource = this.#sources.get(skillDir);
+    if (versionedSource) {
+      return { source: versionedSource, subPath };
+    }
+    if (this.#fallback) {
+      return { source: this.#fallback, subPath: normalized };
+    }
+    return null;
+  }
+  async exists(path4) {
+    const normalized = this.#normalizePath(path4);
+    if (normalized === "") return true;
+    const route = this.#routePath(path4);
+    if (!route) return false;
+    return route.source.exists(route.subPath);
+  }
+  async stat(path4) {
+    const normalized = this.#normalizePath(path4);
+    if (normalized === "") {
+      return {
+        name: ".",
+        type: "directory",
+        size: 0,
+        createdAt: /* @__PURE__ */ new Date(),
+        modifiedAt: /* @__PURE__ */ new Date()
+      };
+    }
+    const route = this.#routePath(path4);
+    if (!route) {
+      throw new Error(`Path not found in composite skill source: ${path4}`);
+    }
+    return route.source.stat(route.subPath);
+  }
+  async readFile(path4) {
+    const route = this.#routePath(path4);
+    if (!route) {
+      throw new Error(`File not found in composite skill source: ${path4}`);
+    }
+    return route.source.readFile(route.subPath);
+  }
+  async readdir(path4) {
+    const normalized = this.#normalizePath(path4);
+    if (normalized === "") {
+      const entries = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const dirName of this.#sources.keys()) {
+        entries.push({ name: dirName, type: "directory" });
+        seen.add(dirName);
+      }
+      for (const dirName of this.#fallbackSkills) {
+        if (!seen.has(dirName)) {
+          entries.push({ name: dirName, type: "directory" });
+          seen.add(dirName);
+        }
+      }
+      return entries;
+    }
+    const route = this.#routePath(path4);
+    if (!route) {
+      throw new Error(`Directory not found in composite skill source: ${path4}`);
+    }
+    return route.source.readdir(route.subPath);
+  }
+};
+var WorkspaceSkillsImpl = class _WorkspaceSkillsImpl {
   #source;
   #skillsResolver;
   #searchEngine;
@@ -2714,6 +3019,13 @@ var WorkspaceSkillsImpl = class {
   #lastDiscoveryTime = 0;
   /** Currently resolved skills paths (used to detect changes) */
   #resolvedPaths = [];
+  /** Cached glob-resolved directories and per-pattern resolve timestamps */
+  #globDirCache = /* @__PURE__ */ new Map();
+  #globResolveTimes = /* @__PURE__ */ new Map();
+  static GLOB_RESOLVE_INTERVAL = 5e3;
+  // Re-walk glob dirs every 5s
+  static STALENESS_CHECK_COOLDOWN = 2e3;
+  // Skip staleness check for 2s after discovery
   constructor(config) {
     this.#source = config.source;
     this.#skillsResolver = config.skills;
@@ -2766,6 +3078,35 @@ var WorkspaceSkillsImpl = class {
       await this.refresh();
     }
   }
+  async addSkill(skillPath) {
+    await this.#ensureInitialized();
+    let skillFilePath;
+    let dirName;
+    if (skillPath.endsWith("/SKILL.md") || skillPath === "SKILL.md") {
+      skillFilePath = skillPath;
+      dirName = this.#getParentPath(skillPath).split("/").pop() || "unknown";
+    } else {
+      skillFilePath = this.#joinPath(skillPath, "SKILL.md");
+      dirName = skillPath.split("/").pop() || "unknown";
+    }
+    const source = this.#inferSource(skillPath);
+    const skill = await this.#parseSkillFile(skillFilePath, dirName, source);
+    const existing = this.#skills.get(skill.name);
+    if (existing) {
+      await this.#removeSkillFromIndex(existing);
+    }
+    this.#skills.set(skill.name, skill);
+    await this.#indexSkill(skill);
+    this.#lastDiscoveryTime = Date.now();
+  }
+  async removeSkill(skillName) {
+    await this.#ensureInitialized();
+    const skill = this.#skills.get(skillName);
+    if (!skill) return;
+    await this.#removeSkillFromIndex(skill);
+    this.#skills.delete(skillName);
+    this.#lastDiscoveryTime = Date.now();
+  }
   /**
    * Resolve skills paths from the resolver (static array or function).
    */
@@ -2922,19 +3263,82 @@ var WorkspaceSkillsImpl = class {
   /**
    * Discover skills from all skills paths.
    * Uses currently resolved paths (must be set before calling).
+   *
+   * Paths can be plain directories (e.g., '/skills') or glob patterns
+   * (e.g., '**\/skills'). Glob patterns resolve to directories that match
+   * the pattern, each of which is then scanned for skills.
    */
   async #discoverSkills() {
+    this.#globDirCache.clear();
+    this.#globResolveTimes.clear();
     for (const skillsPath of this.#resolvedPaths) {
       const source = this.#determineSource(skillsPath);
-      await this.#discoverSkillsInPath(skillsPath, source);
+      if (isGlobPattern(skillsPath)) {
+        const matchingDirs = await this.#resolveGlobToDirectories(skillsPath);
+        this.#globDirCache.set(skillsPath, matchingDirs);
+        this.#globResolveTimes.set(skillsPath, Date.now());
+        for (const dir of matchingDirs) {
+          await this.#discoverSkillsInPath(dir, source);
+        }
+      } else {
+        const isDirect = await this.#discoverDirectSkill(skillsPath, source);
+        if (!isDirect) {
+          await this.#discoverSkillsInPath(skillsPath, source);
+        }
+      }
     }
     this.#lastDiscoveryTime = Date.now();
   }
+  /**
+   * Resolve a glob pattern to a list of matching directories.
+   * Walks from extractGlobBase() and tests each directory against the pattern.
+   *
+   * Note: Broad patterns like `/** /skills` resolve to a walk root of `/`,
+   * scanning the entire workspace tree. This is cached per-pattern with a
+   * TTL (GLOB_RESOLVE_INTERVAL) to limit I/O. For large workspaces, prefer
+   * more specific patterns like `/src/** /skills` to narrow the walk root.
+   */
+  async #resolveGlobToDirectories(pattern) {
+    const walkRoot = extractGlobBase(pattern);
+    const matcher = createGlobMatcher(pattern, { dot: true });
+    const matchingDirs = [];
+    await this.#walkForDirectories(walkRoot, (dirPath) => {
+      if (matcher(dirPath)) {
+        matchingDirs.push(dirPath);
+      }
+    });
+    return matchingDirs;
+  }
+  /**
+   * Walk a directory tree and call callback for each directory found.
+   */
+  async #walkForDirectories(basePath, callback, depth = 0, maxDepth = 4) {
+    if (depth >= maxDepth) return;
+    try {
+      const entries = await this.#source.readdir(basePath);
+      for (const entry of entries) {
+        if (entry.type !== "directory" || entry.isSymlink) continue;
+        const entryPath = basePath === "/" ? `/${entry.name}` : `${basePath}/${entry.name}`;
+        callback(entryPath);
+        await this.#walkForDirectories(entryPath, callback, depth + 1, maxDepth);
+      }
+    } catch {
+    }
+  }
   /**
    * Discover skills in a single path
    */
   async #discoverSkillsInPath(skillsPath, source) {
-    if (!await this.#source.exists(skillsPath)) {
+    try {
+      if (!await this.#source.exists(skillsPath)) {
+        return;
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        console.warn(`[WorkspaceSkills] Cannot access skills path "${skillsPath}": ${error.message}`);
+      } else {
+        console.warn(`[WorkspaceSkills] Cannot access skills path "${skillsPath}": ${String(error)}`);
+      }
       return;
     }
     try {
@@ -2961,35 +3365,107 @@ var WorkspaceSkillsImpl = class {
       }
     }
   }
+  /**
+   * Attempt to discover a skill from a direct path reference.
+   *
+   * Handles two cases:
+   * - Path ends with `/SKILL.md` → parse directly, extract dirName from parent
+   * - Path is a directory containing `SKILL.md` → parse it as a single skill
+   *
+   * Returns `true` if the path was a direct skill reference (skip subdirectory scan),
+   * `false` to fall through to the normal subdirectory scan.
+   */
+  async #discoverDirectSkill(skillsPath, source) {
+    try {
+      if (skillsPath.endsWith("/SKILL.md") || skillsPath === "SKILL.md") {
+        if (!await this.#source.exists(skillsPath)) {
+          return true;
+        }
+        const skillDir = this.#getParentPath(skillsPath);
+        const dirName = skillDir.split("/").pop() || skillDir;
+        try {
+          const skill = await this.#parseSkillFile(skillsPath, dirName, source);
+          this.#skills.set(skill.name, skill);
+          await this.#indexSkill(skill);
+        } catch (error) {
+          if (error instanceof Error) {
+            console.error(`[WorkspaceSkills] Failed to load skill from ${skillsPath}:`, error.message);
+          }
+        }
+        return true;
+      }
+      if (await this.#source.exists(skillsPath)) {
+        const skillFilePath = this.#joinPath(skillsPath, "SKILL.md");
+        if (await this.#source.exists(skillFilePath)) {
+          const dirName = skillsPath.split("/").pop() || skillsPath;
+          try {
+            const skill = await this.#parseSkillFile(skillFilePath, dirName, source);
+            this.#skills.set(skill.name, skill);
+            await this.#indexSkill(skill);
+          } catch (error) {
+            if (error instanceof Error) {
+              console.error(`[WorkspaceSkills] Failed to load skill from ${skillFilePath}:`, error.message);
+            }
+          }
+          return true;
+        }
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
   /**
    * Check if any skills path directory has been modified since last discovery.
    * Compares directory mtime to lastDiscoveryTime.
+   * For glob patterns, checks the walk root and expanded directories.
    */
   async #isSkillsPathStale() {
     if (this.#lastDiscoveryTime === 0) {
       return true;
     }
+    if (Date.now() - this.#lastDiscoveryTime < _WorkspaceSkillsImpl.STALENESS_CHECK_COOLDOWN) {
+      return false;
+    }
     for (const skillsPath of this.#resolvedPaths) {
-      try {
-        const stat3 = await this.#source.stat(skillsPath);
-        const mtime = stat3.modifiedAt.getTime();
-        if (mtime > this.#lastDiscoveryTime) {
-          return true;
+      let pathsToCheck;
+      if (isGlobPattern(skillsPath)) {
+        const now = Date.now();
+        const lastResolved = this.#globResolveTimes.get(skillsPath) ?? 0;
+        if (now - lastResolved > _WorkspaceSkillsImpl.GLOB_RESOLVE_INTERVAL || !this.#globDirCache.has(skillsPath)) {
+          const dirs = await this.#resolveGlobToDirectories(skillsPath);
+          this.#globDirCache.set(skillsPath, dirs);
+          this.#globResolveTimes.set(skillsPath, now);
         }
-        const entries = await this.#source.readdir(skillsPath);
-        for (const entry of entries) {
-          if (entry.type !== "directory") continue;
-          const entryPath = this.#joinPath(skillsPath, entry.name);
-          try {
-            const entryStat = await this.#source.stat(entryPath);
-            if (entryStat.modifiedAt.getTime() > this.#lastDiscoveryTime) {
-              return true;
+        pathsToCheck = this.#globDirCache.get(skillsPath) ?? [];
+      } else {
+        pathsToCheck = [skillsPath];
+      }
+      for (const pathToCheck of pathsToCheck) {
+        try {
+          const stat3 = await this.#source.stat(pathToCheck);
+          const mtime = stat3.modifiedAt.getTime();
+          if (mtime > this.#lastDiscoveryTime) {
+            return true;
+          }
+          if (stat3.type !== "directory") {
+            continue;
+          }
+          const entries = await this.#source.readdir(pathToCheck);
+          for (const entry of entries) {
+            if (entry.type !== "directory") continue;
+            const entryPath = this.#joinPath(pathToCheck, entry.name);
+            try {
+              const entryStat = await this.#source.stat(entryPath);
+              if (entryStat.modifiedAt.getTime() > this.#lastDiscoveryTime) {
+                return true;
+              }
+            } catch {
             }
-          } catch {
           }
+        } catch {
+          continue;
         }
-      } catch {
-        continue;
       }
     }
     return false;
@@ -3073,7 +3549,7 @@ ${validation.errors.join("\n")}`);
     const entries = await this.#source.readdir(dirPath);
     for (const entry of entries) {
       const entryPath = this.#joinPath(dirPath, entry.name);
-      if (entry.type === "directory") {
+      if (entry.type === "directory" && !entry.isSymlink) {
         await this.#walkDirectory(basePath, entryPath, callback, depth + 1, maxDepth);
       } else {
         const relativePath = entryPath.substring(basePath.length + 1);
@@ -3097,6 +3573,30 @@ ${validation.errors.join("\n")}`);
     }
     return parts.join("\n\n");
   }
+  /**
+   * Remove a skill's entries from the search index.
+   */
+  async #removeSkillFromIndex(skill) {
+    if (!this.#searchEngine?.remove) return;
+    const ids = [`skill:${skill.name}:SKILL.md`, ...skill.references.map((r) => `skill:${skill.name}:${r}`)];
+    for (const id of ids) {
+      try {
+        await this.#searchEngine.remove(id);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Infer the ContentSource for a skill path by matching against resolved paths.
+   */
+  #inferSource(skillPath) {
+    for (const rp of this.#resolvedPaths) {
+      if (skillPath === rp || skillPath.startsWith(rp + "/")) {
+        return this.#determineSource(rp);
+      }
+    }
+    return this.#determineSource(skillPath);
+  }
   /**
    * Index a skill for search
    */
@@ -3206,6 +3706,151 @@ ${validation.errors.join("\n")}`);
     return lastSlash > 0 ? path4.substring(0, lastSlash) : "/";
   }
 };
+function hashContent(content) {
+  if (Buffer.isBuffer(content)) {
+    return createHash("sha256").update(content).digest("hex");
+  }
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function detectMimeType(filename) {
+  const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+  const mimeTypes = {
+    ".md": "text/markdown",
+    ".txt": "text/plain",
+    ".json": "application/json",
+    ".yaml": "text/yaml",
+    ".yml": "text/yaml",
+    ".sh": "text/x-shellscript",
+    ".py": "text/x-python",
+    ".js": "text/javascript",
+    ".ts": "text/typescript",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml"
+  };
+  return mimeTypes[ext];
+}
+function isBinaryMimeType(mimeType) {
+  if (!mimeType) return false;
+  if (mimeType.startsWith("text/")) return false;
+  if (mimeType === "application/json") return false;
+  if (mimeType === "image/svg+xml") return false;
+  return true;
+}
+async function walkSkillDirectory(source, basePath, currentPath = basePath) {
+  const entries = await source.readdir(currentPath);
+  const files = [];
+  for (const entry of entries) {
+    const entryPath = joinPath(currentPath, entry.name);
+    if (entry.type === "directory") {
+      const subFiles = await walkSkillDirectory(source, basePath, entryPath);
+      files.push(...subFiles);
+    } else {
+      const rawContent = await source.readFile(entryPath);
+      const relativePath = entryPath.substring(basePath.length + 1);
+      const mimeType = detectMimeType(entry.name);
+      const isBinary = isBinaryMimeType(mimeType);
+      if (isBinary) {
+        const buf = Buffer.isBuffer(rawContent) ? rawContent : Buffer.from(rawContent, "utf-8");
+        files.push({ path: relativePath, content: buf, isBinary: true });
+      } else {
+        const content = typeof rawContent === "string" ? rawContent : rawContent.toString("utf-8");
+        files.push({ path: relativePath, content, isBinary: false });
+      }
+    }
+  }
+  return files;
+}
+function joinPath(...segments) {
+  return segments.map((seg, i) => {
+    if (i === 0) return seg.replace(/\/+$/, "");
+    return seg.replace(/^\/+|\/+$/g, "");
+  }).filter(Boolean).join("/");
+}
+function collectSubdirPaths(allPaths, subdir) {
+  const prefix = subdir + "/";
+  return allPaths.filter((p) => p.startsWith(prefix)).map((p) => p.substring(prefix.length));
+}
+async function collectSkillForPublish(source, skillPath) {
+  const files = await walkSkillDirectory(source, skillPath);
+  const treeEntries = {};
+  const blobMap = /* @__PURE__ */ new Map();
+  const now = /* @__PURE__ */ new Date();
+  for (const file of files) {
+    const hash = hashContent(file.content);
+    const mimeType = detectMimeType(file.path);
+    if (file.isBinary) {
+      const buf = Buffer.isBuffer(file.content) ? file.content : Buffer.from(file.content);
+      const size = buf.length;
+      const base64Content = buf.toString("base64");
+      treeEntries[file.path] = {
+        blobHash: hash,
+        size,
+        mimeType,
+        encoding: "base64"
+      };
+      if (!blobMap.has(hash)) {
+        blobMap.set(hash, {
+          hash,
+          content: base64Content,
+          size,
+          mimeType,
+          createdAt: now
+        });
+      }
+    } else {
+      const content = file.content;
+      const size = Buffer.byteLength(content, "utf-8");
+      treeEntries[file.path] = {
+        blobHash: hash,
+        size,
+        mimeType
+      };
+      if (!blobMap.has(hash)) {
+        blobMap.set(hash, {
+          hash,
+          content,
+          size,
+          mimeType,
+          createdAt: now
+        });
+      }
+    }
+  }
+  const tree = { entries: treeEntries };
+  const blobs = Array.from(blobMap.values());
+  const skillMdFile = files.find((f) => f.path === "SKILL.md");
+  if (!skillMdFile) {
+    throw new Error(`SKILL.md not found in ${skillPath}`);
+  }
+  const parsed = matter(skillMdFile.content);
+  const frontmatter = parsed.data;
+  const instructions = parsed.content.trim();
+  const allPaths = files.map((f) => f.path);
+  const references = collectSubdirPaths(allPaths, "references");
+  const scripts = collectSubdirPaths(allPaths, "scripts");
+  const assets = collectSubdirPaths(allPaths, "assets");
+  const snapshot = {
+    name: frontmatter.name,
+    description: frontmatter.description,
+    instructions,
+    license: frontmatter.license,
+    compatibility: frontmatter.compatibility,
+    metadata: frontmatter.metadata,
+    ...references.length > 0 ? { references } : {},
+    ...scripts.length > 0 ? { scripts } : {},
+    ...assets.length > 0 ? { assets } : {}
+  };
+  return { snapshot, tree, blobs };
+}
+async function publishSkillFromSource(source, skillPath, blobStore) {
+  const result = await collectSkillForPublish(source, skillPath);
+  await blobStore.putMany(result.blobs);
+  return result;
+}
 
 // src/workspace/workspace.ts
 var Workspace = class {
@@ -3290,12 +3935,18 @@ var Workspace = class {
   }
   /**
    * The filesystem provider (if configured).
+   *
+   * Returns the concrete type you passed to the constructor.
+   * When `mounts` is used instead of `filesystem`, returns `CompositeFilesystem`
+   * parameterized with the concrete mount types.
    */
   get filesystem() {
     return this._fs;
   }
   /**
    * The sandbox provider (if configured).
+   *
+   * Returns the concrete type you passed to the constructor.
    */
   get sandbox() {
     return this._sandbox;
@@ -3325,7 +3976,7 @@ var Workspace = class {
       return void 0;
     }
     if (!this._skills) {
-      const source = this._fs ?? new LocalSkillSource();
+      const source = this._config.skillSource ?? this._fs ?? new LocalSkillSource();
       this._skills = new WorkspaceSkillsImpl({
         source,
         skills: this._config.skills,
@@ -3403,31 +4054,51 @@ var Workspace = class {
   /**
    * Rebuild the search index from filesystem paths.
    * Used internally for auto-indexing on init.
+   *
+   * Paths can be plain directories (e.g., '/docs') or glob patterns
+   * (e.g., '/docs/**\/*.md'). Glob patterns are resolved to a walk root
+   * via extractGlobBase, then files are filtered by the pattern.
    */
   async rebuildSearchIndex(paths) {
     if (!this._searchEngine || !this._fs || paths.length === 0) {
       return;
     }
     this._searchEngine.clear();
-    for (const basePath of paths) {
+    for (const pathOrGlob of paths) {
       try {
-        const files = await this.getAllFiles(basePath);
-        for (const filePath of files) {
-          try {
-            const content = await this._fs.readFile(filePath, { encoding: "utf-8" });
-            await this._searchEngine.index({
-              id: filePath,
-              content
-            });
-          } catch {
+        if (isGlobPattern(pathOrGlob)) {
+          const walkRoot = extractGlobBase(pathOrGlob);
+          const matcher = createGlobMatcher(pathOrGlob);
+          const files = await this.getAllFiles(walkRoot);
+          for (const filePath of files) {
+            if (!matcher(filePath)) continue;
+            await this.indexFileForSearch(filePath);
+          }
+        } else {
+          const files = await this.getAllFiles(pathOrGlob);
+          for (const filePath of files) {
+            await this.indexFileForSearch(filePath);
           }
         }
       } catch {
       }
     }
   }
-  async getAllFiles(dir) {
-    if (!this._fs) return [];
+  /**
+   * Index a single file for search. Skips files that can't be read as text.
+   */
+  async indexFileForSearch(filePath) {
+    try {
+      const content = await this._fs.readFile(filePath, { encoding: "utf-8" });
+      await this._searchEngine.index({
+        id: filePath,
+        content
+      });
+    } catch {
+    }
+  }
+  async getAllFiles(dir, depth = 0, maxDepth = 10) {
+    if (!this._fs || depth >= maxDepth) return [];
     const files = [];
     const entries = await this._fs.readdir(dir);
     for (const entry of entries) {
@@ -3435,7 +4106,7 @@ var Workspace = class {
       if (entry.type === "file") {
         files.push(fullPath);
       } else if (entry.type === "directory" && !entry.isSymlink) {
-        files.push(...await this.getAllFiles(fullPath));
+        files.push(...await this.getAllFiles(fullPath, depth + 1, maxDepth));
       }
     }
     return files;
@@ -3915,7 +4586,10 @@ var LocalSandbox = class extends MastraSandbox {
    * Status management is handled by the base class.
    */
   async start() {
-    this.logger.debug("Starting sandbox", { workingDirectory: this._workingDirectory, isolation: this._isolation });
+    this.logger.debug("[LocalSandbox] Starting sandbox", {
+      workingDirectory: this._workingDirectory,
+      isolation: this._isolation
+    });
     await fs2.mkdir(this.workingDirectory, { recursive: true });
     if (this._isolation === "seatbelt") {
       const userProvidedPath = this._nativeSandboxConfig.seatbeltProfilePath;
@@ -3941,14 +4615,14 @@ var LocalSandbox = class extends MastraSandbox {
         await fs2.writeFile(this._seatbeltProfilePath, this._seatbeltProfile, "utf-8");
       }
     }
-    this.logger.debug("Sandbox started", { workingDirectory: this._workingDirectory });
+    this.logger.debug("[LocalSandbox] Sandbox started", { workingDirectory: this._workingDirectory });
   }
   /**
    * Stop the local sandbox.
    * Status management is handled by the base class.
    */
   async stop() {
-    this.logger.debug("Stopping sandbox", { workingDirectory: this._workingDirectory });
+    this.logger.debug("[LocalSandbox] Stopping sandbox", { workingDirectory: this._workingDirectory });
   }
   /**
    * Destroy the local sandbox and clean up resources.
@@ -3956,7 +4630,7 @@ var LocalSandbox = class extends MastraSandbox {
    * Status management is handled by the base class.
    */
   async destroy() {
-    this.logger.debug("Destroying sandbox", { workingDirectory: this._workingDirectory });
+    this.logger.debug("[LocalSandbox] Destroying sandbox", { workingDirectory: this._workingDirectory });
     if (this._seatbeltProfilePath && !this._userProvidedProfilePath) {
       try {
         await fs2.unlink(this._seatbeltProfilePath);
@@ -4022,7 +4696,7 @@ var LocalSandbox = class extends MastraSandbox {
     });
   }
   async executeCommand(command, args = [], options = {}) {
-    this.logger.debug("Executing command", { command, args, cwd: options.cwd ?? this.workingDirectory });
+    this.logger.debug("[LocalSandbox] Executing command", { command, args, cwd: options.cwd ?? this.workingDirectory });
     await this.ensureRunning();
     const startTime = Date.now();
     const wrapped = this.wrapCommandForIsolation(command, args);
@@ -4041,7 +4715,7 @@ var LocalSandbox = class extends MastraSandbox {
         exitCode: result.exitCode,
         executionTimeMs: Date.now() - startTime
       };
-      this.logger.info("Command completed", {
+      this.logger.debug("[LocalSandbox] Command completed", {
         command,
         exitCode: commandResult.exitCode,
         executionTimeMs: commandResult.executionTimeMs
@@ -4049,7 +4723,7 @@ var LocalSandbox = class extends MastraSandbox {
       return commandResult;
     } catch (error) {
       const executionTimeMs = Date.now() - startTime;
-      this.logger.error("Command failed", { command, error, executionTimeMs });
+      this.logger.error("[LocalSandbox] Command failed", { command, error, executionTimeMs });
       return {
         success: false,
         stdout: "",
@@ -4071,7 +4745,8 @@ var WORKSPACE_TOOLS = {
     LIST_FILES: `${WORKSPACE_TOOLS_PREFIX}_list_files`,
     DELETE: `${WORKSPACE_TOOLS_PREFIX}_delete`,
     FILE_STAT: `${WORKSPACE_TOOLS_PREFIX}_file_stat`,
-    MKDIR: `${WORKSPACE_TOOLS_PREFIX}_mkdir`
+    MKDIR: `${WORKSPACE_TOOLS_PREFIX}_mkdir`,
+    GREP: `${WORKSPACE_TOOLS_PREFIX}_grep`
   },
   SANDBOX: {
     EXECUTE_COMMAND: `${WORKSPACE_TOOLS_PREFIX}_execute_command`
@@ -4082,6 +4757,357 @@ var WORKSPACE_TOOLS = {
   }
 };
 
+// src/workspace/tools/helpers.ts
+function requireWorkspace(context) {
+  if (!context?.workspace) {
+    throw new WorkspaceNotAvailableError();
+  }
+  return context.workspace;
+}
+function requireFilesystem(context) {
+  const workspace = requireWorkspace(context);
+  if (!workspace.filesystem) {
+    throw new FilesystemNotAvailableError();
+  }
+  return { workspace, filesystem: workspace.filesystem };
+}
+function requireSandbox(context) {
+  const workspace = requireWorkspace(context);
+  if (!workspace.sandbox) {
+    throw new SandboxNotAvailableError();
+  }
+  return { workspace, sandbox: workspace.sandbox };
+}
+async function emitWorkspaceMetadata(context, toolName) {
+  const workspace = requireWorkspace(context);
+  const info = await workspace.getInfo();
+  const toolCallId = context?.agent?.toolCallId;
+  await context?.writer?.custom({
+    type: "data-workspace-metadata",
+    data: { toolName, toolCallId, ...info }
+  });
+}
+
+// src/workspace/tools/delete-file.ts
+var deleteFileTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.DELETE,
+  description: "Delete a file or directory from the workspace filesystem",
+  inputSchema: z.object({
+    path: z.string().describe("The path to the file or directory to delete"),
+    recursive: z.boolean().optional().default(false).describe("If true, delete directories and their contents recursively. Required for non-empty directories.")
+  }),
+  execute: async ({ path: path4, recursive }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.DELETE);
+    if (filesystem.readOnly) {
+      throw new WorkspaceReadOnlyError("delete");
+    }
+    const stat3 = await filesystem.stat(path4);
+    if (stat3.type === "directory") {
+      await filesystem.rmdir(path4, { recursive, force: recursive });
+    } else {
+      await filesystem.deleteFile(path4);
+    }
+    return `Deleted ${path4}`;
+  }
+});
+var editFileTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE,
+  description: `Edit a file by replacing specific text. The old_string must match exactly and be unique in the file.
+
+Usage:
+- Read the file first to get the exact text to replace.
+- By default, ${WORKSPACE_TOOLS.FILESYSTEM.READ_FILE} output includes line number prefixes (e.g., "     1\u2192"). Ensure you preserve the exact indentation as it appears AFTER the arrow. Never include any part of the line number prefix in old_string or new_string.
+- Include enough surrounding context (multiple lines) to make old_string unique. If it still isn't unique, include more lines.
+- Use replace_all only when intentionally replacing all occurrences.`,
+  inputSchema: z.object({
+    path: z.string().describe("The path to the file to edit"),
+    old_string: z.string().describe("The exact text to find and replace. Must be unique in the file."),
+    new_string: z.string().describe("The text to replace old_string with"),
+    replace_all: z.boolean().optional().default(false).describe("If true, replace all occurrences. If false (default), old_string must be unique.")
+  }),
+  execute: async ({ path: path4, old_string, new_string, replace_all }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE);
+    if (filesystem.readOnly) {
+      throw new WorkspaceReadOnlyError("edit_file");
+    }
+    try {
+      const content = await filesystem.readFile(path4, { encoding: "utf-8" });
+      if (typeof content !== "string") {
+        return `Cannot edit binary files. Use ${WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE} instead.`;
+      }
+      const result = replaceString(content, old_string, new_string, replace_all);
+      await filesystem.writeFile(path4, result.content, { overwrite: true });
+      return `Replaced ${result.replacements} occurrence${result.replacements !== 1 ? "s" : ""} in ${path4}`;
+    } catch (error) {
+      if (error instanceof StringNotFoundError) {
+        return error.message;
+      }
+      if (error instanceof StringNotUniqueError) {
+        return error.message;
+      }
+      throw error;
+    }
+  }
+});
+var executeCommandTool = createTool({
+  id: WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND,
+  description: `Execute a shell command in the workspace sandbox.
+
+Usage:
+- Verify parent directories exist before running commands that create files or directories.
+- Always quote file paths that contain spaces (e.g., cd "/path/with spaces").
+- Use the timeout parameter to limit execution time. Behavior when omitted depends on the sandbox provider.
+- Optionally use cwd to override the working directory. Commands run from the sandbox default if omitted.`,
+  inputSchema: z.object({
+    command: z.string().describe('The command to execute (e.g., "ls", "npm", "python")'),
+    args: z.array(z.string()).nullish().default([]).describe("Arguments to pass to the command"),
+    timeout: z.number().nullish().describe("Maximum execution time in milliseconds. Example: 60000 for 1 minute."),
+    cwd: z.string().nullish().describe("Working directory for the command")
+  }),
+  execute: async ({ command, args, timeout, cwd }, context) => {
+    const { sandbox } = requireSandbox(context);
+    if (!sandbox.executeCommand) {
+      throw new SandboxFeatureNotSupportedError("executeCommand");
+    }
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND);
+    const toolCallId = context?.agent?.toolCallId;
+    const startedAt = Date.now();
+    let stdout = "";
+    let stderr = "";
+    try {
+      const result = await sandbox.executeCommand(command, args ?? [], {
+        timeout: timeout ?? void 0,
+        cwd: cwd ?? void 0,
+        onStdout: async (data) => {
+          stdout += data;
+          await context?.writer?.custom({
+            type: "data-sandbox-stdout",
+            data: { output: data, timestamp: Date.now(), toolCallId }
+          });
+        },
+        onStderr: async (data) => {
+          stderr += data;
+          await context?.writer?.custom({
+            type: "data-sandbox-stderr",
+            data: { output: data, timestamp: Date.now(), toolCallId }
+          });
+        }
+      });
+      await context?.writer?.custom({
+        type: "data-sandbox-exit",
+        data: {
+          exitCode: result.exitCode,
+          success: result.success,
+          executionTimeMs: result.executionTimeMs,
+          toolCallId
+        }
+      });
+      if (!result.success) {
+        const parts = [result.stdout, result.stderr].filter(Boolean);
+        parts.push(`Exit code: ${result.exitCode}`);
+        return parts.join("\n");
+      }
+      return result.stdout || "(no output)";
+    } catch (error) {
+      await context?.writer?.custom({
+        type: "data-sandbox-exit",
+        data: {
+          exitCode: -1,
+          success: false,
+          executionTimeMs: Date.now() - startedAt,
+          toolCallId
+        }
+      });
+      const parts = [stdout, stderr].filter(Boolean);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      parts.push(`Error: ${errorMessage}`);
+      return parts.join("\n");
+    }
+  }
+});
+var fileStatTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT,
+  description: "Get file or directory metadata from the workspace. Returns existence, type, size, and modification time.",
+  inputSchema: z.object({
+    path: z.string().describe("The path to check")
+  }),
+  execute: async ({ path: path4 }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT);
+    try {
+      const stat3 = await filesystem.stat(path4);
+      const modifiedAt = stat3.modifiedAt.toISOString();
+      const parts = [`${path4}`, `Type: ${stat3.type}`];
+      if (stat3.size !== void 0) parts.push(`Size: ${stat3.size} bytes`);
+      parts.push(`Modified: ${modifiedAt}`);
+      return parts.join(" ");
+    } catch (error) {
+      if (error instanceof FileNotFoundError) {
+        return `${path4}: not found`;
+      }
+      throw error;
+    }
+  }
+});
+var grepTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.GREP,
+  description: `Search file contents using a regex pattern. Walks the filesystem and returns matching lines with file paths and line numbers.
+
+Usage:
+- Basic search: { pattern: "TODO" }
+- Regex: { pattern: "function\\s+\\w+\\(" }
+- Multiple terms: { pattern: "TODO|FIXME|HACK" }
+- Case-insensitive: { pattern: "error", caseSensitive: false }
+- Search in directory: { pattern: "import", path: "./src" }
+- Filter by glob: { pattern: "import", path: "**/*.ts" }
+- Combined path + glob: { pattern: "import", path: "src/**/*.ts" }
+- Multiple file types: { pattern: "import", path: "**/*.{ts,tsx,js}" }
+- Multiple directories: { pattern: "TODO", path: "{src,lib}/**/*.ts" }
+- With context: { pattern: "function", contextLines: 2 }`,
+  inputSchema: z.object({
+    pattern: z.string().describe("Regex pattern to search for"),
+    path: z.string().optional().default("./").describe(
+      'File, directory, or glob pattern to search within (default: "./"). A plain path searches that file or directory. A glob pattern (e.g., "**/*.ts", "src/**/*.test.ts") filters which files to search.'
+    ),
+    contextLines: z.number().optional().default(0).describe("Number of lines of context to include before and after each match (default: 0)"),
+    maxCount: z.number().optional().describe(
+      "Maximum matches per file. Moves on to the next file after this many matches. Similar to grep -m flag."
+    ),
+    caseSensitive: z.boolean().optional().default(true).describe("Whether the search is case-sensitive (default: true)"),
+    includeHidden: z.boolean().optional().default(false).describe('Include hidden files and directories (names starting with ".") in the search (default: false)')
+  }),
+  execute: async ({ pattern, path: inputPath = "./", contextLines = 0, maxCount, caseSensitive = true, includeHidden = false }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.GREP);
+    const MAX_PATTERN_LENGTH = 1e3;
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+      return `Error: Pattern too long (${pattern.length} chars, max ${MAX_PATTERN_LENGTH}). Use a shorter pattern.`;
+    }
+    let regex;
+    try {
+      regex = new RegExp(pattern, caseSensitive ? "g" : "gi");
+    } catch (e) {
+      return `Error: Invalid regex pattern: ${e.message}`;
+    }
+    let searchPath;
+    let globMatcher;
+    if (isGlobPattern(inputPath)) {
+      searchPath = extractGlobBase(inputPath);
+      globMatcher = createGlobMatcher(inputPath, { dot: includeHidden });
+    } else {
+      searchPath = inputPath;
+    }
+    let filePaths;
+    try {
+      const stat3 = await filesystem.stat(searchPath);
+      if (stat3.type === "file") {
+        filePaths = isTextFile(searchPath) ? [searchPath] : [];
+      } else {
+        const collectFiles = async (dir) => {
+          const files = [];
+          let entries;
+          try {
+            entries = await filesystem.readdir(dir);
+          } catch {
+            return files;
+          }
+          for (const entry of entries) {
+            if (!includeHidden && entry.name.startsWith(".")) continue;
+            const fullPath = dir.endsWith("/") ? `${dir}${entry.name}` : `${dir}/${entry.name}`;
+            if (entry.type === "file") {
+              if (!isTextFile(entry.name)) continue;
+              if (globMatcher && !globMatcher(fullPath)) continue;
+              files.push(fullPath);
+            } else if (entry.type === "directory" && !entry.isSymlink) {
+              files.push(...await collectFiles(fullPath));
+            }
+          }
+          return files;
+        };
+        filePaths = await collectFiles(searchPath);
+      }
+    } catch {
+      filePaths = [];
+    }
+    const outputLines = [];
+    const filesWithMatches = /* @__PURE__ */ new Set();
+    let totalMatchCount = 0;
+    let truncated = false;
+    const MAX_LINE_LENGTH = 500;
+    const GLOBAL_CAP = 1e3;
+    for (const filePath of filePaths) {
+      if (truncated) break;
+      let content;
+      try {
+        const raw = await filesystem.readFile(filePath, { encoding: "utf-8" });
+        if (typeof raw !== "string") continue;
+        content = raw;
+      } catch {
+        continue;
+      }
+      const lines = content.split("\n");
+      let fileMatchCount = 0;
+      for (let i = 0; i < lines.length; i++) {
+        const currentLine = lines[i];
+        regex.lastIndex = 0;
+        const lineMatch = regex.exec(currentLine);
+        if (!lineMatch) continue;
+        filesWithMatches.add(filePath);
+        let lineContent = currentLine;
+        if (lineContent.length > MAX_LINE_LENGTH) {
+          lineContent = lineContent.slice(0, MAX_LINE_LENGTH) + "...";
+        }
+        if (contextLines > 0) {
+          const beforeStart = Math.max(0, i - contextLines);
+          for (let b = beforeStart; b < i; b++) {
+            outputLines.push(`${filePath}:${b + 1}- ${lines[b]}`);
+          }
+        }
+        outputLines.push(`${filePath}:${i + 1}:${lineMatch.index + 1}: ${lineContent}`);
+        if (contextLines > 0) {
+          const afterEnd = Math.min(lines.length - 1, i + contextLines);
+          for (let a = i + 1; a <= afterEnd; a++) {
+            outputLines.push(`${filePath}:${a + 1}- ${lines[a]}`);
+          }
+          outputLines.push("--");
+        }
+        totalMatchCount++;
+        fileMatchCount++;
+        if (maxCount !== void 0 && fileMatchCount >= maxCount) break;
+        if (totalMatchCount >= GLOBAL_CAP) {
+          truncated = true;
+          break;
+        }
+      }
+    }
+    outputLines.push("---");
+    const parts = [`${totalMatchCount} match${totalMatchCount !== 1 ? "es" : ""}`];
+    parts.push(`across ${filesWithMatches.size} file${filesWithMatches.size !== 1 ? "s" : ""}`);
+    if (truncated) {
+      parts.push(`(truncated at ${GLOBAL_CAP})`);
+    }
+    outputLines.push(parts.join(" "));
+    return outputLines.join("\n");
+  }
+});
+var indexContentTool = createTool({
+  id: WORKSPACE_TOOLS.SEARCH.INDEX,
+  description: "Index content for search. The path becomes the document ID in search results.",
+  inputSchema: z.object({
+    path: z.string().describe("The document ID/path for search results"),
+    content: z.string().describe("The text content to index"),
+    metadata: z.record(z.unknown()).optional().describe("Optional metadata to store with the document")
+  }),
+  execute: async ({ path: path4, content, metadata }, context) => {
+    const workspace = requireWorkspace(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SEARCH.INDEX);
+    await workspace.index(path4, content, { metadata });
+    return `Indexed ${path4}`;
+  }
+});
+
 // src/workspace/tools/tree-formatter.ts
 var BRANCH = "\u251C\u2500\u2500 ";
 var LAST_BRANCH = "\u2514\u2500\u2500 ";
@@ -4093,6 +5119,12 @@ async function formatAsTree(fs5, path4, options) {
   const dirsOnly = options?.dirsOnly ?? false;
   const exclude = options?.exclude;
   const extension = options?.extension;
+  const pattern = options?.pattern;
+  let globMatcher;
+  if (pattern) {
+    const patterns = Array.isArray(pattern) ? pattern : [pattern];
+    globMatcher = createGlobMatcher(patterns, { dot: showHidden });
+  }
   const lines = ["."];
   let dirCount = 0;
   let fileCount = 0;
@@ -4118,7 +5150,7 @@ async function formatAsTree(fs5, path4, options) {
     if (exclude) {
       const patterns = Array.isArray(exclude) ? exclude : [exclude];
       filtered = filtered.filter((e) => {
-        return !patterns.some((pattern) => e.name.includes(pattern));
+        return !patterns.some((pattern2) => e.name.includes(pattern2));
       });
     }
     if (dirsOnly) {
@@ -4134,6 +5166,20 @@ async function formatAsTree(fs5, path4, options) {
         });
       });
     }
+    if (globMatcher && !dirsOnly) {
+      filtered = filtered.filter((e) => {
+        if (e.type === "directory") return true;
+        const entryPath = currentPath === path4 ? e.name : `${currentPath === "/" ? "" : currentPath}/${e.name}`;
+        let relativePath;
+        if (path4 === "/" || path4 === "") {
+          relativePath = entryPath.startsWith("/") ? entryPath.slice(1) : entryPath;
+        } else {
+          relativePath = entryPath.startsWith(path4 + "/") ? entryPath.slice(path4.length + 1) : entryPath;
+          if (!relativePath) relativePath = entryPath;
+        }
+        return globMatcher(relativePath);
+      });
+    }
     filtered.sort((a, b) => {
       if (a.type === "directory" && b.type !== "directory") return -1;
       if (a.type !== "directory" && b.type === "directory") return 1;
@@ -4149,7 +5195,7 @@ async function formatAsTree(fs5, path4, options) {
       if (entry.type === "directory") {
         dirCount++;
         if (!entry.isSymlink) {
-          const childPath = joinPath(currentPath, entry.name);
+          const childPath = joinPath2(currentPath, entry.name);
           await buildTree(childPath, childPrefix, depth + 1);
         }
       } else {
@@ -4172,13 +5218,159 @@ async function formatAsTree(fs5, path4, options) {
     truncated
   };
 }
-function joinPath(base, name) {
+function joinPath2(base, name) {
   if (base === "/" || base === "") {
     return `/${name}`;
   }
   return `${base}/${name}`;
 }
 
+// src/workspace/tools/list-files.ts
+var listFilesTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES,
+  description: `List files and directories in the workspace filesystem.
+Returns a tree-style view (like the Unix "tree" command) for easy visualization.
+The output is displayed to the user as a tree-like structure in the tool result.
+Options mirror common tree command flags for familiarity.
+
+Examples:
+- List root: { path: "./" }
+- Deep listing: { path: "./src", maxDepth: 5 }
+- Directories only: { path: "./", dirsOnly: true }
+- Exclude node_modules: { path: "./", exclude: "node_modules" }
+- Find TypeScript files: { path: "./src", pattern: "**/*.ts" }
+- Find config files: { path: "./", pattern: "*.config.{js,ts}" }
+- Multiple patterns: { path: "./", pattern: ["**/*.ts", "**/*.tsx"] }`,
+  inputSchema: z.object({
+    path: z.string().default("./").describe("Directory path to list"),
+    maxDepth: z.number().optional().default(3).describe("Maximum depth to descend (default: 3). Similar to tree -L flag."),
+    showHidden: z.boolean().optional().default(false).describe('Show hidden files starting with "." (default: false). Similar to tree -a flag.'),
+    dirsOnly: z.boolean().optional().default(false).describe("List directories only, no files (default: false). Similar to tree -d flag."),
+    exclude: z.string().optional().describe('Pattern to exclude (e.g., "node_modules"). Similar to tree -I flag.'),
+    extension: z.string().optional().describe('Filter by file extension (e.g., ".ts"). Similar to tree -P flag.'),
+    pattern: z.union([z.string(), z.array(z.string())]).optional().describe(
+      'Glob pattern(s) to filter files. Examples: "**/*.ts", "src/**/*.test.ts", "*.config.{js,ts}". Directories always pass through.'
+    )
+  }),
+  execute: async ({ path: path4 = "./", maxDepth = 3, showHidden, dirsOnly, exclude, extension, pattern }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES);
+    const result = await formatAsTree(filesystem, path4, {
+      maxDepth,
+      showHidden,
+      dirsOnly,
+      exclude: exclude || void 0,
+      extension: extension || void 0,
+      pattern: pattern || void 0
+    });
+    return `${result.tree}
+
+${result.summary}`;
+  }
+});
+var mkdirTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.MKDIR,
+  description: "Create a directory in the workspace filesystem",
+  inputSchema: z.object({
+    path: z.string().describe("The path of the directory to create"),
+    recursive: z.boolean().optional().default(true).describe("Whether to create parent directories if they do not exist")
+  }),
+  execute: async ({ path: path4, recursive }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.MKDIR);
+    if (filesystem.readOnly) {
+      throw new WorkspaceReadOnlyError("mkdir");
+    }
+    await filesystem.mkdir(path4, { recursive });
+    return `Created directory ${path4}`;
+  }
+});
+var readFileTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.READ_FILE,
+  description: "Read the contents of a file from the workspace filesystem. Use offset/limit parameters to read specific line ranges for large files.",
+  inputSchema: z.object({
+    path: z.string().describe('The path to the file to read (e.g., "/data/config.json")'),
+    encoding: z.enum(["utf-8", "utf8", "base64", "hex", "binary"]).optional().describe("The encoding to use when reading the file. Defaults to utf-8 for text files."),
+    offset: z.number().optional().describe("Line number to start reading from (1-indexed). If omitted, starts from line 1."),
+    limit: z.number().optional().describe("Maximum number of lines to read. If omitted, reads to the end of the file."),
+    showLineNumbers: z.boolean().optional().default(true).describe("Whether to prefix each line with its line number (default: true)")
+  }),
+  execute: async ({ path: path4, encoding, offset, limit, showLineNumbers }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.READ_FILE);
+    const effectiveEncoding = encoding ?? "utf-8";
+    const fullContent = await filesystem.readFile(path4, { encoding: effectiveEncoding });
+    const stat3 = await filesystem.stat(path4);
+    const isTextEncoding = !encoding || encoding === "utf-8" || encoding === "utf8";
+    if (!isTextEncoding) {
+      return `${stat3.path} (${stat3.size} bytes, ${effectiveEncoding})
+${fullContent}`;
+    }
+    if (typeof fullContent !== "string") {
+      return `${stat3.path} (${stat3.size} bytes, base64)
+${fullContent.toString("base64")}`;
+    }
+    const hasLineRange = offset !== void 0 || limit !== void 0;
+    const result = extractLinesWithLimit(fullContent, offset, limit);
+    const shouldShowLineNumbers = showLineNumbers !== false;
+    const formattedContent = shouldShowLineNumbers ? formatWithLineNumbers(result.content, result.lines.start) : result.content;
+    let header;
+    if (hasLineRange) {
+      header = `${stat3.path} (lines ${result.lines.start}-${result.lines.end} of ${result.totalLines}, ${stat3.size} bytes)`;
+    } else {
+      header = `${stat3.path} (${stat3.size} bytes)`;
+    }
+    return `${header}
+${formattedContent}`;
+  }
+});
+var searchTool = createTool({
+  id: WORKSPACE_TOOLS.SEARCH.SEARCH,
+  description: "Search indexed content in the workspace. Supports keyword (BM25), semantic (vector), and hybrid search modes.",
+  inputSchema: z.object({
+    query: z.string().describe("The search query string"),
+    topK: z.number().optional().default(5).describe("Maximum number of results to return"),
+    mode: z.enum(["bm25", "vector", "hybrid"]).optional().describe("Search mode: bm25 for keyword search, vector for semantic search, hybrid for both combined"),
+    minScore: z.number().optional().describe("Minimum score threshold (0-1 for normalized scores)")
+  }),
+  execute: async ({ query, topK, mode, minScore }, context) => {
+    const workspace = requireWorkspace(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SEARCH.SEARCH);
+    const results = await workspace.search(query, {
+      topK,
+      mode,
+      minScore
+    });
+    const effectiveMode = mode ?? (workspace.canHybrid ? "hybrid" : workspace.canVector ? "vector" : "bm25");
+    const lines = results.map((r) => {
+      const lineInfo = r.lineRange ? `:${r.lineRange.start}-${r.lineRange.end}` : "";
+      return `${r.id}${lineInfo}: ${r.content}`;
+    });
+    lines.push("---");
+    lines.push(`${results.length} result${results.length !== 1 ? "s" : ""} (${effectiveMode} search)`);
+    return lines.join("\n");
+  }
+});
+var writeFileTool = createTool({
+  id: WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE,
+  description: "Write content to a file in the workspace filesystem. Creates parent directories if needed.",
+  inputSchema: z.object({
+    path: z.string().describe('The path where to write the file (e.g., "/data/output.txt")'),
+    content: z.string().describe("The content to write to the file"),
+    overwrite: z.boolean().optional().default(true).describe("Whether to overwrite the file if it already exists")
+  }),
+  execute: async ({ path: path4, content, overwrite }, context) => {
+    const { filesystem } = requireFilesystem(context);
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE);
+    if (filesystem.readOnly) {
+      throw new WorkspaceReadOnlyError("write_file");
+    }
+    await filesystem.writeFile(path4, content, { overwrite });
+    const size = Buffer.byteLength(content, "utf-8");
+    return `Wrote ${size} bytes to ${path4}`;
+  }
+});
+
 // src/workspace/tools/tools.ts
 function resolveToolConfig(toolsConfig, toolName) {
   let enabled = true;
@@ -4206,6 +5398,49 @@ function resolveToolConfig(toolsConfig, toolName) {
   }
   return { enabled, requireApproval, requireReadBeforeWrite };
 }
+function wrapTool(tool, workspace, config) {
+  return {
+    ...tool,
+    requireApproval: config.requireApproval,
+    execute: async (input, context = {}) => {
+      const enrichedContext = { ...context, workspace: context?.workspace ?? workspace };
+      return tool.execute(input, enrichedContext);
+    }
+  };
+}
+function wrapWithReadTracker(tool, workspace, readTracker, config, mode) {
+  return {
+    ...tool,
+    requireApproval: config.requireApproval,
+    execute: async (input, context = {}) => {
+      const enrichedContext = { ...context, workspace: context?.workspace ?? workspace };
+      if (mode === "write" && config.requireReadBeforeWrite) {
+        try {
+          const stat3 = await workspace.filesystem.stat(input.path);
+          const check = readTracker.needsReRead(input.path, stat3.modifiedAt);
+          if (check.needsReRead) {
+            throw new FileReadRequiredError(input.path, check.reason);
+          }
+        } catch (error) {
+          if (!(error instanceof FileNotFoundError)) {
+            throw error;
+          }
+        }
+      }
+      const result = await tool.execute(input, enrichedContext);
+      if (mode === "read") {
+        try {
+          const stat3 = await workspace.filesystem.stat(input.path);
+          readTracker.recordRead(input.path, stat3.modifiedAt);
+        } catch {
+        }
+      } else if (mode === "write") {
+        readTracker.clearReadRecord(input.path);
+      }
+      return result;
+    }
+  };
+}
 function createWorkspaceTools(workspace) {
   const tools = {};
   const toolsConfig = workspace.getToolsConfig();
@@ -4216,498 +5451,53 @@ function createWorkspaceTools(workspace) {
   if (writeFileConfig.requireReadBeforeWrite || editFileConfig.requireReadBeforeWrite) {
     readTracker = new InMemoryFileReadTracker();
   }
-  if (workspace.filesystem) {
-    const readFileConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.READ_FILE);
-    if (readFileConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.READ_FILE] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.READ_FILE,
-        description: "Read the contents of a file from the workspace filesystem. Use offset/limit parameters to read specific line ranges for large files.",
-        requireApproval: readFileConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe('The path to the file to read (e.g., "/data/config.json")'),
-          encoding: z.enum(["utf-8", "utf8", "base64", "hex", "binary"]).optional().describe("The encoding to use when reading the file. Defaults to utf-8 for text files."),
-          offset: z.number().optional().describe("Line number to start reading from (1-indexed). If omitted, starts from line 1."),
-          limit: z.number().optional().describe("Maximum number of lines to read. If omitted, reads to the end of the file."),
-          showLineNumbers: z.boolean().optional().default(true).describe("Whether to prefix each line with its line number (default: true)")
-        }),
-        outputSchema: z.object({
-          content: z.string().describe("The file contents (with optional line number prefixes)"),
-          size: z.number().describe("The file size in bytes"),
-          path: z.string().describe("The full path to the file"),
-          lines: z.object({
-            start: z.number().describe("First line number returned"),
-            end: z.number().describe("Last line number returned")
-          }).optional().describe("Line range information (when offset/limit used)"),
-          totalLines: z.number().optional().describe("Total number of lines in the file")
-        }),
-        execute: async ({ path: path4, encoding, offset, limit, showLineNumbers }) => {
-          const effectiveEncoding = encoding ?? "utf-8";
-          const fullContent = await workspace.filesystem.readFile(path4, {
-            encoding: effectiveEncoding
-          });
-          const stat3 = await workspace.filesystem.stat(path4);
-          if (readTracker) {
-            readTracker.recordRead(path4, stat3.modifiedAt);
-          }
-          const isTextEncoding = !encoding || encoding === "utf-8" || encoding === "utf8";
-          if (!isTextEncoding) {
-            return {
-              content: fullContent,
-              size: stat3.size,
-              path: stat3.path
-            };
-          }
-          if (typeof fullContent !== "string") {
-            return {
-              content: fullContent.toString("base64"),
-              size: stat3.size,
-              path: stat3.path
-            };
-          }
-          const hasLineRange = offset !== void 0 || limit !== void 0;
-          const result = extractLinesWithLimit(fullContent, offset, limit);
-          const shouldShowLineNumbers = showLineNumbers !== false;
-          const formattedContent = shouldShowLineNumbers ? formatWithLineNumbers(result.content, result.lines.start) : result.content;
-          return {
-            content: formattedContent,
-            size: stat3.size,
-            path: stat3.path,
-            ...hasLineRange && {
-              lines: result.lines,
-              totalLines: result.totalLines
-            }
-          };
-        }
-      });
-    }
-    if (!isReadOnly && writeFileConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE,
-        description: "Write content to a file in the workspace filesystem. Creates parent directories if needed.",
-        requireApproval: writeFileConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe('The path where to write the file (e.g., "/data/output.txt")'),
-          content: z.string().describe("The content to write to the file"),
-          overwrite: z.boolean().optional().default(true).describe("Whether to overwrite the file if it already exists")
-        }),
-        outputSchema: z.object({
-          success: z.boolean(),
-          path: z.string().describe("The path where the file was written"),
-          size: z.number().describe("The size of the written content in bytes")
-        }),
-        execute: async ({ path: path4, content, overwrite }) => {
-          if (readTracker && writeFileConfig.requireReadBeforeWrite) {
-            try {
-              const stat3 = await workspace.filesystem.stat(path4);
-              const check = readTracker.needsReRead(path4, stat3.modifiedAt);
-              if (check.needsReRead) {
-                throw new FileReadRequiredError(path4, check.reason);
-              }
-            } catch (error) {
-              if (!(error instanceof FileNotFoundError)) {
-                throw error;
-              }
-            }
-          }
-          await workspace.filesystem.writeFile(path4, content, { overwrite });
-          if (readTracker) {
-            readTracker.clearReadRecord(path4);
-          }
-          return {
-            success: true,
-            path: path4,
-            size: Buffer.byteLength(content, "utf-8")
-          };
-        }
-      });
-    }
-    if (!isReadOnly && editFileConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE,
-        description: `Edit a file by replacing specific text. The old_string must match exactly and be unique in the file.
-
-Usage:
-- Read the file first to get the exact text to replace.
-- By default, ${WORKSPACE_TOOLS.FILESYSTEM.READ_FILE} output includes line number prefixes (e.g., "     1\u2192"). Ensure you preserve the exact indentation as it appears AFTER the arrow. Never include any part of the line number prefix in old_string or new_string.
-- Include enough surrounding context (multiple lines) to make old_string unique. If it still isn't unique, include more lines.
-- Use replace_all only when intentionally replacing all occurrences.`,
-        requireApproval: editFileConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe("The path to the file to edit"),
-          old_string: z.string().describe("The exact text to find and replace. Must be unique in the file."),
-          new_string: z.string().describe("The text to replace old_string with"),
-          replace_all: z.boolean().optional().default(false).describe("If true, replace all occurrences. If false (default), old_string must be unique.")
-        }),
-        outputSchema: z.object({
-          success: z.boolean(),
-          path: z.string().describe("The path to the edited file"),
-          replacements: z.number().describe("Number of replacements made"),
-          error: z.string().optional().describe("Error message if the edit failed")
-        }),
-        execute: async ({ path: path4, old_string, new_string, replace_all }) => {
-          try {
-            if (readTracker && editFileConfig.requireReadBeforeWrite) {
-              const stat3 = await workspace.filesystem.stat(path4);
-              const check = readTracker.needsReRead(path4, stat3.modifiedAt);
-              if (check.needsReRead) {
-                throw new FileReadRequiredError(path4, check.reason);
-              }
-            }
-            const content = await workspace.filesystem.readFile(path4, { encoding: "utf-8" });
-            if (typeof content !== "string") {
-              return {
-                success: false,
-                path: path4,
-                replacements: 0,
-                error: "Cannot edit binary files. Use workspace_write_file instead."
-              };
-            }
-            const result = replaceString(content, old_string, new_string, replace_all);
-            await workspace.filesystem.writeFile(path4, result.content, { overwrite: true });
-            if (readTracker) {
-              readTracker.clearReadRecord(path4);
-            }
-            return {
-              success: true,
-              path: path4,
-              replacements: result.replacements
-            };
-          } catch (error) {
-            if (error instanceof FileReadRequiredError) {
-              throw error;
-            }
-            if (error instanceof StringNotFoundError) {
-              return {
-                success: false,
-                path: path4,
-                replacements: 0,
-                error: error.message
-              };
-            }
-            if (error instanceof StringNotUniqueError) {
-              return {
-                success: false,
-                path: path4,
-                replacements: 0,
-                error: error.message
-              };
-            }
-            throw error;
-          }
-        }
-      });
-    }
-    const listFilesConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES);
-    if (listFilesConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES,
-        description: `List files and directories in the workspace filesystem.
-Returns a tree-style view (like the Unix "tree" command) for easy visualization.
-The output is displayed to the user as a tree-like structure in the tool result.
-Options mirror common tree command flags for familiarity.
-
-Examples:
-- List root: { path: "/" }
-- Deep listing: { path: "/src", maxDepth: 5 }
-- Directories only: { path: "/", dirsOnly: true }
-- Exclude node_modules: { path: "/", exclude: "node_modules" }`,
-        requireApproval: listFilesConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().default("/").describe("Directory path to list"),
-          maxDepth: z.number().optional().default(3).describe("Maximum depth to descend (default: 3). Similar to tree -L flag."),
-          showHidden: z.boolean().optional().default(false).describe('Show hidden files starting with "." (default: false). Similar to tree -a flag.'),
-          dirsOnly: z.boolean().optional().default(false).describe("List directories only, no files (default: false). Similar to tree -d flag."),
-          exclude: z.string().optional().describe('Pattern to exclude (e.g., "node_modules"). Similar to tree -I flag.'),
-          extension: z.string().optional().describe('Filter by file extension (e.g., ".ts"). Similar to tree -P flag.')
-        }),
-        outputSchema: z.object({
-          tree: z.string().describe("Tree-style directory listing"),
-          summary: z.string().describe('Summary of directories and files (e.g., "3 directories, 12 files")'),
-          metadata: z.object({
-            workspace: z.object({
-              id: z.string().optional(),
-              name: z.string().optional()
-            }).optional(),
-            filesystem: z.object({
-              id: z.string().optional(),
-              name: z.string().optional(),
-              provider: z.string().optional()
-            }).optional()
-          }).optional().describe("Metadata about the workspace and filesystem")
-        }),
-        execute: async ({ path: path4 = "/", maxDepth = 3, showHidden, dirsOnly, exclude, extension }) => {
-          const result = await formatAsTree(workspace.filesystem, path4, {
-            maxDepth,
-            showHidden,
-            dirsOnly,
-            exclude: exclude || void 0,
-            extension: extension || void 0
-          });
-          const fs5 = workspace.filesystem;
-          const metadata = {
-            workspace: {
-              id: workspace.id,
-              name: workspace.name
-            },
-            filesystem: {
-              id: fs5.id,
-              name: fs5.name,
-              provider: fs5.provider
-            }
-          };
-          return {
-            tree: result.tree,
-            summary: result.summary,
-            metadata
-          };
-        }
-      });
-    }
-    const deleteConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.DELETE);
-    if (!isReadOnly && deleteConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.DELETE] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.DELETE,
-        description: "Delete a file or directory from the workspace filesystem",
-        requireApproval: deleteConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe("The path to the file or directory to delete"),
-          recursive: z.boolean().optional().default(false).describe(
-            "If true, delete directories and their contents recursively. Required for non-empty directories."
-          )
-        }),
-        outputSchema: z.object({
-          success: z.boolean(),
-          path: z.string()
-        }),
-        execute: async ({ path: path4, recursive }) => {
-          const stat3 = await workspace.filesystem.stat(path4);
-          if (stat3.type === "directory") {
-            await workspace.filesystem.rmdir(path4, { recursive, force: recursive });
-          } else {
-            await workspace.filesystem.deleteFile(path4);
-          }
-          return { success: true, path: path4 };
-        }
-      });
-    }
-    const fileStatConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT);
-    if (fileStatConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT,
-        description: "Get file or directory metadata from the workspace. Returns existence, type, size, and modification time.",
-        requireApproval: fileStatConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe("The path to check")
-        }),
-        outputSchema: z.object({
-          exists: z.boolean().describe("Whether the path exists"),
-          type: z.enum(["file", "directory", "none"]).describe("The type of the path if it exists"),
-          size: z.number().optional().describe("Size in bytes (for files)"),
-          modifiedAt: z.string().optional().describe("Last modification time (ISO string)")
-        }),
-        execute: async ({ path: path4 }) => {
-          try {
-            const stat3 = await workspace.filesystem.stat(path4);
-            return {
-              exists: true,
-              type: stat3.type,
-              size: stat3.size,
-              modifiedAt: stat3.modifiedAt.toISOString()
-            };
-          } catch (error) {
-            if (error instanceof FileNotFoundError) {
-              return { exists: false, type: "none" };
-            }
-            throw error;
-          }
-        }
-      });
-    }
-    const mkdirConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.MKDIR);
-    if (!isReadOnly && mkdirConfig.enabled) {
-      tools[WORKSPACE_TOOLS.FILESYSTEM.MKDIR] = createTool({
-        id: WORKSPACE_TOOLS.FILESYSTEM.MKDIR,
-        description: "Create a directory in the workspace filesystem",
-        requireApproval: mkdirConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe("The path of the directory to create"),
-          recursive: z.boolean().optional().default(true).describe("Whether to create parent directories if they do not exist")
-        }),
-        outputSchema: z.object({
-          success: z.boolean(),
-          path: z.string()
-        }),
-        execute: async ({ path: path4, recursive }) => {
-          await workspace.filesystem.mkdir(path4, { recursive });
-          return { success: true, path: path4 };
-        }
-      });
+  const addTool = (name, tool, opts) => {
+    const config = resolveToolConfig(toolsConfig, name);
+    if (!config.enabled) return;
+    if (opts?.requireWrite && isReadOnly) return;
+    if (readTracker && opts?.readTrackerMode) {
+      tools[name] = wrapWithReadTracker(tool, workspace, readTracker, config, opts.readTrackerMode);
+    } else {
+      tools[name] = wrapTool(tool, workspace, config);
     }
+  };
+  if (workspace.filesystem) {
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.READ_FILE, readFileTool, { readTrackerMode: "read" });
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE, writeFileTool, {
+      requireWrite: true,
+      readTrackerMode: "write"
+    });
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE, editFileTool, {
+      requireWrite: true,
+      readTrackerMode: "write"
+    });
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES, listFilesTool);
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.DELETE, deleteFileTool, { requireWrite: true });
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT, fileStatTool);
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.MKDIR, mkdirTool, { requireWrite: true });
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.GREP, grepTool);
   }
   if (workspace.canBM25 || workspace.canVector) {
-    const searchConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.SEARCH.SEARCH);
-    if (searchConfig.enabled) {
-      tools[WORKSPACE_TOOLS.SEARCH.SEARCH] = createTool({
-        id: WORKSPACE_TOOLS.SEARCH.SEARCH,
-        description: "Search indexed content in the workspace. Supports keyword (BM25), semantic (vector), and hybrid search modes.",
-        requireApproval: searchConfig.requireApproval,
-        inputSchema: z.object({
-          query: z.string().describe("The search query string"),
-          topK: z.number().optional().default(5).describe("Maximum number of results to return"),
-          mode: z.enum(["bm25", "vector", "hybrid"]).optional().describe("Search mode: bm25 for keyword search, vector for semantic search, hybrid for both combined"),
-          minScore: z.number().optional().describe("Minimum score threshold (0-1 for normalized scores)")
-        }),
-        outputSchema: z.object({
-          results: z.array(
-            z.object({
-              id: z.string().describe("Document/file path"),
-              content: z.string().describe("The matching content"),
-              score: z.number().describe("Relevance score"),
-              lineRange: z.object({
-                start: z.number(),
-                end: z.number()
-              }).optional().describe("Line range where query terms were found")
-            })
-          ),
-          count: z.number().describe("Number of results returned"),
-          mode: z.string().describe("The search mode that was used")
-        }),
-        execute: async ({ query, topK, mode, minScore }) => {
-          const results = await workspace.search(query, {
-            topK,
-            mode,
-            minScore
-          });
-          return {
-            results: results.map((r) => ({
-              id: r.id,
-              content: r.content,
-              score: r.score,
-              lineRange: r.lineRange
-            })),
-            count: results.length,
-            mode: mode ?? (workspace.canHybrid ? "hybrid" : workspace.canVector ? "vector" : "bm25")
-          };
-        }
-      });
-    }
-    const indexConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.SEARCH.INDEX);
-    if (!isReadOnly && indexConfig.enabled) {
-      tools[WORKSPACE_TOOLS.SEARCH.INDEX] = createTool({
-        id: WORKSPACE_TOOLS.SEARCH.INDEX,
-        description: "Index content for search. The path becomes the document ID in search results.",
-        requireApproval: indexConfig.requireApproval,
-        inputSchema: z.object({
-          path: z.string().describe("The document ID/path for search results"),
-          content: z.string().describe("The text content to index"),
-          metadata: z.record(z.unknown()).optional().describe("Optional metadata to store with the document")
-        }),
-        outputSchema: z.object({
-          success: z.boolean(),
-          path: z.string().describe("The indexed document ID")
-        }),
-        execute: async ({ path: path4, content, metadata }) => {
-          await workspace.index(path4, content, { metadata });
-          return { success: true, path: path4 };
-        }
-      });
-    }
+    addTool(WORKSPACE_TOOLS.SEARCH.SEARCH, searchTool);
+    addTool(WORKSPACE_TOOLS.SEARCH.INDEX, indexContentTool, { requireWrite: true });
   }
   if (workspace.sandbox) {
-    const pathContext = workspace.getPathContext();
-    const pathInfo = pathContext.instructions ? ` ${pathContext.instructions}` : "";
     const executeCommandConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND);
     if (workspace.sandbox.executeCommand && executeCommandConfig.enabled) {
-      tools[WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND] = createTool({
-        id: WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND,
-        description: `Execute a shell command in the workspace sandbox.${pathInfo}
+      const pathContext = workspace.getPathContext();
+      const pathInfo = pathContext.instructions ? `
 
-Usage:
-- Verify parent directories exist before running commands that create files or directories.
-- Always quote file paths that contain spaces (e.g., cd "/path/with spaces").
-- Use the timeout parameter to limit execution time. Behavior when omitted depends on the sandbox provider.
-- Use cwd to set the working directory, or commands run from the sandbox default.`,
-        requireApproval: executeCommandConfig.requireApproval,
-        inputSchema: z.object({
-          command: z.string().describe('The command to execute (e.g., "ls", "npm", "python")'),
-          args: z.array(z.string()).nullish().default([]).describe("Arguments to pass to the command"),
-          timeout: z.number().nullish().describe("Maximum execution time in milliseconds. Example: 60000 for 1 minute."),
-          cwd: z.string().nullish().describe("Working directory for the command")
-        }),
-        outputSchema: z.object({
-          success: z.boolean().describe("Whether the command executed successfully (exit code 0)"),
-          stdout: z.string().describe("Standard output from the command"),
-          stderr: z.string().describe("Standard error output"),
-          exitCode: z.number().describe("Exit code (0 = success)"),
-          executionTimeMs: z.number().describe("How long the execution took in milliseconds")
-        }),
-        execute: async ({ command, args, timeout, cwd }, context) => {
-          const getExecutionMetadata = () => ({
-            workspace: {
-              id: workspace.id,
-              name: workspace.name
-            },
-            sandbox: {
-              id: workspace.sandbox?.id,
-              name: workspace.sandbox?.name,
-              provider: workspace.sandbox?.provider,
-              status: workspace.sandbox?.status
-            }
-          });
-          const startedAt = Date.now();
-          try {
-            const result = await workspace.sandbox.executeCommand(command, args ?? [], {
-              timeout: timeout ?? void 0,
-              cwd: cwd ?? void 0,
-              // Stream stdout/stderr as tool-output chunks for proper UI integration
-              onStdout: async (data) => {
-                await context?.writer?.write({
-                  type: "sandbox-stdout",
-                  data,
-                  timestamp: Date.now(),
-                  metadata: getExecutionMetadata()
-                });
-              },
-              onStderr: async (data) => {
-                await context?.writer?.write({
-                  type: "sandbox-stderr",
-                  data,
-                  timestamp: Date.now(),
-                  metadata: getExecutionMetadata()
-                });
-              }
-            });
-            await context?.writer?.write({
-              type: "sandbox-exit",
-              exitCode: result.exitCode,
-              success: result.success,
-              executionTimeMs: result.executionTimeMs,
-              metadata: getExecutionMetadata()
-            });
-            return {
-              success: result.success,
-              stdout: result.stdout,
-              stderr: result.stderr,
-              exitCode: result.exitCode,
-              executionTimeMs: result.executionTimeMs
-            };
-          } catch (error) {
-            await context?.writer?.write({
-              type: "sandbox-exit",
-              exitCode: -1,
-              success: false,
-              executionTimeMs: Date.now() - startedAt,
-              metadata: getExecutionMetadata()
-            });
-            throw error;
-          }
-        }
-      });
+${pathContext.instructions}` : "";
+      const description = pathInfo ? `${executeCommandTool.description}${pathInfo}` : executeCommandTool.description;
+      tools[WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND] = {
+        ...wrapTool(executeCommandTool, workspace, executeCommandConfig),
+        description
+      };
     }
   }
   return tools;
 }
 
-export { BM25Index, CompositeFilesystem, DirectoryNotEmptyError, DirectoryNotFoundError, FileExistsError, FileNotFoundError, FileReadRequiredError, FilesystemError, FilesystemNotAvailableError, FilesystemNotMountableError, FilesystemNotReadyError, IsDirectoryError, IsolationUnavailableError, LocalFilesystem, LocalSandbox, MastraFilesystem, MastraSandbox, MountError, MountManager, MountNotSupportedError, NotDirectoryError, PermissionError, SandboxError, SandboxExecutionError, SandboxFeatureNotSupportedError, SandboxNotAvailableError, SandboxNotReadyError, SandboxTimeoutError, SearchNotAvailableError, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, Workspace, WorkspaceError, WorkspaceNotReadyError, WorkspaceReadOnlyError, callLifecycle, createWorkspaceTools, detectIsolation, extractLines, getRecommendedIsolation, isIsolationAvailable, resolveToolConfig };
-//# sourceMappingURL=chunk-4EHGOATH.js.map
-//# sourceMappingURL=chunk-4EHGOATH.js.map
+export { BM25Index, CompositeFilesystem, CompositeVersionedSkillSource, DirectoryNotEmptyError, DirectoryNotFoundError, FileExistsError, FileNotFoundError, FileReadRequiredError, FilesystemError, FilesystemNotAvailableError, FilesystemNotMountableError, FilesystemNotReadyError, IsDirectoryError, IsolationUnavailableError, LocalFilesystem, LocalSandbox, LocalSkillSource, MastraFilesystem, MastraSandbox, MountError, MountManager, MountNotSupportedError, NotDirectoryError, PermissionError, SandboxError, SandboxExecutionError, SandboxFeatureNotSupportedError, SandboxNotAvailableError, SandboxNotReadyError, SandboxTimeoutError, SearchNotAvailableError, VersionedSkillSource, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, Workspace, WorkspaceError, WorkspaceNotAvailableError, WorkspaceNotReadyError, WorkspaceReadOnlyError, callLifecycle, collectSkillForPublish, createGlobMatcher, createWorkspaceTools, deleteFileTool, detectIsolation, editFileTool, executeCommandTool, extractGlobBase, extractLines, fileStatTool, getRecommendedIsolation, indexContentTool, isGlobPattern, isIsolationAvailable, listFilesTool, matchGlob, mkdirTool, publishSkillFromSource, readFileTool, requireFilesystem, requireSandbox, requireWorkspace, resolveToolConfig, searchTool, writeFileTool };
+//# sourceMappingURL=chunk-FZ5DRHKE.js.map
+//# sourceMappingURL=chunk-FZ5DRHKE.js.map