@dexto/tools-filesystem 1.5.2 → 1.5.4

package/dist/edit-file-tool.js

@@ -1,10 +1,16 @@
 import * as path from "node:path";
+import { createHash } from "node:crypto";
 import { z } from "zod";
 import { createPatch } from "diff";
 import { ApprovalType } from "@dexto/core";
 import { ToolError } from "@dexto/core";
 import { ToolErrorCode } from "@dexto/core";
 import { DextoRuntimeError } from "@dexto/core";
+import { FileSystemErrorCode } from "./error-codes.js";
+const previewContentHashCache = /* @__PURE__ */ new Map();
+function computeContentHash(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
 const EditFileInputSchema = z.object({
   file_path: z.string().describe("Absolute path to the file to edit"),
   old_string: z.string().describe("Text to replace (must be unique unless replace_all is true)"),
@@ -36,10 +42,10 @@ function createEditFileTool(options) {
      * Check if this edit operation needs directory access approval.
      * Returns custom approval request if the file is outside allowed paths.
      */
-    getApprovalOverride: (args) => {
+    getApprovalOverride: async (args) => {
       const { file_path } = args;
       if (!file_path) return null;
-      const isAllowed = fileSystemService.isPathWithinConfigAllowed(file_path);
+      const isAllowed = await fileSystemService.isPathWithinConfigAllowed(file_path);
       if (isAllowed) {
         return null;
       }
@@ -75,12 +81,19 @@ function createEditFileTool(options) {
     /**
      * Generate preview for approval UI - shows diff without modifying file
      * Throws ToolError.validationFailed() for validation errors (file not found, string not found)
+     * Stores content hash for change detection in execute phase.
      */
-    generatePreview: async (input, _context) => {
+    generatePreview: async (input, context) => {
       const { file_path, old_string, new_string, replace_all } = input;
       try {
         const originalFile = await fileSystemService.readFile(file_path);
         const originalContent = originalFile.content;
+        if (context?.toolCallId) {
+          previewContentHashCache.set(
+            context.toolCallId,
+            computeContentHash(originalContent)
+          );
+        }
         if (!replace_all) {
           const occurrences = originalContent.split(old_string).length - 1;
           if (occurrences > 1) {
@@ -113,25 +126,36 @@ function createEditFileTool(options) {
         return null;
       }
     },
-    execute: async (input, _context) => {
+    execute: async (input, context) => {
       const { file_path, old_string, new_string, replace_all } = input;
-      const originalFile = await fileSystemService.readFile(file_path);
-      const originalContent = originalFile.content;
-      const result = await fileSystemService.editFile(
-        file_path,
-        {
-          oldString: old_string,
-          newString: new_string,
-          replaceAll: replace_all
-        },
-        {
-          backup: true
-          // Always create backup for internal tools
+      if (context?.toolCallId && previewContentHashCache.has(context.toolCallId)) {
+        const expectedHash = previewContentHashCache.get(context.toolCallId);
+        previewContentHashCache.delete(context.toolCallId);
+        let currentContent;
+        try {
+          const currentFile = await fileSystemService.readFile(file_path);
+          currentContent = currentFile.content;
+        } catch (error) {
+          if (error instanceof DextoRuntimeError && error.code === FileSystemErrorCode.FILE_NOT_FOUND) {
+            throw ToolError.fileModifiedSincePreview("edit_file", file_path);
+          }
+          throw error;
+        }
+        const currentHash = computeContentHash(currentContent);
+        if (expectedHash !== currentHash) {
+          throw ToolError.fileModifiedSincePreview("edit_file", file_path);
         }
+      }
+      const result = await fileSystemService.editFile(file_path, {
+        oldString: old_string,
+        newString: new_string,
+        replaceAll: replace_all
+      });
+      const _display = generateDiffPreview(
+        file_path,
+        result.originalContent,
+        result.newContent
       );
-      const newFile = await fileSystemService.readFile(file_path);
-      const newContent = newFile.content;
-      const _display = generateDiffPreview(file_path, originalContent, newContent);
       return {
         success: result.success,
         path: result.path,

package/dist/edit-file-tool.test.cjs

@@ -0,0 +1,203 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_vitest = require("vitest");
+var path = __toESM(require("node:path"), 1);
+var fs = __toESM(require("node:fs/promises"), 1);
+var os = __toESM(require("node:os"), 1);
+var import_edit_file_tool = require("./edit-file-tool.js");
+var import_filesystem_service = require("./filesystem-service.js");
+var import_core = require("@dexto/core");
+var import_core2 = require("@dexto/core");
+const createMockLogger = () => ({
+  debug: import_vitest.vi.fn(),
+  info: import_vitest.vi.fn(),
+  warn: import_vitest.vi.fn(),
+  error: import_vitest.vi.fn(),
+  createChild: import_vitest.vi.fn().mockReturnThis()
+});
+(0, import_vitest.describe)("edit_file tool", () => {
+  let mockLogger;
+  let tempDir;
+  let fileSystemService;
+  (0, import_vitest.beforeEach)(async () => {
+    mockLogger = createMockLogger();
+    const rawTempDir = await fs.mkdtemp(path.join(os.tmpdir(), "dexto-edit-test-"));
+    tempDir = await fs.realpath(rawTempDir);
+    fileSystemService = new import_filesystem_service.FileSystemService(
+      {
+        allowedPaths: [tempDir],
+        blockedPaths: [],
+        blockedExtensions: [],
+        maxFileSize: 10 * 1024 * 1024,
+        workingDirectory: tempDir,
+        enableBackups: false,
+        backupRetentionDays: 7
+      },
+      mockLogger
+    );
+    await fileSystemService.initialize();
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.afterEach)(async () => {
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch {
+    }
+  });
+  (0, import_vitest.describe)("File Modification Detection", () => {
+    (0, import_vitest.it)("should succeed when file is not modified between preview and execute", async () => {
+      const tool = (0, import_edit_file_tool.createEditFileTool)({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-123";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      const preview = await tool.generatePreview(input, { toolCallId });
+      (0, import_vitest.expect)(preview).toBeDefined();
+      const result = await tool.execute(input, { toolCallId });
+      (0, import_vitest.expect)(result.success).toBe(true);
+      (0, import_vitest.expect)(result.path).toBe(testFile);
+      const content = await fs.readFile(testFile, "utf-8");
+      (0, import_vitest.expect)(content).toBe("hello universe");
+    });
+    (0, import_vitest.it)("should fail when file is modified between preview and execute", async () => {
+      const tool = (0, import_edit_file_tool.createEditFileTool)({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-456";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      const preview = await tool.generatePreview(input, { toolCallId });
+      (0, import_vitest.expect)(preview).toBeDefined();
+      await fs.writeFile(testFile, "hello world - user added this");
+      try {
+        await tool.execute(input, { toolCallId });
+        import_vitest.expect.fail("Should have thrown an error");
+      } catch (error) {
+        (0, import_vitest.expect)(error).toBeInstanceOf(import_core2.DextoRuntimeError);
+        (0, import_vitest.expect)(error.code).toBe(
+          import_core.ToolErrorCode.FILE_MODIFIED_SINCE_PREVIEW
+        );
+      }
+      const content = await fs.readFile(testFile, "utf-8");
+      (0, import_vitest.expect)(content).toBe("hello world - user added this");
+    });
+    (0, import_vitest.it)("should detect file modification with correct error code", async () => {
+      const tool = (0, import_edit_file_tool.createEditFileTool)({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-789";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, { toolCallId });
+      await fs.writeFile(testFile, "hello world modified");
+      try {
+        await tool.execute(input, { toolCallId });
+        import_vitest.expect.fail("Should have thrown an error");
+      } catch (error) {
+        (0, import_vitest.expect)(error).toBeInstanceOf(import_core2.DextoRuntimeError);
+        (0, import_vitest.expect)(error.code).toBe(
+          import_core.ToolErrorCode.FILE_MODIFIED_SINCE_PREVIEW
+        );
+        (0, import_vitest.expect)(error.message).toContain(
+          "modified since the preview"
+        );
+        (0, import_vitest.expect)(error.message).toContain("read the file again");
+      }
+    });
+    (0, import_vitest.it)("should work without toolCallId (no modification check)", async () => {
+      const tool = (0, import_edit_file_tool.createEditFileTool)({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, {});
+      await fs.writeFile(testFile, "hello world changed");
+      try {
+        await tool.execute(input, {});
+      } catch (error) {
+        (0, import_vitest.expect)(error).toBeInstanceOf(import_core2.DextoRuntimeError);
+        (0, import_vitest.expect)(error.code).not.toBe(
+          import_core.ToolErrorCode.FILE_MODIFIED_SINCE_PREVIEW
+        );
+      }
+    });
+    (0, import_vitest.it)("should clean up hash cache after successful execution", async () => {
+      const tool = (0, import_edit_file_tool.createEditFileTool)({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-cleanup";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, { toolCallId });
+      await tool.execute(input, { toolCallId });
+      const input2 = {
+        file_path: testFile,
+        old_string: "universe",
+        new_string: "galaxy"
+      };
+      await tool.generatePreview(input2, { toolCallId });
+      const result = await tool.execute(input2, { toolCallId });
+      (0, import_vitest.expect)(result.success).toBe(true);
+      const content = await fs.readFile(testFile, "utf-8");
+      (0, import_vitest.expect)(content).toBe("hello galaxy");
+    });
+    (0, import_vitest.it)("should clean up hash cache after failed execution", async () => {
+      const tool = (0, import_edit_file_tool.createEditFileTool)({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-fail-cleanup";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, { toolCallId });
+      await fs.writeFile(testFile, "hello world modified");
+      try {
+        await tool.execute(input, { toolCallId });
+      } catch {
+      }
+      await fs.writeFile(testFile, "hello world");
+      await tool.generatePreview(input, { toolCallId });
+      const result = await tool.execute(input, { toolCallId });
+      (0, import_vitest.expect)(result.success).toBe(true);
+    });
+  });
+});

package/dist/edit-file-tool.test.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/edit-file-tool.test.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/edit-file-tool.test.js

@@ -0,0 +1,180 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import { createEditFileTool } from "./edit-file-tool.js";
+import { FileSystemService } from "./filesystem-service.js";
+import { ToolErrorCode } from "@dexto/core";
+import { DextoRuntimeError } from "@dexto/core";
+const createMockLogger = () => ({
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  createChild: vi.fn().mockReturnThis()
+});
+describe("edit_file tool", () => {
+  let mockLogger;
+  let tempDir;
+  let fileSystemService;
+  beforeEach(async () => {
+    mockLogger = createMockLogger();
+    const rawTempDir = await fs.mkdtemp(path.join(os.tmpdir(), "dexto-edit-test-"));
+    tempDir = await fs.realpath(rawTempDir);
+    fileSystemService = new FileSystemService(
+      {
+        allowedPaths: [tempDir],
+        blockedPaths: [],
+        blockedExtensions: [],
+        maxFileSize: 10 * 1024 * 1024,
+        workingDirectory: tempDir,
+        enableBackups: false,
+        backupRetentionDays: 7
+      },
+      mockLogger
+    );
+    await fileSystemService.initialize();
+    vi.clearAllMocks();
+  });
+  afterEach(async () => {
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch {
+    }
+  });
+  describe("File Modification Detection", () => {
+    it("should succeed when file is not modified between preview and execute", async () => {
+      const tool = createEditFileTool({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-123";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      const preview = await tool.generatePreview(input, { toolCallId });
+      expect(preview).toBeDefined();
+      const result = await tool.execute(input, { toolCallId });
+      expect(result.success).toBe(true);
+      expect(result.path).toBe(testFile);
+      const content = await fs.readFile(testFile, "utf-8");
+      expect(content).toBe("hello universe");
+    });
+    it("should fail when file is modified between preview and execute", async () => {
+      const tool = createEditFileTool({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-456";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      const preview = await tool.generatePreview(input, { toolCallId });
+      expect(preview).toBeDefined();
+      await fs.writeFile(testFile, "hello world - user added this");
+      try {
+        await tool.execute(input, { toolCallId });
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(DextoRuntimeError);
+        expect(error.code).toBe(
+          ToolErrorCode.FILE_MODIFIED_SINCE_PREVIEW
+        );
+      }
+      const content = await fs.readFile(testFile, "utf-8");
+      expect(content).toBe("hello world - user added this");
+    });
+    it("should detect file modification with correct error code", async () => {
+      const tool = createEditFileTool({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-789";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, { toolCallId });
+      await fs.writeFile(testFile, "hello world modified");
+      try {
+        await tool.execute(input, { toolCallId });
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(DextoRuntimeError);
+        expect(error.code).toBe(
+          ToolErrorCode.FILE_MODIFIED_SINCE_PREVIEW
+        );
+        expect(error.message).toContain(
+          "modified since the preview"
+        );
+        expect(error.message).toContain("read the file again");
+      }
+    });
+    it("should work without toolCallId (no modification check)", async () => {
+      const tool = createEditFileTool({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, {});
+      await fs.writeFile(testFile, "hello world changed");
+      try {
+        await tool.execute(input, {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(DextoRuntimeError);
+        expect(error.code).not.toBe(
+          ToolErrorCode.FILE_MODIFIED_SINCE_PREVIEW
+        );
+      }
+    });
+    it("should clean up hash cache after successful execution", async () => {
+      const tool = createEditFileTool({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-cleanup";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, { toolCallId });
+      await tool.execute(input, { toolCallId });
+      const input2 = {
+        file_path: testFile,
+        old_string: "universe",
+        new_string: "galaxy"
+      };
+      await tool.generatePreview(input2, { toolCallId });
+      const result = await tool.execute(input2, { toolCallId });
+      expect(result.success).toBe(true);
+      const content = await fs.readFile(testFile, "utf-8");
+      expect(content).toBe("hello galaxy");
+    });
+    it("should clean up hash cache after failed execution", async () => {
+      const tool = createEditFileTool({ fileSystemService });
+      const testFile = path.join(tempDir, "test.txt");
+      await fs.writeFile(testFile, "hello world");
+      const toolCallId = "test-call-fail-cleanup";
+      const input = {
+        file_path: testFile,
+        old_string: "world",
+        new_string: "universe"
+      };
+      await tool.generatePreview(input, { toolCallId });
+      await fs.writeFile(testFile, "hello world modified");
+      try {
+        await tool.execute(input, { toolCallId });
+      } catch {
+      }
+      await fs.writeFile(testFile, "hello world");
+      await tool.generatePreview(input, { toolCallId });
+      const result = await tool.execute(input, { toolCallId });
+      expect(result.success).toBe(true);
+    });
+  });
+});

package/dist/filesystem-service.cjs

@@ -66,6 +66,13 @@ class FileSystemService {
   getBackupDir() {
     return this.config.backupPath || (0, import_core.getDextoPath)("backups");
   }
+  /**
+   * Get the effective working directory for file operations.
+   * Falls back to process.cwd() if not configured.
+   */
+  getWorkingDirectory() {
+    return this.config.workingDirectory || process.cwd();
+  }
   /**
    * Initialize the service.
    * Safe to call multiple times - subsequent calls return the same promise.
@@ -126,7 +133,7 @@ class FileSystemService {
    * @param filePath The file path to check (can be relative or absolute)
    * @returns true if the path is within config-allowed paths, false otherwise
    */
-  isPathWithinConfigAllowed(filePath) {
+  async isPathWithinConfigAllowed(filePath) {
     return this.pathValidator.isPathWithinAllowed(filePath);
   }
   /**
@@ -134,7 +141,7 @@ class FileSystemService {
    */
   async readFile(filePath, options = {}) {
     await this.ensureInitialized();
-    const validation = this.pathValidator.validatePath(filePath);
+    const validation = await this.pathValidator.validatePath(filePath);
     if (!validation.isValid || !validation.normalizedPath) {
       throw import_errors.FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
     }
@@ -211,7 +218,7 @@ class FileSystemService {
       });
       const validFiles = [];
       for (const file of files) {
-        const validation = this.pathValidator.validatePath(file);
+        const validation = await this.pathValidator.validatePath(file);
         if (!validation.isValid || !validation.normalizedPath) {
           this.logger.debug(`Skipping invalid path: ${file}`);
           continue;
@@ -344,7 +351,7 @@ class FileSystemService {
    */
   async writeFile(filePath, content, options = {}) {
     await this.ensureInitialized();
-    const validation = this.pathValidator.validatePath(filePath);
+    const validation = await this.pathValidator.validatePath(filePath);
     if (!validation.isValid || !validation.normalizedPath) {
       throw import_errors.FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
     }
@@ -386,14 +393,14 @@ class FileSystemService {
    */
   async editFile(filePath, operation, options = {}) {
     await this.ensureInitialized();
-    const validation = this.pathValidator.validatePath(filePath);
+    const validation = await this.pathValidator.validatePath(filePath);
     if (!validation.isValid || !validation.normalizedPath) {
       throw import_errors.FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
     }
     const normalizedPath = validation.normalizedPath;
     const fileContent = await this.readFile(normalizedPath);
-    let content = fileContent.content;
-    const occurrences = (content.match(
+    const originalContent = fileContent.content;
+    const occurrences = (originalContent.match(
       new RegExp(operation.oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")
     ) || []).length;
     if (occurrences === 0) {
@@ -407,21 +414,24 @@ class FileSystemService {
       backupPath = await this.createBackup(normalizedPath);
     }
     try {
+      let newContent;
       if (operation.replaceAll) {
-        content = content.replace(
+        newContent = originalContent.replace(
           new RegExp(operation.oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"),
           operation.newString
         );
       } else {
-        content = content.replace(operation.oldString, operation.newString);
+        newContent = originalContent.replace(operation.oldString, operation.newString);
       }
-      await fs.writeFile(normalizedPath, content, options.encoding || DEFAULT_ENCODING);
+      await fs.writeFile(normalizedPath, newContent, options.encoding || DEFAULT_ENCODING);
       this.logger.debug(`File edited: ${normalizedPath} (${occurrences} replacements)`);
       return {
         success: true,
         path: normalizedPath,
         changesCount: occurrences,
-        backupPath
+        backupPath,
+        originalContent,
+        newContent
       };
     } catch (error) {
       throw import_errors.FileSystemError.editFailed(
@@ -513,10 +523,10 @@ class FileSystemService {
     return { ...this.config };
   }
   /**
-   * Check if a path is allowed
+   * Check if a path is allowed (async for non-blocking symlink resolution)
    */
-  isPathAllowed(filePath) {
-    const validation = this.pathValidator.validatePath(filePath);
+  async isPathAllowed(filePath) {
+    const validation = await this.pathValidator.validatePath(filePath);
     return validation.isValid;
   }
 }

package/dist/filesystem-service.d.cts

@@ -36,6 +36,11 @@ declare class FileSystemService {
      * TODO: Migrate to explicit configuration via CLI enrichment layer (per-agent paths)
      */
     private getBackupDir;
+    /**
+     * Get the effective working directory for file operations.
+     * Falls back to process.cwd() if not configured.
+     */
+    getWorkingDirectory(): string;
     /**
      * Initialize the service.
      * Safe to call multiple times - subsequent calls return the same promise.
@@ -65,7 +70,7 @@ declare class FileSystemService {
      * @param filePath The file path to check (can be relative or absolute)
      * @returns true if the path is within config-allowed paths, false otherwise
      */
-    isPathWithinConfigAllowed(filePath: string): boolean;
+    isPathWithinConfigAllowed(filePath: string): Promise<boolean>;
     /**
      * Read a file with validation and size limits
      */
@@ -99,9 +104,9 @@ declare class FileSystemService {
      */
     getConfig(): Readonly<FileSystemConfig>;
     /**
-     * Check if a path is allowed
+     * Check if a path is allowed (async for non-blocking symlink resolution)
      */
-    isPathAllowed(filePath: string): boolean;
+    isPathAllowed(filePath: string): Promise<boolean>;
 }
 
 export { FileSystemService };

package/dist/filesystem-service.d.ts

@@ -36,6 +36,11 @@ declare class FileSystemService {
      * TODO: Migrate to explicit configuration via CLI enrichment layer (per-agent paths)
      */
     private getBackupDir;
+    /**
+     * Get the effective working directory for file operations.
+     * Falls back to process.cwd() if not configured.
+     */
+    getWorkingDirectory(): string;
     /**
      * Initialize the service.
      * Safe to call multiple times - subsequent calls return the same promise.
@@ -65,7 +70,7 @@ declare class FileSystemService {
      * @param filePath The file path to check (can be relative or absolute)
      * @returns true if the path is within config-allowed paths, false otherwise
      */
-    isPathWithinConfigAllowed(filePath: string): boolean;
+    isPathWithinConfigAllowed(filePath: string): Promise<boolean>;
     /**
      * Read a file with validation and size limits
      */
@@ -99,9 +104,9 @@ declare class FileSystemService {
      */
     getConfig(): Readonly<FileSystemConfig>;
     /**
-     * Check if a path is allowed
+     * Check if a path is allowed (async for non-blocking symlink resolution)
      */
-    isPathAllowed(filePath: string): boolean;
+    isPathAllowed(filePath: string): Promise<boolean>;
 }
 
 export { FileSystemService };