@probelabs/probe 0.6.0-rc225 → 0.6.0-rc227

package/build/agent/ProbeAgent.js

@@ -4,6 +4,29 @@
 import dotenv from 'dotenv';
 dotenv.config();
 
+// ============================================================================
+// Timeout Configuration Constants
+// ============================================================================
+
+/**
+ * Default activity timeout for engine streams (3 minutes).
+ * This is the time allowed between stream chunks before considering the stream stalled.
+ * Conservative default to handle extended thinking models that may not stream during thinking.
+ */
+export const ENGINE_ACTIVITY_TIMEOUT_DEFAULT = 180000;
+
+/**
+ * Minimum allowed activity timeout (5 seconds).
+ * Prevents unreasonably short timeouts that could cause premature failures.
+ */
+export const ENGINE_ACTIVITY_TIMEOUT_MIN = 5000;
+
+/**
+ * Maximum allowed activity timeout (10 minutes).
+ * Prevents excessively long waits for stalled streams.
+ */
+export const ENGINE_ACTIVITY_TIMEOUT_MAX = 600000;
+
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createOpenAI } from '@ai-sdk/openai';
 import { createGoogleGenerativeAI } from '@ai-sdk/google';
@@ -71,6 +94,7 @@ import { RetryManager, createRetryManagerFromEnv } from './RetryManager.js';
 import { FallbackManager, createFallbackManagerFromEnv, buildFallbackProvidersFromEnv } from './FallbackManager.js';
 import { handleContextLimitError } from './contextCompactor.js';
 import { formatErrorForAI, ParameterError } from '../utils/error-types.js';
+import { getCommonPrefix, toRelativePath, safeRealpath } from '../utils/path-validation.js';
 import { truncateIfNeeded, getMaxOutputTokens } from './outputTruncator.js';
 import { DelegationManager } from '../delegate.js';
 import {
@@ -188,6 +212,8 @@ export class ProbeAgent {
    * @param {number} [options.fallback.maxTotalAttempts=10] - Maximum total attempts across all providers
    * @param {string} [options.completionPrompt] - Custom prompt to run after attempt_completion for validation/review (runs before mermaid/JSON validation)
    * @param {number} [options.maxOutputTokens] - Maximum tokens for tool output before truncation (default: 20000, can also be set via PROBE_MAX_OUTPUT_TOKENS env var)
+   * @param {number} [options.requestTimeout] - Timeout in ms for AI requests (default: 120000 or REQUEST_TIMEOUT env var). Used to abort hung requests.
+   * @param {number} [options.maxOperationTimeout] - Maximum timeout in ms for the entire operation including all retries and fallbacks (default: 300000 or MAX_OPERATION_TIMEOUT env var). This is the absolute maximum time for streamTextWithRetryAndFallback.
    */
   constructor(options = {}) {
     // Basic configuration
@@ -269,8 +295,15 @@ export class ProbeAgent {
       this.allowedFolders = [process.cwd()];
     }
 
-    // Working directory for resolving relative paths (separate from allowedFolders security)
-    this.cwd = options.cwd || null;
+    // Compute workspace root as common prefix of all allowed folders
+    // This provides a single "root" for relative path resolution and default cwd
+    // IMPORTANT: workspaceRoot is NOT a security boundary - all security checks
+    // must be performed against this.allowedFolders, not workspaceRoot
+    this.workspaceRoot = getCommonPrefix(this.allowedFolders);
+
+    // Working directory for resolving relative paths
+    // If not explicitly provided, use workspace root for consistency
+    this.cwd = options.cwd || this.workspaceRoot;
 
     // API configuration
     this.clientApiProvider = options.provider || null;
@@ -289,6 +322,8 @@ export class ProbeAgent {
       console.log(`[DEBUG] Maximum tool iterations configured: ${MAX_TOOL_ITERATIONS}`);
       console.log(`[DEBUG] Allow Edit (implement tool): ${this.allowEdit}`);
       console.log(`[DEBUG] Search delegation enabled: ${this.searchDelegate}`);
+      console.log(`[DEBUG] Workspace root: ${this.workspaceRoot}`);
+      console.log(`[DEBUG] Working directory (cwd): ${this.cwd}`);
     }
 
     // Initialize tools
@@ -320,6 +355,41 @@ export class ProbeAgent {
     // Each ProbeAgent instance has its own limits, not shared globally
     this.delegationManager = new DelegationManager();
 
+    // Request timeout configuration (default 2 minutes)
+    // Validates env var to prevent NaN or unreasonable values
+    this.requestTimeout = options.requestTimeout ?? (() => {
+      if (process.env.REQUEST_TIMEOUT) {
+        const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
+        // Validate: must be positive number between 1s and 1 hour
+        if (isNaN(parsed) || parsed < 1000 || parsed > 3600000) {
+          return 120000; // Default 2 minutes
+        }
+        return parsed;
+      }
+      return 120000;
+    })();
+    if (this.debug) {
+      console.log(`[DEBUG] Request timeout: ${this.requestTimeout}ms`);
+    }
+
+    // Maximum operation timeout for entire streamTextWithRetryAndFallback operation (default 5 minutes)
+    // This is the absolute maximum time including all retries and fallbacks
+    // Validates env var to prevent NaN or unreasonable values
+    this.maxOperationTimeout = options.maxOperationTimeout ?? (() => {
+      if (process.env.MAX_OPERATION_TIMEOUT) {
+        const parsed = parseInt(process.env.MAX_OPERATION_TIMEOUT, 10);
+        // Validate: must be positive number between 1s and 2 hours
+        if (isNaN(parsed) || parsed < 1000 || parsed > 7200000) {
+          return 300000; // Default 5 minutes
+        }
+        return parsed;
+      }
+      return 300000;
+    })();
+    if (this.debug) {
+      console.log(`[DEBUG] Max operation timeout: ${this.maxOperationTimeout}ms`);
+    }
+
     // Retry configuration
     this.retryConfig = options.retry || {};
     this.retryManager = null; // Will be initialized lazily when needed
@@ -732,8 +802,9 @@ export class ProbeAgent {
     const configOptions = {
       sessionId: this.sessionId,
       debug: this.debug,
-      // Use explicit cwd if set, otherwise fall back to first allowed folder
-      cwd: this.cwd || (this.allowedFolders.length > 0 ? this.allowedFolders[0] : process.cwd()),
+      // Use cwd (which defaults to workspaceRoot in constructor)
+      cwd: this.cwd,
+      workspaceRoot: this.workspaceRoot,
       allowedFolders: this.allowedFolders,
       outline: this.outline,
       searchDelegate: this.searchDelegate,
@@ -1094,120 +1165,128 @@ export class ProbeAgent {
   }
 
   /**
-   * Execute streamText with retry and fallback support
-   * @param {Object} options - streamText options
-   * @returns {Promise<Object>} - streamText result
+   * Create a streamText-compatible result from an engine stream with timeout handling
+   * @param {AsyncGenerator} engineStream - The engine's query result
+   * @param {AbortSignal} abortSignal - Signal for aborting the operation
+   * @param {number} requestTimeout - Per-request timeout in ms
+   * @param {Object} timeoutState - Object with timeoutId property (mutable for cleanup)
+   * @returns {Object} - streamText-compatible result with textStream
    * @private
    */
-  async streamTextWithRetryAndFallback(options) {
-    // Check if we should use Claude Code engine
-    if (this.clientApiProvider === 'claude-code' || process.env.USE_CLAUDE_CODE === 'true') {
+  _createEngineTextStreamResult(engineStream, abortSignal, requestTimeout, timeoutState) {
+    // Activity timeout for engine stream - validates env var against defined bounds
+    const activityTimeout = (() => {
+      const parsed = parseInt(process.env.ENGINE_ACTIVITY_TIMEOUT, 10);
+      return isNaN(parsed) || parsed < ENGINE_ACTIVITY_TIMEOUT_MIN || parsed > ENGINE_ACTIVITY_TIMEOUT_MAX
+        ? ENGINE_ACTIVITY_TIMEOUT_DEFAULT
+        : parsed;
+    })();
+    const startTime = Date.now();
+
+    // Create a text stream that extracts text from engine messages with timeout
+    // The generator clears the operation timeout when done to handle the case
+    // where the stream is returned immediately but consumed later
+    async function* createTextStream() {
+      let lastActivity = Date.now();
+
       try {
-        const engine = await this.getEngine();
-        if (engine && engine.query) {
-          // Convert Vercel AI SDK format to engine format
-          // Extract the ORIGINAL user message as the main prompt (skip any warning messages)
-          // Look for user messages that are NOT the warning message
-          const userMessages = options.messages.filter(m =>
-            m.role === 'user' &&
-            !m.content.includes('WARNING: You have reached the maximum tool iterations limit')
-          );
-          const lastUserMessage = userMessages[userMessages.length - 1];
-          const prompt = lastUserMessage ? lastUserMessage.content : '';
-
-          // Pass system message and other options
-          const engineOptions = {
-            maxTokens: options.maxTokens,
-            temperature: options.temperature,
-            messages: options.messages,
-            systemPrompt: options.messages.find(m => m.role === 'system')?.content
-          };
-
-          // Get the engine's query result (async generator)
-          const engineStream = engine.query(prompt, engineOptions);
-
-          // Create a text stream that extracts text from engine messages
-          async function* createTextStream() {
-            for await (const message of engineStream) {
-              if (message.type === 'text' && message.content) {
-                yield message.content;
-              } else if (typeof message === 'string') {
-                // If engine returns plain strings, pass them through
-                yield message;
-              }
-              // Ignore other message types for the text stream
-            }
+        for await (const message of engineStream) {
+          // Check for abort signal
+          if (abortSignal.aborted) {
+            const abortError = new Error('Operation aborted');
+            abortError.name = 'AbortError';
+            throw abortError;
           }
 
-          // Wrap the engine result to match streamText interface
-          return {
-            textStream: createTextStream(),
-            usage: Promise.resolve({}), // Engine should handle its own usage tracking
-            // Add other streamText-compatible properties as needed
-          };
-        }
-      } catch (error) {
-        if (this.debug) {
-          console.log(`[DEBUG] Failed to use Claude Code engine, falling back to Vercel:`, error.message);
-        }
-        // Fall through to use Vercel engine as fallback
-      }
-    }
+          const now = Date.now();
 
-    // Check if we should use Codex engine
-    if (this.clientApiProvider === 'codex' || process.env.USE_CODEX === 'true') {
-      try {
-        const engine = await this.getEngine();
-        if (engine && engine.query) {
-          // Convert Vercel AI SDK format to engine format
-          // Extract the ORIGINAL user message as the main prompt (skip any warning messages)
-          // Look for user messages that are NOT the warning message
-          const userMessages = options.messages.filter(m =>
-            m.role === 'user' &&
-            !m.content.includes('WARNING: You have reached the maximum tool iterations limit')
-          );
-          const lastUserMessage = userMessages[userMessages.length - 1];
-          const prompt = lastUserMessage ? lastUserMessage.content : '';
-
-          // Pass system message and other options
-          const engineOptions = {
-            maxTokens: options.maxTokens,
-            temperature: options.temperature,
-            messages: options.messages,
-            systemPrompt: options.messages.find(m => m.role === 'system')?.content
-          };
-
-          // Get the engine's query result (async generator)
-          const engineStream = engine.query(prompt, engineOptions);
-
-          // Create a text stream that extracts text from engine messages
-          async function* createTextStream() {
-            for await (const message of engineStream) {
-              if (message.type === 'text' && message.content) {
-                yield message.content;
-              } else if (typeof message === 'string') {
-                // If engine returns plain strings, pass them through
-                yield message;
-              }
-              // Ignore other message types for the text stream
-            }
+          // Check for activity timeout (no data received for too long)
+          if (now - lastActivity > activityTimeout) {
+            throw new Error(`Engine stream timeout - no activity for ${activityTimeout}ms`);
+          }
+
+          // Check for overall request timeout
+          if (requestTimeout > 0 && now - startTime > requestTimeout) {
+            throw new Error(`Engine stream timeout - request exceeded ${requestTimeout}ms`);
           }
 
-          // Wrap the engine result to match streamText interface
-          return {
-            textStream: createTextStream(),
-            usage: Promise.resolve({}), // Engine should handle its own usage tracking
-            // Add other streamText-compatible properties as needed
-          };
+          lastActivity = now;
+
+          if (message.type === 'text' && message.content) {
+            yield message.content;
+          } else if (typeof message === 'string') {
+            // If engine returns plain strings, pass them through
+            yield message;
+          }
+          // Ignore other message types for the text stream
         }
-      } catch (error) {
-        if (this.debug) {
-          console.log(`[DEBUG] Failed to use Codex engine, falling back to Vercel:`, error.message);
+      } finally {
+        // Clear operation timeout when stream completes (success or error)
+        // This is done here because for engine paths, the stream is returned
+        // immediately but consumed later by the caller
+        if (timeoutState.timeoutId) {
+          clearTimeout(timeoutState.timeoutId);
+          timeoutState.timeoutId = null;
         }
-        // Fall through to use Vercel engine as fallback
       }
     }
 
+    // Wrap the engine result to match streamText interface
+    // Note: maxOperationTimeout cleanup is handled by the generator's finally block
+    // since the stream is consumed after this function returns.
+    return {
+      textStream: createTextStream(),
+      usage: Promise.resolve({}), // Engine should handle its own usage tracking
+      // Add other streamText-compatible properties as needed
+    };
+  }
+
+  /**
+   * Try to use an engine (claude-code or codex) for streaming
+   * @param {Object} options - streamText options
+   * @param {AbortController} controller - Abort controller for the operation
+   * @param {Object} timeoutState - Mutable timeout state for cleanup
+   * @returns {Promise<Object|null>} - Stream result or null if engine unavailable
+   * @private
+   */
+  async _tryEngineStreamPath(options, controller, timeoutState) {
+    const engine = await this.getEngine();
+    if (!engine || !engine.query) {
+      return null;
+    }
+
+    // Extract the ORIGINAL user message as the main prompt (skip any warning messages)
+    const userMessages = options.messages.filter(m =>
+      m.role === 'user' &&
+      !m.content.includes('WARNING: You have reached the maximum tool iterations limit')
+    );
+    const lastUserMessage = userMessages[userMessages.length - 1];
+    const prompt = lastUserMessage ? lastUserMessage.content : '';
+
+    // Pass system message and other options including abort signal
+    const engineOptions = {
+      maxTokens: options.maxTokens,
+      temperature: options.temperature,
+      messages: options.messages,
+      systemPrompt: options.messages.find(m => m.role === 'system')?.content,
+      abortSignal: controller.signal
+    };
+
+    // Get the engine's query result and wrap with timeout handling
+    const engineStream = engine.query(prompt, engineOptions);
+    return this._createEngineTextStreamResult(
+      engineStream, controller.signal, this.requestTimeout, timeoutState
+    );
+  }
+
+  /**
+   * Execute streamText with Vercel AI SDK using retry/fallback logic
+   * @param {Object} options - streamText options
+   * @param {AbortController} controller - Abort controller for the operation
+   * @returns {Promise<Object>} - Stream result
+   * @private
+   */
+  async _executeWithVercelProvider(options, controller) {
     // Initialize retry manager if not already created
     if (!this.retryManager) {
       this.retryManager = new RetryManager({
@@ -1223,10 +1302,11 @@ export class ProbeAgent {
     // If no fallback manager, just use retry with current provider
     if (!this.fallbackManager) {
       return await this.retryManager.executeWithRetry(
-        () => streamText(options),
+        () => streamText({ ...options, abortSignal: controller.signal }),
         {
           provider: this.apiType,
-          model: this.model
+          model: this.model,
+          signal: controller.signal
         }
       );
     }
@@ -1234,13 +1314,12 @@ export class ProbeAgent {
     // Use fallback manager with retry for each provider
     return await this.fallbackManager.executeWithFallback(
       async (provider, model, config) => {
-        // Create options with the fallback provider
         const fallbackOptions = {
           ...options,
-          model: provider(model)
+          model: provider(model),
+          abortSignal: controller.signal
         };
 
-        // Create a retry manager for this specific provider
         const providerRetryManager = new RetryManager({
           maxRetries: config.maxRetries ?? this.retryConfig.maxRetries ?? 3,
           initialDelay: this.retryConfig.initialDelay ?? 1000,
@@ -1250,18 +1329,70 @@ export class ProbeAgent {
           debug: this.debug
         });
 
-        // Execute with retry for this provider
         return await providerRetryManager.executeWithRetry(
           () => streamText(fallbackOptions),
           {
             provider: config.provider,
-            model: model
+            model: model,
+            signal: controller.signal
           }
         );
       }
     );
   }
 
+  /**
+   * Execute streamText with retry and fallback support
+   * @param {Object} options - streamText options
+   * @returns {Promise<Object>} - streamText result
+   * @private
+   */
+  async streamTextWithRetryAndFallback(options) {
+    // Create AbortController for overall operation timeout
+    const controller = new AbortController();
+    const timeoutState = { timeoutId: null };
+
+    // Set up overall operation timeout (default 5 minutes)
+    if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
+      timeoutState.timeoutId = setTimeout(() => {
+        controller.abort();
+        if (this.debug) {
+          console.log(`[DEBUG] Operation timed out after ${this.maxOperationTimeout}ms (max operation timeout)`);
+        }
+      }, this.maxOperationTimeout);
+    }
+
+    try {
+      // Try engine paths (claude-code or codex)
+      const useClaudeCode = this.clientApiProvider === 'claude-code' || process.env.USE_CLAUDE_CODE === 'true';
+      const useCodex = this.clientApiProvider === 'codex' || process.env.USE_CODEX === 'true';
+
+      if (useClaudeCode || useCodex) {
+        try {
+          const result = await this._tryEngineStreamPath(options, controller, timeoutState);
+          if (result) {
+            return result;
+          }
+        } catch (error) {
+          if (this.debug) {
+            const engineType = useClaudeCode ? 'Claude Code' : 'Codex';
+            console.log(`[DEBUG] Failed to use ${engineType} engine, falling back to Vercel:`, error.message);
+          }
+          // Fall through to Vercel provider
+        }
+      }
+
+      // Use Vercel AI SDK with retry/fallback
+      return await this._executeWithVercelProvider(options, controller);
+    } finally {
+      // Clean up timeout (for non-engine paths; engine paths clean up in the generator)
+      if (timeoutState.timeoutId) {
+        clearTimeout(timeoutState.timeoutId);
+        timeoutState.timeoutId = null;
+      }
+    }
+  }
+
   /**
    * Initialize Anthropic model
    */
@@ -1612,7 +1743,8 @@ export class ProbeAgent {
       }
 
       // Security validation: check if path is within any allowed directory
-      // Use normalize() after resolve() to handle path traversal attempts (e.g., '/allowed/../etc/passwd')
+      // Use safeRealpath() to resolve symlinks and handle path traversal attempts (e.g., '/allowed/../etc/passwd')
+      // This prevents symlink bypass attacks (e.g., /tmp -> /private/tmp on macOS)
       const allowedDirs = this.allowedFolders && this.allowedFolders.length > 0 ? this.allowedFolders : [process.cwd()];
 
       let absolutePath;
@@ -1620,20 +1752,20 @@ export class ProbeAgent {
 
       // If absolute path, check if it's within any allowed directory
       if (isAbsolute(imagePath)) {
-        // Normalize to resolve any '..' sequences
-        absolutePath = normalize(resolve(imagePath));
+        // Use safeRealpath to resolve symlinks for security
+        absolutePath = safeRealpath(resolve(imagePath));
         isPathAllowed = allowedDirs.some(dir => {
-          const normalizedDir = normalize(resolve(dir));
+          const resolvedDir = safeRealpath(dir);
           // Ensure the path is within the allowed directory (add separator to prevent prefix attacks)
-          return absolutePath === normalizedDir || absolutePath.startsWith(normalizedDir + sep);
+          return absolutePath === resolvedDir || absolutePath.startsWith(resolvedDir + sep);
         });
       } else {
         // For relative paths, try resolving against each allowed directory
         for (const dir of allowedDirs) {
-          const normalizedDir = normalize(resolve(dir));
-          const resolvedPath = normalize(resolve(dir, imagePath));
+          const resolvedDir = safeRealpath(dir);
+          const resolvedPath = safeRealpath(resolve(dir, imagePath));
           // Ensure the resolved path is within the allowed directory
-          if (resolvedPath === normalizedDir || resolvedPath.startsWith(normalizedDir + sep)) {
+          if (resolvedPath === resolvedDir || resolvedPath.startsWith(resolvedDir + sep)) {
             absolutePath = resolvedPath;
             isPathAllowed = true;
             break;
@@ -1870,7 +2002,8 @@ export class ProbeAgent {
       return this.architectureContext;
     }
 
-    const rootDirectory = this.allowedFolders.length > 0 ? this.allowedFolders[0] : process.cwd();
+    // Use workspaceRoot for consistent path handling
+    const rootDirectory = this.workspaceRoot || (this.allowedFolders.length > 0 ? this.allowedFolders[0] : process.cwd());
     const configuredName =
       typeof this.architectureFileName === 'string' ? this.architectureFileName.trim() : '';
     const hasConfiguredName = !!configuredName;
@@ -2028,6 +2161,10 @@ export class ProbeAgent {
   }
 
   _getSkillsRepoRoot() {
+    // Use workspaceRoot for consistent path handling
+    if (this.workspaceRoot) {
+      return resolve(this.workspaceRoot);
+    }
     if (this.allowedFolders && this.allowedFolders.length > 0) {
       return resolve(this.allowedFolders[0]);
     }
@@ -2108,7 +2245,7 @@ ${extractGuidance}
     // Add repository structure if available
     if (this.fileList) {
       systemPrompt += `\n\n# Repository Structure\n`;
-      systemPrompt += `You are working with a repository located at: ${this.allowedFolders[0]}\n\n`;
+      systemPrompt += `You are working with a repository located at: ${this.workspaceRoot}\n\n`;
       systemPrompt += `Here's an overview of the repository structure (showing up to 100 most relevant files):\n\n`;
       systemPrompt += '```\n' + this.fileList + '\n```\n';
     }
@@ -2170,7 +2307,7 @@ ${extractGuidance}
     // Add repository structure if available
     if (this.fileList) {
       systemPrompt += `\n\n# Repository Structure\n`;
-      systemPrompt += `You are working with a repository located at: ${this.allowedFolders[0]}\n\n`;
+      systemPrompt += `You are working with a repository located at: ${this.workspaceRoot}\n\n`;
       systemPrompt += `Here's an overview of the repository structure (showing up to 100 most relevant files):\n\n`;
       systemPrompt += '```\n' + this.fileList + '\n```\n';
     }
@@ -2484,10 +2621,29 @@ Follow these instructions carefully:
       }
     }
 
-    // Add folder information
-    const searchDirectory = this.allowedFolders.length > 0 ? this.allowedFolders[0] : process.cwd();
+    // Add folder information using workspace root and relative paths
+    const searchDirectory = this.workspaceRoot;
     if (this.debug) {
-      console.log(`[DEBUG] Generating file list for base directory: ${searchDirectory}...`);
+      console.log(`[DEBUG] Generating file list for workspace root: ${searchDirectory}...`);
+    }
+
+    // Convert allowed folders to relative paths for cleaner AI context
+    // Add ./ prefix to make it clear these are relative paths
+    const relativeWorkspaces = this.allowedFolders.map(f => {
+      const rel = toRelativePath(f, this.workspaceRoot);
+      // Add ./ prefix if not already starting with . and not an absolute path
+      if (rel && rel !== '.' && !rel.startsWith('.') && !rel.startsWith('/')) {
+        return './' + rel;
+      }
+      return rel;
+    }).filter(f => f && f !== '.');
+
+    // Describe available paths in a user-friendly way
+    let workspaceDesc;
+    if (relativeWorkspaces.length === 0) {
+      workspaceDesc = '. (current directory)';
+    } else {
+      workspaceDesc = relativeWorkspaces.join(', ');
     }
 
     try {
@@ -2495,15 +2651,15 @@ Follow these instructions carefully:
         directory: searchDirectory,
         maxFiles: 100,
         respectGitignore: !process.env.PROBE_NO_GITIGNORE || process.env.PROBE_NO_GITIGNORE === '',
-        cwd: process.cwd()
+        cwd: this.workspaceRoot
       });
 
-      systemMessage += `\n# Repository Structure\n\nYou are working with a repository located at: ${searchDirectory}\n\nHere's an overview of the repository structure (showing up to 100 most relevant files):\n\n\`\`\`\n${files}\n\`\`\`\n\n`;
+      systemMessage += `\n# Repository Structure\n\nYou are working with a workspace. Available paths: ${workspaceDesc}\n\nHere's an overview of the repository structure (showing up to 100 most relevant files):\n\n\`\`\`\n${files}\n\`\`\`\n\n`;
     } catch (error) {
       if (this.debug) {
         console.log(`[DEBUG] Could not generate file list: ${error.message}`);
       }
-      systemMessage += `\n# Repository Structure\n\nYou are working with a repository located at: ${searchDirectory}\n\n`;
+      systemMessage += `\n# Repository Structure\n\nYou are working with a workspace. Available paths: ${workspaceDesc}\n\n`;
     }
 
     // Add architecture context if available
@@ -2511,7 +2667,15 @@ Follow these instructions carefully:
     systemMessage += this.getArchitectureSection();
 
     if (this.allowedFolders.length > 0) {
-      systemMessage += `\n**Important**: For security reasons, you can only search within these allowed folders: ${this.allowedFolders.join(', ')}\n\n`;
+      const relativeAllowed = this.allowedFolders.map(f => {
+        const rel = toRelativePath(f, this.workspaceRoot);
+        // Add ./ prefix if not already starting with . and not an absolute path
+        if (rel && rel !== '.' && !rel.startsWith('.') && !rel.startsWith('/')) {
+          return './' + rel;
+        }
+        return rel;
+      });
+      systemMessage += `\n**Important**: For security reasons, you can only access these paths: ${relativeAllowed.join(', ')}\n\n`;
     }
 
     return systemMessage;
@@ -3234,6 +3398,8 @@ Follow these instructions carefully:
                   console.error(`[DEBUG] ========================================\n`);
                 }
 
+                // Add assistant message with tool call (matching native tool pattern)
+                currentMessages.push({ role: 'assistant', content: assistantResponseContent });
                 currentMessages.push({ role: 'user', content: `<tool_result>\n${toolResultContent}\n</tool_result>` });
               } catch (error) {
                 // Record MCP tool end event (failure)
@@ -3257,24 +3423,27 @@ Follow these instructions carefully:
 
                 // Format error with structured information for AI
                 const errorXml = formatErrorForAI(error);
+                // Add assistant message with tool call (matching native tool pattern)
+                currentMessages.push({ role: 'assistant', content: assistantResponseContent });
                 currentMessages.push({ role: 'user', content: `<tool_result>\n${errorXml}\n</tool_result>` });
               }
             } else if (this.toolImplementations[toolName]) {
               // Execute native tool
               try {
                 // Add sessionId and workingDirectory to params for tool execution
-                // Validate and resolve workingDirectory
-                // Priority: explicit cwd > first allowed folder > process.cwd()
-                let resolvedWorkingDirectory = this.cwd || (this.allowedFolders && this.allowedFolders[0]) || process.cwd();
+                // Validate and resolve workingDirectory using safeRealpath for symlink security
+                // Consistent fallback chain: workspaceRoot > cwd > allowedFolders[0] > process.cwd()
+                let resolvedWorkingDirectory = this.workspaceRoot || this.cwd || (this.allowedFolders && this.allowedFolders[0]) || process.cwd();
                 if (params.workingDirectory) {
                   // Resolve relative paths against the current working directory context, not process.cwd()
-                  const requestedDir = isAbsolute(params.workingDirectory)
+                  // Use safeRealpath to resolve symlinks and prevent bypass attacks
+                  const requestedDir = safeRealpath(isAbsolute(params.workingDirectory)
                     ? resolve(params.workingDirectory)
-                    : resolve(resolvedWorkingDirectory, params.workingDirectory);
+                    : resolve(resolvedWorkingDirectory, params.workingDirectory));
                   // Check if the requested directory is within allowed folders
                   const isWithinAllowed = !this.allowedFolders || this.allowedFolders.length === 0 ||
                     this.allowedFolders.some(folder => {
-                      const resolvedFolder = resolve(folder);
+                      const resolvedFolder = safeRealpath(folder);
                       return requestedDir === resolvedFolder || requestedDir.startsWith(resolvedFolder + sep);
                     });
                   if (isWithinAllowed) {
@@ -3887,7 +4056,7 @@ Convert your previous response content into actual JSON data that follows this s
               
               const mermaidValidation = await validateAndFixMermaidResponse(finalResult, {
                 debug: this.debug,
-                path: this.allowedFolders[0],
+                path: this.workspaceRoot || this.allowedFolders[0],
                 provider: this.clientApiProvider,
                 model: this.model,
                 tracer: this.tracer
@@ -3977,7 +4146,7 @@ Convert your previous response content into actual JSON data that follows this s
 
               const { JsonFixingAgent } = await import('./schemaUtils.js');
               const jsonFixer = new JsonFixingAgent({
-                path: this.allowedFolders[0],
+                path: this.workspaceRoot || this.allowedFolders[0],
                 provider: this.clientApiProvider,
                 model: this.model,
                 debug: this.debug,
@@ -4065,7 +4234,7 @@ Convert your previous response content into actual JSON data that follows this s
 
             const mermaidValidation = await validateAndFixMermaidResponse(finalResult, {
               debug: this.debug,
-              path: this.allowedFolders[0],
+              path: this.workspaceRoot || this.allowedFolders[0],
               provider: this.clientApiProvider,
               model: this.model,
               tracer: this.tracer
@@ -4221,7 +4390,7 @@ Convert your previous response content into actual JSON data that follows this s
           
           const finalMermaidValidation = await validateAndFixMermaidResponse(finalResult, {
             debug: this.debug,
-            path: this.allowedFolders[0],
+            path: this.workspaceRoot || this.allowedFolders[0],
             provider: this.clientApiProvider,
             model: this.model,
             tracer: this.tracer
@@ -4419,7 +4588,7 @@ Convert your previous response content into actual JSON data that follows this s
       allowEdit: this.allowEdit,
       enableDelegate: this.enableDelegate,
       architectureFileName: this.architectureFileName,
-      path: this.allowedFolders[0], // Use first allowed folder as primary path
+      // Pass allowedFolders which will recompute workspaceRoot correctly
       allowedFolders: [...this.allowedFolders],
       cwd: this.cwd, // Preserve explicit working directory
       provider: this.clientApiProvider,