@probelabs/probe 0.6.0-rc279 → 0.6.0-rc280

package/cjs/agent/ProbeAgent.cjs

@@ -29663,9 +29663,7 @@ async function acquireFileLock(lockPath, version2) {
   };
   try {
     await import_fs_extra2.default.writeFile(lockPath, JSON.stringify(lockData), { flag: "wx" });
-    if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-      console.log(`Acquired file lock: ${lockPath}`);
-    }
+    console.log(`Acquired file lock: ${lockPath}`);
     return true;
   } catch (error2) {
     if (error2.code === "EEXIST") {
@@ -29673,15 +29671,11 @@ async function acquireFileLock(lockPath, version2) {
         const existingLock = JSON.parse(await import_fs_extra2.default.readFile(lockPath, "utf-8"));
         const lockAge = Date.now() - existingLock.timestamp;
         if (lockAge > LOCK_TIMEOUT_MS) {
-          if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-            console.log(`Removing stale lock file (age: ${Math.round(lockAge / 1e3)}s, pid: ${existingLock.pid})`);
-          }
+          console.log(`Removing stale lock file (age: ${Math.round(lockAge / 1e3)}s, pid: ${existingLock.pid})`);
           await import_fs_extra2.default.remove(lockPath);
           return false;
         }
-        if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-          console.log(`Download in progress by process ${existingLock.pid}, waiting...`);
-        }
+        console.log(`Download in progress by process ${existingLock.pid}, waiting...`);
         return false;
       } catch (readError) {
         if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
@@ -29722,36 +29716,36 @@ async function releaseFileLock(lockPath) {
 }
 async function waitForFileLock(lockPath, binaryPath) {
   const startTime = Date.now();
+  let lastStatusTime = startTime;
+  console.log(`Waiting for file lock to clear: ${lockPath}`);
   while (Date.now() - startTime < MAX_LOCK_WAIT_MS) {
     if (await import_fs_extra2.default.pathExists(binaryPath)) {
-      if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-        console.log(`Binary now available at ${binaryPath}, download completed by another process`);
-      }
+      const waitedSeconds = Math.round((Date.now() - startTime) / 1e3);
+      console.log(`Binary now available at ${binaryPath}, download completed by another process (waited ${waitedSeconds}s)`);
       return true;
     }
     const lockExists = await import_fs_extra2.default.pathExists(lockPath);
     if (!lockExists) {
-      if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-        console.log(`Lock file removed but binary not found - download may have failed`);
-      }
+      console.log(`Lock file removed but binary not found - download may have failed`);
       return false;
     }
     try {
       const lockData = JSON.parse(await import_fs_extra2.default.readFile(lockPath, "utf-8"));
       const lockAge = Date.now() - lockData.timestamp;
       if (lockAge > LOCK_TIMEOUT_MS) {
-        if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-          console.log(`Lock expired (age: ${Math.round(lockAge / 1e3)}s), will retry download`);
-        }
+        console.log(`Lock expired (age: ${Math.round(lockAge / 1e3)}s), will retry download`);
         return false;
       }
     } catch {
     }
+    if (Date.now() - lastStatusTime >= 15e3) {
+      const elapsedSeconds = Math.round((Date.now() - startTime) / 1e3);
+      console.log(`Still waiting for file lock (${elapsedSeconds}s/${MAX_LOCK_WAIT_MS / 1e3}s max)`);
+      lastStatusTime = Date.now();
+    }
     await new Promise((resolve8) => setTimeout(resolve8, LOCK_POLL_INTERVAL_MS));
   }
-  if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-    console.log(`Timeout waiting for file lock`);
-  }
+  console.log(`Timeout waiting for file lock after ${MAX_LOCK_WAIT_MS / 1e3}s`);
   return false;
 }
 async function withDownloadLock(version2, downloadFn) {
@@ -29765,9 +29759,7 @@ async function withDownloadLock(version2, downloadFn) {
       }
       downloadLocks.delete(lockKey);
     } else {
-      if (process.env.DEBUG === "1" || process.env.VERBOSE === "1") {
-        console.log(`Download already in progress in this process for version ${lockKey}, waiting...`);
-      }
+      console.log(`Download already in progress in this process for version ${lockKey}, waiting...`);
       try {
         return await lock.promise;
       } catch (error2) {
@@ -29777,10 +29769,16 @@ async function withDownloadLock(version2, downloadFn) {
       }
     }
   }
+  let timeoutId = null;
   const downloadPromise = Promise.race([
     downloadFn(),
     new Promise(
-      (_, reject2) => setTimeout(() => reject2(new Error(`Download timeout after ${LOCK_TIMEOUT_MS / 1e3}s`)), LOCK_TIMEOUT_MS)
+      (_, reject2) => {
+        timeoutId = setTimeout(() => reject2(new Error(`Download timeout after ${LOCK_TIMEOUT_MS / 1e3}s`)), LOCK_TIMEOUT_MS);
+        if (timeoutId.unref) {
+          timeoutId.unref();
+        }
+      }
     )
   ]);
   downloadLocks.set(lockKey, {
@@ -29791,6 +29789,9 @@ async function withDownloadLock(version2, downloadFn) {
     const result = await downloadPromise;
     return result;
   } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
     downloadLocks.delete(lockKey);
   }
 }
@@ -31522,10 +31523,9 @@ var init_delegate = __esm({
         if (this.tryAcquire(parentSessionId)) {
           return true;
         }
-        if (debug) {
-          console.error(`[DelegationManager] Slot unavailable (${this.globalActive}/${this.maxConcurrent}), queuing... (queue size: ${this.waitQueue.length}, timeout: ${effectiveTimeout}ms)`);
-        }
+        console.error(`[DelegationManager] Slot unavailable (${this.globalActive}/${this.maxConcurrent}), queuing... (queue size: ${this.waitQueue.length + 1}, timeout: ${effectiveTimeout}ms)`);
         return new Promise((resolve8, reject2) => {
+          const queuedAt = Date.now();
           const entry = {
             resolve: null,
             // Will be wrapped below
@@ -31533,20 +31533,23 @@ var init_delegate = __esm({
             // Will be wrapped below
             parentSessionId,
             debug,
-            queuedAt: Date.now(),
-            timeoutId: null
+            queuedAt,
+            timeoutId: null,
+            reminderId: null
           };
           let settled = false;
           entry.resolve = (value) => {
             if (settled) return;
             settled = true;
             if (entry.timeoutId) clearTimeout(entry.timeoutId);
+            if (entry.reminderId) clearInterval(entry.reminderId);
             resolve8(value);
           };
           entry.reject = (error2) => {
             if (settled) return;
             settled = true;
             if (entry.timeoutId) clearTimeout(entry.timeoutId);
+            if (entry.reminderId) clearInterval(entry.reminderId);
             reject2(error2);
           };
           if (effectiveTimeout > 0) {
@@ -31558,6 +31561,13 @@ var init_delegate = __esm({
               entry.reject(new Error(`Delegation queue timeout: waited ${effectiveTimeout}ms for an available slot`));
             }, effectiveTimeout);
           }
+          entry.reminderId = setInterval(() => {
+            const waitedSeconds = Math.round((Date.now() - queuedAt) / 1e3);
+            console.error(`[DelegationManager] Still waiting for slot (${waitedSeconds}s). ${this.globalActive}/${this.maxConcurrent} active, ${this.waitQueue.length} queued.`);
+          }, 15e3);
+          if (entry.reminderId.unref) {
+            entry.reminderId.unref();
+          }
           this.waitQueue.push(entry);
         });
       }
@@ -31596,18 +31606,14 @@ var init_delegate = __esm({
             const sessionData = this.sessionDelegations.get(parentSessionId);
             const sessionCount = sessionData?.count || 0;
             if (sessionCount >= this.maxPerSession) {
-              if (debug) {
-                console.error(`[DelegationManager] Session limit (${this.maxPerSession}) reached for queued item, rejecting`);
-              }
+              console.error(`[DelegationManager] Session limit (${this.maxPerSession}) reached for queued item, rejecting`);
               toReject.push({ reject: reject2, error: new Error(`Maximum delegations per session (${this.maxPerSession}) reached for session ${parentSessionId}`) });
               continue;
             }
           }
           this._incrementCounters(parentSessionId);
-          if (debug) {
-            const waitTime = Date.now() - queuedAt;
-            console.error(`[DelegationManager] Granted slot from queue (waited ${waitTime}ms). Active: ${this.globalActive}/${this.maxConcurrent}`);
-          }
+          const waitTime = Date.now() - queuedAt;
+          console.error(`[DelegationManager] Granted slot from queue (waited ${waitTime}ms). Active: ${this.globalActive}/${this.maxConcurrent}`);
           toResolve.push(resolve8);
         }
         if (toResolve.length > 0 || toReject.length > 0) {
@@ -31657,6 +31663,9 @@ var init_delegate = __esm({
           if (entry.timeoutId) {
             clearTimeout(entry.timeoutId);
           }
+          if (entry.reminderId) {
+            clearInterval(entry.reminderId);
+          }
           if (entry.reject) {
             entry.reject(new Error("DelegationManager was cleaned up"));
           }
@@ -31801,16 +31810,12 @@ async function processChunksParallel(chunks, extractionPrompt, maxWorkers, optio
         return result;
       });
       active.add(promise);
-      if (options.debug) {
-        console.error(`[analyze_all] Started processing chunk ${chunk.id}/${chunk.total}`);
-      }
+      console.error(`[analyze_all] Started processing chunk ${chunk.id}/${chunk.total}`);
     }
     if (active.size > 0) {
       const result = await Promise.race(active);
       results.push(result);
-      if (options.debug) {
-        console.error(`[analyze_all] Completed chunk ${result.chunk.id}/${result.chunk.total}`);
-      }
+      console.error(`[analyze_all] Completed chunk ${result.chunk.id}/${result.chunk.total}`);
     }
   }
   results.sort((a5, b5) => a5.chunk.id - b5.chunk.id);
@@ -36303,14 +36308,14 @@ function resolveTargetPath(target, cwd) {
   }
   return filePart + suffix;
 }
-var import_path5, searchSchema, searchAllSchema, querySchema, extractSchema, delegateSchema, listSkillsSchema, useSkillSchema, listFilesSchema, searchFilesSchema, readImageSchema, bashSchema, analyzeAllSchema, executePlanSchema, cleanupExecutePlanSchema, searchDescription, queryDescription, extractDescription, delegateDescription, analyzeAllDescription;
+var import_path5, searchSchema, searchAllSchema, querySchema, extractSchema, delegateSchema, listSkillsSchema, useSkillSchema, listFilesSchema, searchFilesSchema, readImageSchema, bashSchema, analyzeAllSchema, executePlanSchema, cleanupExecutePlanSchema, searchDescription, searchDelegateDescription, queryDescription, extractDescription, delegateDescription, analyzeAllDescription;
 var init_common2 = __esm({
   "src/tools/common.js"() {
     "use strict";
     init_zod();
     import_path5 = require("path");
     searchSchema = external_exports.object({
-      query: external_exports.string().describe("Search query with Elasticsearch syntax. Use quotes for exact matches, AND/OR for boolean logic, - for negation."),
+      query: external_exports.string().describe("Search query \u2014 natural language questions or Elasticsearch-style keywords both work. For keywords: use quotes for exact phrases, AND/OR for boolean logic, - for negation. Probe handles stemming and camelCase/snake_case splitting automatically, so do NOT try case or style variations of the same keyword."),
       path: external_exports.string().optional().default(".").describe('Path to search in. For dependencies use "go:github.com/owner/repo", "js:package_name", or "rust:cargo_name" etc.'),
       exact: external_exports.boolean().optional().default(false).describe('Default (false) enables stemming and keyword splitting for exploratory search - "getUserData" matches "get", "user", "data", etc. Set true for precise symbol lookup where "getUserData" matches only "getUserData". Use true when you know the exact symbol name.'),
       maxTokens: external_exports.number().nullable().optional().describe("Maximum tokens to return. Default is 20000. Set to null for unlimited results."),
@@ -36318,7 +36323,7 @@ var init_common2 = __esm({
       nextPage: external_exports.boolean().optional().default(false).describe("Set to true when requesting the next page of results. Requires passing the same session ID from the previous search output.")
     });
     searchAllSchema = external_exports.object({
-      query: external_exports.string().describe("Search query with Elasticsearch syntax. Use quotes for exact matches, AND/OR for boolean logic, - for negation."),
+      query: external_exports.string().describe("Search query \u2014 natural language questions or Elasticsearch-style keywords both work. For keywords: use quotes for exact phrases, AND/OR for boolean logic, - for negation. Probe handles stemming and camelCase/snake_case splitting automatically, so do NOT try case or style variations of the same keyword."),
       path: external_exports.string().optional().default(".").describe("Path to search in."),
       exact: external_exports.boolean().optional().default(false).describe("Use exact matching instead of stemming."),
       maxTokensPerPage: external_exports.number().optional().default(2e4).describe("Tokens per page when paginating. Default 20000."),
@@ -36373,7 +36378,8 @@ var init_common2 = __esm({
       clearOutputBuffer: external_exports.boolean().optional().default(true).describe("Clear the output buffer from previous execute_plan calls"),
       clearSessionStore: external_exports.boolean().optional().default(false).describe("Clear the session store (persisted data across execute_plan calls)")
     });
-    searchDescription = "Search code in the repository. Free-form questions are accepted, but Elasticsearch-style keyword queries work best. Use this tool first for any code-related questions.";
+    searchDescription = 'Search code in the repository. Free-form questions are accepted, but Elasticsearch-style keyword queries work best. Use this tool first for any code-related questions. NOTE: By default, search handles stemming, case-insensitive matching, and camelCase/snake_case splitting automatically \u2014 do NOT manually try keyword variations like "getAllUsers" then "get_all_users" then "GetAllUsers". One search covers all variations.';
+    searchDelegateDescription = 'Search code in the repository by asking a question. Accepts natural language questions (e.g., "How does authentication work?", "Where is the user validation logic?"). A specialized subagent breaks down your question into targeted keyword searches and returns extracted code blocks. Do NOT formulate keyword queries yourself \u2014 just ask the question naturally.';
     queryDescription = "Search code using ast-grep structural pattern matching. Use this tool to find specific code structures like functions, classes, or methods.";
     extractDescription = "Extract code blocks from files based on file paths and optional line numbers. Use this tool to see complete context after finding relevant files. Line numbers from output can be used with edit start_line/end_line for precise editing.";
     delegateDescription = "Automatically delegate big distinct tasks to specialized probe subagents within the agentic loop. Used by AI agents to break down complex requests into focused, parallel tasks.";
@@ -36556,11 +36562,41 @@ function buildSearchDelegateTask({ searchQuery, searchPath, exact, language, all
     "- extract: Verify code snippets to ensure targets are actually relevant before including them.",
     "- listFiles: Understand directory structure to find where relevant code might live.",
     "",
-    "Strategy for complex queries:",
+    "CRITICAL - How probe search works (do NOT ignore):",
+    "- By default (exact=false), probe ALREADY handles stemming, case-insensitive matching, and camelCase/snake_case splitting.",
+    '- Searching "allowed_ips" ALREADY matches "AllowedIPs", "allowedIps", "allowed_ips", etc. Do NOT manually try case/style variations.',
+    '- Searching "getUserData" ALREADY matches "get", "user", "data" and their variations.',
+    "- NEVER repeat the same search query \u2014 you will get the same results.",
+    "- NEVER search trivial variations of the same keyword (e.g., AllowedIPs then allowedIps then allowed_ips). This is wasteful \u2014 probe handles it.",
+    "- If a search returns no results, the term likely does not exist in that path. Try a genuinely DIFFERENT keyword or concept, not a variation.",
+    "- If 2-3 consecutive searches return no results for a concept, STOP searching for it and move on.",
+    "",
+    "GOOD search strategy (do this):",
+    '  Query: "How does authentication work and how are sessions managed?"',
+    '  \u2192 search "authentication" \u2192 search "session management" (two different concepts)',
+    '  Query: "Find the IP allowlist middleware"',
+    '  \u2192 search "allowlist middleware" (one search, probe handles IP/ip/Ip variations)',
+    '  Query: "How does BM25 scoring work with SIMD optimization?"',
+    '  \u2192 search "BM25 scoring" \u2192 search "SIMD optimization" (two different concepts)',
+    "",
+    "BAD search strategy (never do this):",
+    '  \u2192 search "AllowedIPs" \u2192 search "allowedIps" \u2192 search "allowed_ips" (WRONG: these are trivial case variations, probe handles them)',
+    '  \u2192 search "CIDR" \u2192 search "cidr" \u2192 search "Cidr" \u2192 search "*cidr*" (WRONG: same keyword repeated with variations)',
+    '  \u2192 search "error handling" \u2192 search "error handling" \u2192 search "error handling" (WRONG: repeating exact same query)',
+    "",
+    "Keyword tips:",
+    "- Common programming keywords are filtered as stopwords when unquoted: function, class, return, new, struct, impl, var, let, const, etc.",
+    '- Avoid searching for these alone \u2014 combine with a specific term (e.g., "middleware function" is fine, "function" alone is too generic).',
+    '- To bypass stopword filtering: wrap terms in quotes ("return", "struct") or set exact=true. Both disable stemming and splitting too.',
+    "- Multiple words without operators use OR logic: foo bar = foo OR bar. Use AND explicitly if you need both: foo AND bar.",
+    '- camelCase terms are split: getUserData becomes "get", "user", "data" \u2014 so one search covers all naming styles.',
+    "",
+    "Strategy:",
     "1. Analyze the query - identify key concepts, entities, and relationships",
-    '2. Run focused searches for each independent concept (e.g., for "how do payments work and how are emails sent", search "payments" and "emails" separately since they are unrelated)',
-    "3. Use extract to verify relevance of promising results",
-    "4. Combine all relevant targets in your final response",
+    "2. Run ONE focused search per concept with the most natural keyword. Trust probe to handle variations.",
+    "3. If a search returns results, use extract to verify relevance",
+    "4. Only try a different keyword if the first one returned irrelevant results (not if it returned no results \u2014 that means the concept is absent)",
+    "5. Combine all relevant targets in your final response",
     "",
     `Query: ${searchQuery}`,
     `Search path(s): ${searchPath}`,
@@ -36613,9 +36649,12 @@ var init_vercel = __esm({
         }
         return result;
       };
+      const previousSearches = /* @__PURE__ */ new Set();
+      const paginationCounts = /* @__PURE__ */ new Map();
+      const MAX_PAGES_PER_QUERY = 3;
       return (0, import_ai.tool)({
         name: "search",
-        description: searchDelegate ? `${searchDescription} (delegates code search to a subagent and returns extracted code blocks)` : searchDescription,
+        description: searchDelegate ? searchDelegateDescription : searchDescription,
         inputSchema: searchSchema,
         execute: async ({ query: searchQuery, path: path9, allow_tests, exact, maxTokens: paramMaxTokens, language, session, nextPage }) => {
           const effectiveMaxTokens = paramMaxTokens || maxTokens;
@@ -36653,6 +36692,26 @@ var init_vercel = __esm({
             return await search(searchOptions);
           };
           if (!searchDelegate) {
+            const searchKey = `${searchQuery}::${searchPath}::${exact || false}`;
+            if (!nextPage) {
+              if (previousSearches.has(searchKey)) {
+                if (debug) {
+                  console.error(`[DEDUP] Blocked duplicate search: "${searchQuery}" in "${searchPath}"`);
+                }
+                return "DUPLICATE SEARCH BLOCKED: You already searched for this exact query in this path. Do NOT repeat the same search. If you need more results, set nextPage=true with the session ID from the previous search. Otherwise, try a genuinely different keyword, use extract to examine results you already found, or use attempt_completion if you have enough information.";
+              }
+              previousSearches.add(searchKey);
+              paginationCounts.set(searchKey, 0);
+            } else {
+              const pageCount = (paginationCounts.get(searchKey) || 0) + 1;
+              paginationCounts.set(searchKey, pageCount);
+              if (pageCount > MAX_PAGES_PER_QUERY) {
+                if (debug) {
+                  console.error(`[DEDUP] Blocked excessive pagination (page ${pageCount}/${MAX_PAGES_PER_QUERY}): "${searchQuery}" in "${searchPath}"`);
+                }
+                return `PAGINATION LIMIT REACHED: You have already retrieved ${MAX_PAGES_PER_QUERY} pages of results for this query. You have enough results \u2014 use extract to examine specific files, or use attempt_completion to return your findings.`;
+              }
+            }
             try {
               const result = maybeAnnotate(await runRawSearch());
               if (options.fileTracker && typeof result === "string") {
@@ -49524,6 +49583,7 @@ function generateSandboxGlobals(options) {
       executing.add(p5);
       results.push(p5);
       if (executing.size >= mapConcurrency) {
+        console.error(`[map] Concurrency limit reached (${executing.size}/${mapConcurrency}), waiting for a slot...`);
         await Promise.race(executing);
       }
     }
@@ -108916,6 +108976,7 @@ var init_ProbeAgent = __esm({
         this.completionPrompt = options.completionPrompt || null;
         this.thinkingEffort = options.thinkingEffort || null;
         const effectiveAllowedTools = options.disableTools ? [] : options.allowedTools;
+        this._rawAllowedTools = options.allowedTools;
         this.allowedTools = this._parseAllowedTools(effectiveAllowedTools);
         this.storageAdapter = options.storageAdapter || new InMemoryStorageAdapter();
         this.hooks = new HookManager();
@@ -109058,6 +109119,16 @@ var init_ProbeAgent = __esm({
       _filterMcpTools(mcpToolNames) {
         return mcpToolNames.filter((toolName) => this._isMcpToolAllowed(toolName));
       }
+      /**
+       * Check if query tool was explicitly listed in allowedTools (not via wildcard).
+       * Query (ast-grep) is excluded by default because models struggle with AST pattern syntax.
+       * @returns {boolean}
+       * @private
+       */
+      _isQueryExplicitlyAllowed() {
+        if (!this._rawAllowedTools) return false;
+        return Array.isArray(this._rawAllowedTools) && this._rawAllowedTools.includes("query");
+      }
       /**
        * Check if tracer is AppTracer (expects sessionId as first param) vs SimpleAppTracer
        * @returns {boolean} - True if tracer is AppTracer style (requires sessionId)
@@ -109351,7 +109422,7 @@ var init_ProbeAgent = __esm({
         if (wrappedTools.searchToolInstance && isToolAllowed("search")) {
           this.toolImplementations.search = wrappedTools.searchToolInstance;
         }
-        if (wrappedTools.queryToolInstance && isToolAllowed("query")) {
+        if (wrappedTools.queryToolInstance && isToolAllowed("query") && this._isQueryExplicitlyAllowed()) {
           this.toolImplementations.query = wrappedTools.queryToolInstance;
         }
         if (wrappedTools.extractToolInstance && isToolAllowed("extract")) {
@@ -110290,12 +110361,13 @@ var init_ProbeAgent = __esm({
         const toolMap = {
           search: {
             schema: searchSchema,
-            description: "Search code in the repository using keyword queries with Elasticsearch syntax."
-          },
-          query: {
-            schema: querySchema,
-            description: "Search code using ast-grep structural pattern matching."
+            description: this.searchDelegate ? "Search code in the repository by asking a question. Accepts natural language questions \u2014 a subagent breaks them into targeted keyword searches and returns extracted code blocks. Do NOT formulate keyword queries yourself." : "Search code in the repository using keyword queries with Elasticsearch syntax. Handles stemming, case-insensitive matching, and camelCase/snake_case splitting automatically \u2014 do NOT try keyword variations manually."
           },
+          // query tool (ast-grep) removed from AI-facing tools — models struggle with pattern syntax
+          // query: {
+          //   schema: querySchema,
+          //   description: 'Search code using ast-grep structural pattern matching.'
+          // },
           extract: {
             schema: extractSchema,
             description: "Extract code blocks from files based on file paths and optional line numbers."
@@ -110963,25 +111035,27 @@ ${this.architectureContext.content}
         } else {
           systemPrompt += predefinedPrompts["code-explorer"] + "\n\n";
         }
+        const searchToolDesc1 = this.searchDelegate ? '- search: Ask natural language questions to find code (e.g., "How does authentication work?"). A subagent handles keyword searches and returns extracted code blocks. Do NOT formulate keyword queries \u2014 just ask questions.' : "- search: Find code patterns using keyword queries with Elasticsearch syntax. Handles stemming and case variations automatically \u2014 do NOT try manual keyword variations.";
         systemPrompt += `You have access to powerful code search and analysis tools through MCP:
-- search: Find code patterns using semantic search
+${searchToolDesc1}
 - extract: Extract specific code sections with context
-- query: Use AST patterns for structural code matching
 - listFiles: Browse directory contents
 - searchFiles: Find files by name patterns`;
         if (this.enableBash) {
           systemPrompt += `
 - bash: Execute bash commands for system operations`;
         }
-        const searchGuidance = this.searchDelegate ? "1. Start with search to retrieve extracted code blocks" : "1. Start with search to find relevant code patterns";
-        const extractGuidance = this.searchDelegate ? "2. Use extract only if you need more context or a full file" : "2. Use extract to get detailed context when needed";
+        const searchGuidance1 = this.searchDelegate ? "1. Start with search \u2014 ask a question about what you want to understand. It returns extracted code blocks directly." : "1. Start with search to find relevant code patterns. One search per concept is usually enough \u2014 probe handles stemming and case variations.";
+        const extractGuidance1 = this.searchDelegate ? "2. Use extract only if you need more context or a full file" : "2. Use extract to get detailed context when needed";
         systemPrompt += `
 
 When exploring code:
-${searchGuidance}
-${extractGuidance}
+${searchGuidance1}
+${extractGuidance1}
 3. Prefer focused, specific searches over broad queries
-4. Combine multiple tools to build complete understanding`;
+4. Do NOT repeat the same search or try trivial keyword variations \u2014 probe handles stemming and case variations automatically
+5. If 2-3 consecutive searches return no results for a concept, stop searching for it \u2014 the term likely does not exist in that codebase
+6. Combine multiple tools to build complete understanding`;
         if (this.allowedFolders && this.allowedFolders.length > 0) {
           systemPrompt += `
 
@@ -111016,25 +111090,27 @@ Workspace: ${this.allowedFolders.join(", ")}`;
         } else {
           systemPrompt += predefinedPrompts["code-explorer"] + "\n\n";
         }
+        const searchToolDesc2 = this.searchDelegate ? '- search: Ask natural language questions to find code (e.g., "How does authentication work?"). A subagent handles keyword searches and returns extracted code blocks. Do NOT formulate keyword queries \u2014 just ask questions.' : "- search: Find code patterns using keyword queries with Elasticsearch syntax. Handles stemming and case variations automatically \u2014 do NOT try manual keyword variations.";
         systemPrompt += `You have access to powerful code search and analysis tools through MCP:
-- search: Find code patterns using semantic search
+${searchToolDesc2}
 - extract: Extract specific code sections with context
-- query: Use AST patterns for structural code matching
 - listFiles: Browse directory contents
 - searchFiles: Find files by name patterns`;
         if (this.enableBash) {
           systemPrompt += `
 - bash: Execute bash commands for system operations`;
         }
-        const searchGuidance = this.searchDelegate ? "1. Start with search to retrieve extracted code blocks" : "1. Start with search to find relevant code patterns";
-        const extractGuidance = this.searchDelegate ? "2. Use extract only if you need more context or a full file" : "2. Use extract to get detailed context when needed";
+        const searchGuidance2 = this.searchDelegate ? "1. Start with search \u2014 ask a question about what you want to understand. It returns extracted code blocks directly." : "1. Start with search to find relevant code patterns. One search per concept is usually enough \u2014 probe handles stemming and case variations.";
+        const extractGuidance2 = this.searchDelegate ? "2. Use extract only if you need more context or a full file" : "2. Use extract to get detailed context when needed";
         systemPrompt += `
 
 When exploring code:
-${searchGuidance}
-${extractGuidance}
+${searchGuidance2}
+${extractGuidance2}
 3. Prefer focused, specific searches over broad queries
-4. Combine multiple tools to build complete understanding`;
+4. Do NOT repeat the same search or try trivial keyword variations \u2014 probe handles stemming and case variations automatically
+5. If 2-3 consecutive searches return no results for a concept, stop searching for it \u2014 the term likely does not exist in that codebase
+6. Combine multiple tools to build complete understanding`;
         if (this.allowedFolders && this.allowedFolders.length > 0) {
           systemPrompt += `
 
@@ -111085,10 +111161,10 @@ Workspace: ${this.allowedFolders.join(", ")}`;
 Follow these instructions carefully:
 1. Analyze the user's request.
 2. Use the available tools step-by-step to fulfill the request.
-3. You should always prefer the search tool for code-related questions.${this.searchDelegate ? " It already returns extracted code blocks; use extract only to expand context or read full files." : " Read full files only if really necessary."}
+3. You should always prefer the search tool for code-related questions.${this.searchDelegate ? " Ask natural language questions \u2014 the search subagent handles keyword formulation and returns extracted code blocks. Use extract only to expand context or read full files." : " Search handles stemming and case variations automatically \u2014 do NOT try keyword variations manually. Read full files only if really necessary."}
 4. Ensure to get really deep and understand the full picture before answering.
 5. Once the task is fully completed, use the attempt_completion tool to provide the final result.
-6. Prefer concise and focused search queries. Use specific keywords and phrases to narrow down results.${this.allowEdit ? `
+6. ${this.searchDelegate ? "Ask clear, specific questions when searching. Each search should target a distinct concept or question." : "Prefer concise and focused search queries. Use specific keywords and phrases to narrow down results."}${this.allowEdit ? `
 7. When modifying files, choose the appropriate tool:
     - Use 'edit' for all code modifications:
       * PREFERRED: Use start_line (and optionally end_line) for line-targeted editing \u2014 this is the safest and most precise approach.${this.hashLines ? ' Use the line:hash references from extract/search output (e.g. "42:ab") for integrity verification.' : ""} Always use extract first to see line numbers${this.hashLines ? " and hashes" : ""}, then edit by line reference.