@probelabs/probe 0.6.0-rc224 → 0.6.0-rc226

package/build/agent/ProbeAgent.js

@@ -71,6 +71,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 {
@@ -269,8 +270,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 +297,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
@@ -406,6 +416,209 @@ export class ProbeAgent {
     return mcpToolNames.filter(toolName => this._isMcpToolAllowed(toolName));
   }
 
+  /**
+   * Check if tracer is AppTracer (expects sessionId as first param) vs SimpleAppTracer
+   * @returns {boolean} - True if tracer is AppTracer style (requires sessionId)
+   * @private
+   */
+  _isAppTracerStyle() {
+    // AppTracer has recordThinkingContent(sessionId, iteration, content) signature
+    // SimpleAppTracer has recordThinkingContent(content, metadata) signature
+    // We detect by checking if there's a sessionSpans map (AppTracer-specific)
+    return this.tracer && typeof this.tracer.sessionSpans !== 'undefined';
+  }
+
+  /**
+   * Record an error classification event for telemetry
+   * Provides unified error recording across all error types
+   * @param {string} errorType - Error type (wrapped_tool, unrecognized_tool, no_tool_call, circuit_breaker)
+   * @param {string} message - Error message
+   * @param {Object} context - Additional context data
+   * @param {number} iteration - Current iteration number
+   * @private
+   */
+  _recordErrorTelemetry(errorType, message, context, iteration) {
+    if (!this.tracer) return;
+
+    if (this._isAppTracerStyle() && typeof this.tracer.recordErrorClassification === 'function') {
+      // AppTracer style: (sessionId, iteration, errorType, details)
+      this.tracer.recordErrorClassification(this.sessionId, iteration, errorType, {
+        message,
+        context
+      });
+    } else if (typeof this.tracer.recordErrorEvent === 'function') {
+      // SimpleAppTracer style: (errorType, details)
+      this.tracer.recordErrorEvent(errorType, {
+        message,
+        context: { ...context, iteration }
+      });
+    } else {
+      this.tracer.addEvent(`error.${errorType}`, {
+        'error.type': errorType,
+        'error.message': message,
+        'error.recoverable': errorType !== 'circuit_breaker',
+        'error.context': JSON.stringify(context).substring(0, 1000),
+        'iteration': iteration
+      });
+    }
+  }
+
+  /**
+   * Record AI thinking content for telemetry
+   * @param {string} thinkingContent - The thinking content
+   * @param {number} iteration - Current iteration number
+   * @private
+   */
+  _recordThinkingTelemetry(thinkingContent, iteration) {
+    if (!this.tracer || !thinkingContent) return;
+
+    if (this._isAppTracerStyle() && typeof this.tracer.recordThinkingContent === 'function') {
+      // AppTracer style: (sessionId, iteration, content)
+      this.tracer.recordThinkingContent(this.sessionId, iteration, thinkingContent);
+    } else if (typeof this.tracer.recordThinkingContent === 'function') {
+      // SimpleAppTracer style: (content, metadata)
+      this.tracer.recordThinkingContent(thinkingContent, { iteration });
+    } else {
+      this.tracer.addEvent('ai.thinking', {
+        'ai.thinking.content': thinkingContent.substring(0, 50000),
+        'ai.thinking.length': thinkingContent.length,
+        'iteration': iteration
+      });
+    }
+  }
+
+  /**
+   * Record AI tool decision for telemetry
+   * @param {string} toolName - The tool name
+   * @param {Object} params - Tool parameters
+   * @param {number} responseLength - Length of AI response
+   * @param {number} iteration - Current iteration number
+   * @private
+   */
+  _recordToolDecisionTelemetry(toolName, params, responseLength, iteration) {
+    if (!this.tracer) return;
+
+    if (this._isAppTracerStyle() && typeof this.tracer.recordAIToolDecision === 'function') {
+      // AppTracer style: (sessionId, iteration, toolName, params)
+      this.tracer.recordAIToolDecision(this.sessionId, iteration, toolName, params);
+    } else if (typeof this.tracer.recordToolDecision === 'function') {
+      // SimpleAppTracer style: (toolName, params, metadata)
+      this.tracer.recordToolDecision(toolName, params, {
+        iteration,
+        'ai.tool_decision.raw_response_length': responseLength
+      });
+    } else {
+      this.tracer.addEvent('ai.tool_decision', {
+        'ai.tool_decision.name': toolName,
+        'ai.tool_decision.params': JSON.stringify(params || {}).substring(0, 2000),
+        'ai.tool_decision.raw_response_length': responseLength,
+        'iteration': iteration
+      });
+    }
+  }
+
+  /**
+   * Record tool result for telemetry
+   * @param {string} toolName - The tool name
+   * @param {string|Object} result - Tool result
+   * @param {boolean} success - Whether tool succeeded
+   * @param {number} durationMs - Execution duration in milliseconds
+   * @param {number} iteration - Current iteration number
+   * @private
+   */
+  _recordToolResultTelemetry(toolName, result, success, durationMs, iteration) {
+    if (!this.tracer) return;
+
+    if (this._isAppTracerStyle() && typeof this.tracer.recordToolResult === 'function') {
+      // AppTracer style: (sessionId, iteration, toolName, result, success, durationMs)
+      this.tracer.recordToolResult(this.sessionId, iteration, toolName, result, success, durationMs);
+    } else if (typeof this.tracer.recordToolResult === 'function') {
+      // SimpleAppTracer style: (toolName, result, success, durationMs, metadata)
+      this.tracer.recordToolResult(toolName, result, success, durationMs, { iteration });
+    } else {
+      const resultStr = typeof result === 'string' ? result : JSON.stringify(result || '');
+      this.tracer.addEvent('tool.result', {
+        'tool.name': toolName,
+        'tool.result': resultStr.substring(0, 10000),
+        'tool.result.length': resultStr.length,
+        'tool.duration_ms': durationMs,
+        'tool.success': success,
+        'iteration': iteration
+      });
+    }
+  }
+
+  /**
+   * Record MCP tool lifecycle event for telemetry
+   * @param {string} phase - 'start' or 'end'
+   * @param {string} toolName - MCP tool name
+   * @param {Object} params - Tool parameters (for start) or null (for end)
+   * @param {number} iteration - Current iteration number
+   * @param {Object} [endData] - Additional data for end phase (result, success, durationMs, error)
+   * @private
+   */
+  _recordMcpToolTelemetry(phase, toolName, params, iteration, endData = null) {
+    if (!this.tracer) return;
+
+    if (phase === 'start') {
+      if (this._isAppTracerStyle() && typeof this.tracer.recordMcpToolStart === 'function') {
+        // AppTracer style: (sessionId, iteration, toolName, serverName, params)
+        this.tracer.recordMcpToolStart(this.sessionId, iteration, toolName, 'mcp', params);
+      } else if (typeof this.tracer.recordMcpToolStart === 'function') {
+        // SimpleAppTracer style: (toolName, serverName, params, metadata)
+        this.tracer.recordMcpToolStart(toolName, 'mcp', params, { iteration });
+      } else {
+        this.tracer.addEvent('mcp.tool.start', {
+          'mcp.tool.name': toolName,
+          'mcp.tool.server': 'mcp',
+          'mcp.tool.params': JSON.stringify(params || {}).substring(0, 2000),
+          'iteration': iteration
+        });
+      }
+    } else if (phase === 'end' && endData) {
+      const { result, success, durationMs, error } = endData;
+      if (this._isAppTracerStyle() && typeof this.tracer.recordMcpToolEnd === 'function') {
+        // AppTracer style: (sessionId, iteration, toolName, serverName, result, success, durationMs, error)
+        this.tracer.recordMcpToolEnd(this.sessionId, iteration, toolName, 'mcp', result, success, durationMs, error);
+      } else if (typeof this.tracer.recordMcpToolEnd === 'function') {
+        // SimpleAppTracer style: (toolName, serverName, result, success, durationMs, error, metadata)
+        this.tracer.recordMcpToolEnd(toolName, 'mcp', result, success, durationMs, error, { iteration });
+      } else {
+        const resultStr = typeof result === 'string' ? result : JSON.stringify(result || '');
+        this.tracer.addEvent('mcp.tool.end', {
+          'mcp.tool.name': toolName,
+          'mcp.tool.server': 'mcp',
+          'mcp.tool.result': resultStr.substring(0, 10000),
+          'mcp.tool.result.length': resultStr.length,
+          'mcp.tool.duration_ms': durationMs,
+          'mcp.tool.success': success,
+          'mcp.tool.error': error,
+          'iteration': iteration
+        });
+      }
+    }
+  }
+
+  /**
+   * Record iteration lifecycle event for telemetry
+   * @param {string} phase - 'end' (start is already handled elsewhere)
+   * @param {number} iteration - Current iteration number
+   * @param {Object} data - Additional iteration data
+   * @private
+   */
+  _recordIterationTelemetry(phase, iteration, data = {}) {
+    if (!this.tracer) return;
+
+    if (typeof this.tracer.recordIterationEvent === 'function') {
+      this.tracer.recordIterationEvent(phase, iteration, data);
+    } else {
+      this.tracer.addEvent(`iteration.${phase}`, {
+        'iteration': iteration,
+        ...data
+      });
+    }
+  }
+
   /**
    * Initialize the agent asynchronously (must be called after constructor)
    * This method initializes MCP and merges MCP tools into the tool list, and loads history from storage
@@ -529,8 +742,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,
@@ -1409,7 +1623,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;
@@ -1417,20 +1632,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;
@@ -1667,7 +1882,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;
@@ -1825,6 +2041,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]);
     }
@@ -1905,7 +2125,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';
     }
@@ -1967,7 +2187,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';
     }
@@ -2281,10 +2501,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 {
@@ -2292,15 +2531,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
@@ -2308,7 +2547,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;
@@ -2854,8 +3101,18 @@ Follow these instructions carefully:
         const parsedTool = (this.mcpBridge && !options._disableTools)
           ? parseHybridXmlToolCall(assistantResponseContent, nativeTools, this.mcpBridge)
           : parseXmlToolCallWithThinking(assistantResponseContent, validTools);
+
+        // Capture AI thinking content if present (for debugging and telemetry)
+        if (parsedTool?.thinkingContent) {
+          this._recordThinkingTelemetry(parsedTool.thinkingContent, currentIteration);
+        }
+
         if (parsedTool) {
           const { toolName, params } = parsedTool;
+
+          // Record AI tool decision for telemetry
+          this._recordToolDecisionTelemetry(toolName, params, assistantResponseContent.length, currentIteration);
+
           if (this.debug) console.log(`[DEBUG] Parsed tool call: ${toolName} with params:`, params);
 
           if (toolName === 'attempt_completion') {
@@ -2962,6 +3219,9 @@ Follow these instructions carefully:
 
             if (type === 'mcp' && this.mcpBridge && this.mcpBridge.isMcpTool(toolName)) {
               // Execute MCP tool
+              const mcpStartTime = Date.now();
+              this._recordMcpToolTelemetry('start', toolName, params, currentIteration);
+
               try {
                 // Log MCP tool execution in debug mode
                 if (this.debug) {
@@ -2999,6 +3259,15 @@ Follow these instructions carefully:
                   console.error(`[WARN] Tool output truncation failed: ${truncateError.message}`);
                 }
 
+                // Record MCP tool end event (success)
+                const mcpDurationMs = Date.now() - mcpStartTime;
+                this._recordMcpToolTelemetry('end', toolName, null, currentIteration, {
+                  result: toolResultContent,
+                  success: true,
+                  durationMs: mcpDurationMs,
+                  error: null
+                });
+
                 // Log MCP tool result in debug mode
                 if (this.debug) {
                   const preview = toolResultContent.length > 500 ? toolResultContent.substring(0, 500) + '...' : toolResultContent;
@@ -3009,8 +3278,19 @@ 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)
+                const mcpDurationMs = Date.now() - mcpStartTime;
+                this._recordMcpToolTelemetry('end', toolName, null, currentIteration, {
+                  result: null,
+                  success: false,
+                  durationMs: mcpDurationMs,
+                  error: error.message
+                });
+
                 console.error(`Error executing MCP tool ${toolName}:`, error);
 
                 // Log MCP tool error in debug mode
@@ -3023,24 +3303,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) {
@@ -3118,6 +3401,7 @@ Follow these instructions carefully:
                 };
 
                 let toolResult;
+                const toolStartTime = Date.now();
                 try {
                   if (this.tracer) {
                     toolResult = await this.tracer.withSpan('tool.call', executeToolCall, {
@@ -3128,7 +3412,11 @@ Follow these instructions carefully:
                   } else {
                     toolResult = await executeToolCall();
                   }
-                  
+
+                  // Record tool result in telemetry
+                  const toolDurationMs = Date.now() - toolStartTime;
+                  this._recordToolResultTelemetry(toolName, toolResult, true, toolDurationMs, currentIteration);
+
                   // Log tool result in debug mode
                   if (this.debug) {
                     const resultPreview = typeof toolResult === 'string'
@@ -3201,6 +3489,22 @@ Follow these instructions carefully:
                   content: toolResultMessage
                 });
 
+                // Record conversation turns in telemetry
+                if (this.tracer) {
+                  if (typeof this.tracer.recordConversationTurn === 'function') {
+                    this.tracer.recordConversationTurn('assistant', assistantResponseContent, {
+                      iteration: currentIteration,
+                      has_tool_call: true,
+                      tool_name: toolName
+                    });
+                    this.tracer.recordConversationTurn('tool_result', toolResultContent, {
+                      iteration: currentIteration,
+                      tool_name: toolName,
+                      tool_success: true
+                    });
+                  }
+                }
+
                 // NOTE: Automatic image processing removed (GitHub issue #305)
                 // Images are now only loaded when the AI explicitly calls the readImage tool
                 // This prevents: 1) implicit behavior that users don't expect
@@ -3294,6 +3598,10 @@ Follow these instructions carefully:
             if (this.debug) {
               console.log(`[DEBUG] Detected wrapped tool '${wrappedToolName}' in assistant response - wrong XML format.`);
             }
+
+            // Record wrapped tool error in telemetry
+            this._recordErrorTelemetry('wrapped_tool', 'Tool call wrapped in markdown', { toolName: wrappedToolName }, currentIteration);
+
             const toolError = new ParameterError(
               `Tool '${wrappedToolName}' found but in WRONG FORMAT - do not wrap tools in other XML tags.`,
               {
@@ -3318,12 +3626,19 @@ Remove ALL wrapper tags and use <${wrappedToolName}> directly as the outermost t
             if (this.debug) {
               console.log(`[DEBUG] Detected unrecognized tool '${unrecognizedTool}' in assistant response.`);
             }
+
+            // Record unrecognized tool error in telemetry
+            this._recordErrorTelemetry('unrecognized_tool', `Unknown tool: ${unrecognizedTool}`, { toolName: unrecognizedTool, validTools }, currentIteration);
+
             const toolError = new ParameterError(`Tool '${unrecognizedTool}' is not available in this context.`, {
               suggestion: `Available tools: ${validTools.join(', ')}. Please use one of these tools instead.`
             });
             reminderContent = `<tool_result>\n${formatErrorForAI(toolError)}\n</tool_result>`;
           } else {
-            // No tool call detected at all - check if this is the last iteration
+            // No tool call detected at all - record in telemetry
+            this._recordErrorTelemetry('no_tool_call', 'AI response did not contain tool call', { responsePreview: assistantResponseContent.substring(0, 500) }, currentIteration);
+
+            // Check if this is the last iteration
             // On the last iteration, if the AI gave a substantive response without using
             // attempt_completion, accept it as the final answer rather than losing the content
             if (currentIteration >= maxIterations) {
@@ -3439,6 +3754,10 @@ Note: <attempt_complete></attempt_complete> reuses your PREVIOUS assistant messa
               sameFormatErrorCount++;
               if (sameFormatErrorCount >= MAX_REPEATED_FORMAT_ERRORS) {
                 const errorDesc = isWrapped ? 'wrapped tool format' : unrecognizedTool;
+
+                // Record circuit breaker error in telemetry
+                this._recordErrorTelemetry('circuit_breaker', 'Format error limit exceeded', { formatErrorCount: sameFormatErrorCount, errorCategory }, currentIteration);
+
                 console.error(`[ERROR] Format error category '${errorCategory}' repeated ${sameFormatErrorCount} times. Breaking loop early to prevent infinite iteration.`);
                 finalResult = `Error: Unable to complete request. The AI model repeatedly used incorrect tool call format (${errorDesc}). Please try rephrasing your question or using a different model.`;
                 break;
@@ -3454,13 +3773,19 @@ Note: <attempt_complete></attempt_complete> reuses your PREVIOUS assistant messa
           }
         }
 
+        // Record iteration end event
+        this._recordIterationTelemetry('end', currentIteration, {
+          'iteration.completed': completionAttempted,
+          'iteration.message_count': currentMessages.length
+        });
+
         // Keep message history manageable
         if (currentMessages.length > MAX_HISTORY_MESSAGES) {
           const messagesBefore = currentMessages.length;
           const systemMsg = currentMessages[0]; // Keep system message
           const recentMessages = currentMessages.slice(-MAX_HISTORY_MESSAGES + 1);
           currentMessages = [systemMsg, ...recentMessages];
-          
+
           if (this.debug) {
             console.log(`[DEBUG] Trimmed message history from ${messagesBefore} to ${currentMessages.length} messages`);
           }
@@ -3611,7 +3936,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
@@ -3701,7 +4026,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,
@@ -3789,7 +4114,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
@@ -3945,7 +4270,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
@@ -4143,7 +4468,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,