@probelabs/probe 0.6.0-rc253 → 0.6.0-rc255

package/index.d.ts

@@ -13,8 +13,10 @@ export interface ProbeAgentOptions {
   systemPrompt?: string;
   /** Predefined prompt type (persona) */
   promptType?: 'code-explorer' | 'engineer' | 'code-review' | 'support' | 'architect';
-  /** Allow the use of the 'implement' tool for code editing */
+  /** Allow the use of the 'edit' and 'create' tools for code editing */
   allowEdit?: boolean;
+  /** Annotate search/extract output with line hashes for integrity verification */
+  hashLines?: boolean;
   /** Architecture context filename to embed from repo root (defaults to AGENTS.md with CLAUDE.md fallback; ARCHITECTURE.md is always included when present) */
   architectureFileName?: string;
   /** Search directory path */
@@ -562,12 +564,196 @@ export declare function listFilesByLevel(
  */
 export declare const DEFAULT_SYSTEM_MESSAGE: string;
 
+/**
+ * Content record for a tracked symbol
+ */
+export interface ContentRecord {
+  /** SHA-256 content hash (first 16 hex chars) */
+  contentHash: string;
+  /** 1-indexed start line */
+  startLine: number;
+  /** 1-indexed end line */
+  endLine: number;
+  /** Symbol name, if from a symbol extract */
+  symbolName: string | null;
+  /** How the content was obtained: 'extract' or 'edit' */
+  source: string;
+  /** When the record was created (ms since epoch) */
+  timestamp: number;
+}
+
+/**
+ * Result of a staleness check
+ */
+export interface FileCheckResult {
+  /** Whether the file is safe to edit */
+  ok: boolean;
+  /** Reason for rejection: 'untracked' or 'stale' */
+  reason?: 'untracked' | 'stale';
+  /** Human-readable message explaining the rejection */
+  message?: string;
+}
+
+/**
+ * Compute a SHA-256 content hash for a code block.
+ * Normalizes trailing whitespace per line for robustness.
+ */
+export declare function computeContentHash(content: string): string;
+
+/**
+ * Per-session content-aware file state tracker for safe multi-edit workflows.
+ * Two-tier tracking: file-level "seen" flag + symbol-level content hashes.
+ * Edits proceed when the target symbol hasn't changed, even if other parts of the file changed.
+ */
+export declare class FileTracker {
+  constructor(options?: { debug?: boolean });
+
+  /** Mark a file as seen (read via search/extract) */
+  markFileSeen(resolvedPath: string): void;
+
+  /** Check if a file has been seen in this session */
+  isFileSeen(resolvedPath: string): boolean;
+
+  /** Store a content hash for a symbol */
+  trackSymbolContent(resolvedPath: string, symbolName: string, code: string, startLine: number, endLine: number, source?: string): void;
+
+  /** Look up a stored content record for a symbol */
+  getSymbolRecord(resolvedPath: string, symbolName: string): ContentRecord | null;
+
+  /** Check if a symbol's current content matches what was stored */
+  checkSymbolContent(resolvedPath: string, symbolName: string, currentCode: string): FileCheckResult;
+
+  /** Track files from extract target strings (marks as seen, hashes symbol targets) */
+  trackFilesFromExtract(targets: string[], cwd: string): Promise<void>;
+
+  /** Track files from probe search/extract output text (marks as seen) */
+  trackFilesFromOutput(output: string, cwd: string): Promise<void>;
+
+  /** Check if a file is safe to edit (seen-check only) */
+  checkBeforeEdit(resolvedPath: string): FileCheckResult;
+
+  /** Mark file as seen after write, invalidate content records */
+  trackFileAfterWrite(resolvedPath: string): Promise<void>;
+
+  /** Update stored hash after successful symbol write */
+  trackSymbolAfterWrite(resolvedPath: string, symbolName: string, code: string, startLine: number, endLine: number): void;
+
+  /** Remove all content records for a file */
+  invalidateFileRecords(resolvedPath: string): void;
+
+  /** Quick sync check if a file is being tracked (alias for isFileSeen) */
+  isTracked(resolvedPath: string): boolean;
+
+  /** Clear all tracking state */
+  clear(): void;
+}
+
+/**
+ * Edit tool configuration options
+ */
+export interface EditToolOptions {
+  /** Debug mode */
+  debug?: boolean;
+  /** Allowed directories for file operations */
+  allowedFolders?: string[];
+  /** Working directory for resolving relative paths */
+  cwd?: string;
+  /** Workspace root for relative path display */
+  workspaceRoot?: string;
+  /** File tracker for staleness detection (created automatically by ProbeAgent) */
+  fileTracker?: FileTracker;
+}
+
+/**
+ * Edit tool parameters (text mode)
+ */
+export interface EditTextParams {
+  /** Path to the file to edit */
+  file_path: string;
+  /** Text to find in the file (copy verbatim) */
+  old_string: string;
+  /** Replacement text */
+  new_string: string;
+  /** Replace all occurrences (default: false) */
+  replace_all?: boolean;
+}
+
+/**
+ * Edit tool parameters (symbol replace mode)
+ */
+export interface EditSymbolReplaceParams {
+  /** Path to the file to edit */
+  file_path: string;
+  /** Symbol name to replace (e.g. "myFunction", "MyClass.myMethod") */
+  symbol: string;
+  /** New code to replace the symbol with */
+  new_string: string;
+}
+
+/**
+ * Edit tool parameters (symbol insert mode)
+ */
+export interface EditSymbolInsertParams {
+  /** Path to the file to edit */
+  file_path: string;
+  /** Symbol name to insert near */
+  symbol: string;
+  /** New code to insert */
+  new_string: string;
+  /** Insert before or after the symbol */
+  position: 'before' | 'after';
+}
+
+/**
+ * Line-targeted edit parameters
+ */
+export interface EditLineTargetedParams {
+  /** Path to the file to edit */
+  file_path: string;
+  /** New code content */
+  new_string: string;
+  /** Line reference (e.g. "42" or "42:ab" with hash) */
+  start_line: string;
+  /** End of line range, inclusive (e.g. "55" or "55:cd"). Defaults to start_line. */
+  end_line?: string;
+  /** Insert before or after the line instead of replacing */
+  position?: 'before' | 'after';
+}
+
+/**
+ * Create tool parameters
+ */
+export interface CreateParams {
+  /** Path where the file should be created */
+  file_path: string;
+  /** Content to write to the file */
+  content: string;
+  /** Overwrite if file exists (default: false) */
+  overwrite?: boolean;
+}
+
+/**
+ * Create edit tool instance
+ */
+export declare function editTool(options?: EditToolOptions): {
+  execute(params: EditTextParams | EditSymbolReplaceParams | EditSymbolInsertParams | EditLineTargetedParams): Promise<string>;
+};
+
+/**
+ * Create create tool instance
+ */
+export declare function createTool(options?: EditToolOptions): {
+  execute(params: CreateParams): Promise<string>;
+};
+
 /**
  * Schema definitions
  */
 export declare const searchSchema: any;
 export declare const querySchema: any;
 export declare const extractSchema: any;
+export declare const editSchema: any;
+export declare const createSchema: any;
 export declare const attemptCompletionSchema: any;
 
 /**
@@ -576,6 +762,8 @@ export declare const attemptCompletionSchema: any;
 export declare const searchToolDefinition: any;
 export declare const queryToolDefinition: any;
 export declare const extractToolDefinition: any;
+export declare const editToolDefinition: string;
+export declare const createToolDefinition: string;
 export declare const attemptCompletionToolDefinition: any;
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc253",
+  "version": "0.6.0-rc255",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/agent/ProbeAgent.d.ts

@@ -35,7 +35,7 @@ export interface ProbeAgentOptions {
   systemPrompt?: string;
   /** Predefined prompt type (persona) */
   promptType?: 'code-explorer' | 'code-searcher' | 'engineer' | 'code-review' | 'support' | 'architect';
-  /** Allow the use of the 'implement' tool for code editing */
+  /** Allow the use of the 'edit' and 'create' tools for code editing */
   allowEdit?: boolean;
   /** Enable the delegate tool for task distribution to subagents */
   enableDelegate?: boolean;

package/src/agent/ProbeAgent.js

@@ -57,7 +57,6 @@ import {
   useSkillToolDefinition,
   readImageToolDefinition,
   attemptCompletionToolDefinition,
-  implementToolDefinition,
   editToolDefinition,
   createToolDefinition,
   googleSearchToolDefinition,
@@ -66,6 +65,7 @@ import {
   parseXmlToolCallWithThinking
 } from './tools.js';
 import { createMessagePreview, detectUnrecognizedToolCall, detectStuckResponse, areBothStuckResponses } from '../tools/common.js';
+import { FileTracker } from '../tools/fileTracker.js';
 import {
   createWrappedTools,
   listFilesToolInstance,
@@ -178,7 +178,7 @@ export class ProbeAgent {
    * @param {string} [options.customPrompt] - Custom prompt to replace the default system message
    * @param {string} [options.systemPrompt] - Alias for customPrompt; takes precedence when both are provided
    * @param {string} [options.promptType] - Predefined prompt type (code-explorer, code-searcher, architect, code-review, support)
-   * @param {boolean} [options.allowEdit=false] - Allow the use of the 'implement' tool
+   * @param {boolean} [options.allowEdit=false] - Allow the use of the 'edit' and 'create' tools
    * @param {boolean} [options.enableDelegate=false] - Enable the delegate tool for task distribution to subagents
    * @param {boolean} [options.enableExecutePlan=false] - Enable the execute_plan DSL orchestration tool
    * @param {string} [options.architectureFileName] - Architecture context filename to embed from repo root (defaults to AGENTS.md with CLAUDE.md fallback; ARCHITECTURE.md is always included when present)
@@ -229,6 +229,7 @@ export class ProbeAgent {
     this.customPrompt = options.systemPrompt || options.customPrompt || null;
     this.promptType = options.promptType || 'code-explorer';
     this.allowEdit = !!options.allowEdit;
+    this.hashLines = options.hashLines !== undefined ? !!options.hashLines : this.allowEdit;
     this.enableDelegate = !!options.enableDelegate;
     this.enableExecutePlan = !!options.enableExecutePlan;
     this.debug = options.debug || process.env.DEBUG === '1';
@@ -328,7 +329,8 @@ export class ProbeAgent {
     if (this.debug) {
       console.log(`[DEBUG] Generated session ID for agent: ${this.sessionId}`);
       console.log(`[DEBUG] Maximum tool iterations configured: ${MAX_TOOL_ITERATIONS}`);
-      console.log(`[DEBUG] Allow Edit (implement tool): ${this.allowEdit}`);
+      console.log(`[DEBUG] Allow Edit: ${this.allowEdit}`);
+      console.log(`[DEBUG] Hash Lines: ${this.hashLines}`);
       console.log(`[DEBUG] Search delegation enabled: ${this.searchDelegate}`);
       console.log(`[DEBUG] Workspace root: ${this.workspaceRoot}`);
       console.log(`[DEBUG] Working directory (cwd): ${this.cwd}`);
@@ -831,9 +833,12 @@ export class ProbeAgent {
       cwd: this.cwd,
       workspaceRoot: this.workspaceRoot,
       allowedFolders: this.allowedFolders,
+      // File state tracking for safe multi-edit workflows (only when editing is enabled)
+      fileTracker: this.allowEdit ? new FileTracker({ debug: this.debug }) : null,
       outline: this.outline,
       searchDelegate: this.searchDelegate,
       allowEdit: this.allowEdit,
+      hashLines: this.hashLines,
       enableDelegate: this.enableDelegate,
       enableExecutePlan: this.enableExecutePlan,
       enableBash: this.enableBash,
@@ -2553,16 +2558,12 @@ ${extractGuidance}
     }
 
     // Edit tools (require both allowEdit flag AND allowedTools permission)
-    if (this.allowEdit && isToolAllowed('implement')) {
-      toolDefinitions += `${implementToolDefinition}\n`;
-    }
     if (this.allowEdit && isToolAllowed('edit')) {
       toolDefinitions += `${editToolDefinition}\n`;
     }
     if (this.allowEdit && isToolAllowed('create')) {
       toolDefinitions += `${createToolDefinition}\n`;
     }
-
     // Bash tool (require both enableBash flag AND allowedTools permission)
     if (this.enableBash && isToolAllowed('bash')) {
       toolDefinitions += `${bashToolDefinition}\n`;
@@ -2645,7 +2646,7 @@ The configuration is loaded from src/config.js lines 15-25 which contains the da
       availableToolsList += '- query: Search code using structural AST patterns.\n';
     }
     if (isToolAllowed('extract')) {
-      availableToolsList += '- extract: Extract specific code blocks or lines from files.\n';
+      availableToolsList += '- extract: Extract specific code blocks or lines from files. Use with symbol targets (e.g. "file.js#funcName") to get line numbers for line-targeted editing.\n';
     }
     if (isToolAllowed('listFiles')) {
       availableToolsList += '- listFiles: List files and directories in a specified location.\n';
@@ -2662,11 +2663,8 @@ The configuration is loaded from src/config.js lines 15-25 which contains the da
     if (isToolAllowed('readImage')) {
       availableToolsList += '- readImage: Read and load an image file for AI analysis.\n';
     }
-    if (this.allowEdit && isToolAllowed('implement')) {
-      availableToolsList += '- implement: Implement a feature or fix a bug using aider.\n';
-    }
     if (this.allowEdit && isToolAllowed('edit')) {
-      availableToolsList += '- edit: Edit files using exact string replacement.\n';
+      availableToolsList += '- edit: Edit files using text replacement, AST-aware symbol operations, or line-targeted editing.\n';
     }
     if (this.allowEdit && isToolAllowed('create')) {
       availableToolsList += '- create: Create new files with specified content.\n';
@@ -2757,8 +2755,14 @@ Follow these instructions carefully:
 8. Once the task is fully completed, use the '<attempt_completion>' tool to provide the final result. This is the ONLY way to signal completion.
 9. Prefer concise and focused search queries. Use specific keywords and phrases to narrow down results.${this.allowEdit ? `
 10. When modifying files, choose the appropriate tool:
-    - Use 'edit' for precise changes to existing files (requires exact string match)
-    - Use 'create' for new files or complete file rewrites` : ''}
+    - Use 'edit' for all code modifications:
+      * For small changes (a line or a few lines), use old_string + new_string — copy old_string verbatim from the file.
+      * For rewriting entire functions/classes/methods, use the symbol parameter instead (no exact text matching needed).
+      * For editing specific lines from search/extract output, use start_line (and optionally end_line) with the line numbers shown in the output.${this.hashLines ? ' Line references include content hashes (e.g. "42:ab") for integrity verification.' : ''}
+      * For editing inside large functions: first use extract with the symbol target (e.g. "file.js#myFunction") to see the function with line numbers${this.hashLines ? ' and hashes' : ''}, then use start_line/end_line to surgically edit specific lines within it.
+    - Use 'create' for new files or complete file rewrites.
+    - If an edit fails, read the error message — it tells you exactly how to fix the call and retry.
+    - The system tracks which files you've seen via search/extract. If you try to edit a file you haven't read, or one that changed since you last read it, the edit will fail with instructions to re-read first. Always use extract before editing to ensure you have current file content.` : ''}
 </instructions>
 `;
 
@@ -3420,8 +3424,11 @@ Follow these instructions carefully:
           validTools.push('attempt_completion');
 
           // Edit tools (require both allowEdit flag AND allowedTools permission)
-          if (this.allowEdit && this.allowedTools.isEnabled('implement')) {
-            validTools.push('implement', 'edit', 'create');
+          if (this.allowEdit && this.allowedTools.isEnabled('edit')) {
+            validTools.push('edit');
+          }
+          if (this.allowEdit && this.allowedTools.isEnabled('create')) {
+            validTools.push('create');
           }
           // Bash tool (require both enableBash flag AND allowedTools permission)
           if (this.enableBash && this.allowedTools.isEnabled('bash')) {
@@ -3804,6 +3811,7 @@ Follow these instructions carefully:
                       mcpConfigPath: this.mcpConfigPath, // Inherit MCP config path
                       enableBash: this.enableBash,      // Inherit bash enablement
                       bashConfig: this.bashConfig,      // Inherit bash configuration
+                      allowEdit: this.allowEdit,        // Inherit edit/create permission
                       allowedTools: allowedToolsForDelegate,  // Inherit allowed tools from parent
                       debug: this.debug,
                       tracer: this.tracer
@@ -4005,6 +4013,33 @@ Follow these instructions carefully:
             break;
           }
 
+          // Issue #443: Check if response contains valid schema-matching JSON
+          // Before triggering error.no_tool_call, strip markdown fences and validate
+          // This handles cases where AI returns valid JSON without using attempt_completion
+          if (options.schema) {
+            // Remove thinking tags first
+            let contentToCheck = assistantResponseContent;
+            contentToCheck = contentToCheck.replace(/<thinking>[\s\S]*?<\/thinking>/gi, '').trim();
+            contentToCheck = contentToCheck.replace(/<thinking>[\s\S]*$/gi, '').trim();
+
+            // Try to extract and validate JSON
+            const cleanedJson = cleanSchemaResponse(contentToCheck);
+            try {
+              JSON.parse(cleanedJson);
+              const validation = validateJsonResponse(cleanedJson, { debug: this.debug, schema: options.schema });
+              if (validation.isValid) {
+                if (this.debug) {
+                  console.log(`[DEBUG] Issue #443: Accepting valid JSON response without attempt_completion (${cleanedJson.length} chars)`);
+                }
+                finalResult = cleanedJson;
+                completionAttempted = true;
+                break;
+              }
+            } catch {
+              // Not valid JSON - continue to standard no_tool_call handling
+            }
+          }
+
           // Increment consecutive no-tool counter (catches alternating stuck responses)
           consecutiveNoToolCount++;
 

package/src/agent/acp/tools.js

@@ -162,7 +162,8 @@ export class ACPToolManager {
         return ToolCallKind.extract;
       case 'delegate':
         return ToolCallKind.execute;
-      case 'implement':
+      case 'edit':
+      case 'create':
         return ToolCallKind.edit;
       default:
         return ToolCallKind.execute;

package/src/agent/acp/tools.test.js

@@ -117,7 +117,8 @@ describe('ACPToolManager', () => {
       expect(toolManager.getToolKind('query')).toBe(ToolCallKind.query);
       expect(toolManager.getToolKind('extract')).toBe(ToolCallKind.extract);
       expect(toolManager.getToolKind('delegate')).toBe(ToolCallKind.execute);
-      expect(toolManager.getToolKind('implement')).toBe(ToolCallKind.edit);
+      expect(toolManager.getToolKind('edit')).toBe(ToolCallKind.edit);
+      expect(toolManager.getToolKind('create')).toBe(ToolCallKind.edit);
       expect(toolManager.getToolKind('unknown')).toBe(ToolCallKind.execute);
     });
   });

package/src/agent/dsl/environment.js

@@ -183,6 +183,16 @@ export function generateSandboxGlobals(options) {
         });
       }
 
+      // Issue #444: Auto-coerce object paths to strings for search()
+      // AI-generated DSL sometimes passes field objects instead of field.file_path strings
+      if (params.path && typeof params.path === 'object') {
+        const coercedPath = params.path.file_path || params.path.path || params.path.directory || params.path.filename;
+        if (coercedPath && typeof coercedPath === 'string') {
+          logFn?.(`[${name}] Warning: Coerced object path to string "${coercedPath}" (issue #444)`);
+          params.path = coercedPath;
+        }
+      }
+
       const validated = schema.safeParse(params);
       if (!validated.success) {
         throw new Error(`Invalid parameters for ${name}: ${validated.error.message}`);
@@ -232,6 +242,15 @@ export function generateSandboxGlobals(options) {
   // When schema is provided, auto-parse the JSON result for easier downstream processing
   if (llmCall) {
     const rawLLM = async (instruction, data, opts = {}) => {
+      // Issue #444: Guard against error strings being passed as data
+      // When previous tool calls fail, they return "ERROR: ..." strings
+      // Passing these to LLM() spawns useless delegates that can't help
+      const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
+      if (dataStr && dataStr.startsWith('ERROR:')) {
+        logFn?.('[LLM] Blocked: data contains error from previous tool call');
+        return 'ERROR: Previous tool call failed - ' + dataStr.substring(0, 200);
+      }
+
       const result = await llmCall(instruction, data, opts);
       // Auto-parse JSON when schema is provided and result is a string
       if (opts.schema && typeof result === 'string') {

package/src/agent/index.js

@@ -124,7 +124,8 @@ function parseArgs() {
     schema: null,
     provider: null,
     model: null,
-    allowEdit: false,
+    allowEdit: process.env.ALLOW_EDIT === '1' || false,
+    hashLines: process.env.HASH_LINES !== undefined ? process.env.HASH_LINES === '1' : undefined,
     enableDelegate: false,
     verbose: false,
     help: false,
@@ -167,6 +168,10 @@ function parseArgs() {
       config.verbose = true;
     } else if (arg === '--allow-edit') {
       config.allowEdit = true;
+    } else if (arg === '--hash-lines') {
+      config.hashLines = true;
+    } else if (arg === '--no-hash-lines') {
+      config.hashLines = false;
     } else if (arg === '--enable-delegate') {
       config.enableDelegate = true;
     } else if (arg === '--no-delegate') {
@@ -275,12 +280,14 @@ Options:
   --schema <schema|file>           Output schema (JSON, XML, any format - text or file path)
   --provider <name>                Force AI provider: anthropic, openai, google
   --model <name>                   Override model name
-  --allow-edit                     Enable code modification capabilities
+  --allow-edit                     Enable code modification capabilities (edit + create tools)
+  --hash-lines                     Annotate search/extract output with line hashes (default: on when --allow-edit)
+  --no-hash-lines                  Disable line hash annotations even with --allow-edit
   --enable-delegate                Enable delegate tool for task distribution to subagents
   --allowed-tools <tools>          Filter available tools (comma-separated list)
                                    Use '*' or 'all' for all tools (default)
                                    Use 'none' or '' for no tools (raw AI mode)
-                                   Specific tools: search,query,extract,listFiles,searchFiles,listSkills,useSkill
+                                   Specific tools: search,query,extract,edit,create,listFiles,searchFiles,listSkills,useSkill
                                    Supports exclusion: '*,!bash' (all except bash)
   --disable-tools                  Disable all tools (raw AI mode, no code analysis)
                                    Convenience flag equivalent to --allowed-tools none
@@ -318,6 +325,8 @@ Environment Variables:
   FORCE_PROVIDER                  Force specific provider (anthropic, openai, google)
   MODEL_NAME                      Override model name
   MAX_RESPONSE_TOKENS             Maximum tokens for AI response
+  ALLOW_EDIT                      Enable code modification (set to '1')
+  HASH_LINES                      Annotate output with line hashes (set to '1'; default: on with ALLOW_EDIT)
   DEBUG                           Enable verbose mode (set to '1')
 
 Examples:
@@ -334,6 +343,8 @@ Examples:
   probe agent "Explain this code" --allowed-tools search,extract  # Only search and extract
   probe agent "What is this project about?" --allowed-tools none  # Raw AI mode (no tools)
   probe agent "Tell me about this project" --disable-tools        # Raw AI mode (convenience flag)
+  probe agent "Fix the off-by-one error" --allow-edit --path ./src  # Enable code editing
+  ALLOW_EDIT=1 probe agent "Refactor the login flow"                # Edit via env var
   probe agent --mcp               # Start MCP server mode
   probe agent --acp               # Start ACP server mode
 

package/src/agent/schemaUtils.js

@@ -165,6 +165,39 @@ export function decodeHtmlEntities(text) {
   return decoded;
 }
 
+/**
+ * Sanitize Markdown escape sequences in JSON strings
+ *
+ * Markdown uses backslash escapes like \*, \_, \#, \~ etc. which are NOT valid
+ * JSON escape sequences. When AI models produce JSON with Markdown content,
+ * these escapes cause JSON.parse() to fail with "Invalid \escape" errors.
+ *
+ * This function removes the backslash from invalid escape sequences while
+ * preserving valid JSON escapes: \\, \", \/, \b, \f, \n, \r, \t, \uXXXX
+ *
+ * @param {string} jsonString - JSON string that may contain Markdown escapes
+ * @returns {string} - JSON string with invalid escapes sanitized
+ */
+export function sanitizeMarkdownEscapesInJson(jsonString) {
+  if (!jsonString || typeof jsonString !== 'string') {
+    return jsonString;
+  }
+
+  // Strategy: Match either:
+  // 1. \\\\ (escaped backslash) - preserve as-is
+  // 2. \\X where X is NOT a valid JSON escape char - remove the backslash
+  //
+  // Valid JSON escape chars: " \ / b f n r t u
+  // This converts: \* → *, \_ → _, \# → #, \~ → ~, etc.
+  // But preserves: \\, \", \n, \t, \r, \b, \f, \/, \uXXXX
+  return jsonString.replace(/\\\\|\\([^"\\\/bfnrtu])/g, (match, captured) => {
+    if (match === '\\\\') {
+      return '\\\\'; // Preserve escaped backslash
+    }
+    return captured; // Remove backslash from invalid escape
+  });
+}
+
 /**
  * Normalize JavaScript syntax to valid JSON syntax
  * Converts single quotes to double quotes for strings in JSON-like structures
@@ -261,6 +294,22 @@ export function cleanSchemaResponse(response) {
     return cleanSchemaResponse(resultWrapperMatch[1]);
   }
 
+  // Strip <tool_code>...</tool_code> wrapper (Gemini-style code execution format)
+  // Issue #443: Gemini sometimes wraps responses in <plan> + <tool_code> tags
+  // e.g., <tool_code>print(attempt_completion({"projects": ["repo1"]}))</tool_code>
+  const toolCodeMatch = trimmed.match(/<tool_code>\s*([\s\S]*?)\s*<\/tool_code>/);
+  if (toolCodeMatch) {
+    let innerContent = toolCodeMatch[1].trim();
+    // Extract JSON from print() or attempt_completion() wrappers
+    // e.g., print({"key": "value"}) or attempt_completion({"key": "value"})
+    const funcCallMatch = innerContent.match(/(?:print|attempt_completion)\s*\(\s*([{\[][\s\S]*[}\]])\s*\)/);
+    if (funcCallMatch) {
+      return cleanSchemaResponse(funcCallMatch[1]);
+    }
+    // Try cleaning the inner content directly
+    return cleanSchemaResponse(innerContent);
+  }
+
   // First, look for JSON after code block markers - similar to mermaid extraction
   // Try with json language specifier
   const jsonBlockMatch = trimmed.match(/```json\s*\n([\s\S]*?)\n```/);
@@ -370,9 +419,30 @@ export function validateJsonResponse(response, options = {}) {
     }
   }
 
+  // Try to parse the response, with fallback to sanitizing Markdown escapes (issue #441)
+  let responseToValidate = response;
+  try {
+    JSON.parse(response);
+  } catch (initialError) {
+    // Check if the error is due to invalid escape sequences (Markdown escapes like \*, \_)
+    if (initialError.message && initialError.message.includes('escape')) {
+      const sanitized = sanitizeMarkdownEscapesInJson(response);
+      try {
+        JSON.parse(sanitized);
+        // Sanitized version parses - use it instead
+        responseToValidate = sanitized;
+        if (debug) {
+          console.log(`[DEBUG] JSON validation: Fixed Markdown escapes in JSON (issue #441)`);
+        }
+      } catch {
+        // Sanitization didn't help, continue with original (will fail below with proper error)
+      }
+    }
+  }
+
   try {
     const parseStart = Date.now();
-    const parsed = JSON.parse(response);
+    const parsed = JSON.parse(responseToValidate);
     const parseTime = Date.now() - parseStart;
 
     if (debug) {
@@ -853,7 +923,26 @@ export function tryAutoWrapForSimpleSchema(response, schema, options = {}) {
       console.log(`[DEBUG] Auto-wrap: Response is already valid JSON, skipping`);
     }
     return null;
-  } catch {
+  } catch (initialError) {
+    // Not valid JSON - check if it's due to Markdown escapes (issue #441)
+    // AI models sometimes produce JSON with Markdown escapes like \* or \_
+    // which are valid Markdown but NOT valid JSON escape sequences
+    if (initialError.message && initialError.message.includes('escape')) {
+      try {
+        const sanitized = sanitizeMarkdownEscapesInJson(response);
+        JSON.parse(sanitized);
+        // Sanitized JSON is valid! Return it instead of wrapping
+        if (debug) {
+          console.log(`[DEBUG] Auto-wrap: Fixed Markdown escapes in JSON (issue #441), returning sanitized JSON`);
+        }
+        return sanitized;
+      } catch {
+        // Sanitization didn't help, proceed with wrapping
+        if (debug) {
+          console.log(`[DEBUG] Auto-wrap: Markdown escape sanitization didn't fix JSON, proceeding with wrapping`);
+        }
+      }
+    }
     // Not valid JSON, proceed with wrapping
   }