@probelabs/probe 0.6.0-rc279 → 0.6.0-rc280

package/src/agent/ProbeAgent.js

@@ -254,6 +254,7 @@ export class ProbeAgent {
     // Supports exclusion with '!' prefix: ['*', '!bash'] = all tools except bash
     // disableTools is a convenience flag that overrides allowedTools to []
     const effectiveAllowedTools = options.disableTools ? [] : options.allowedTools;
+    this._rawAllowedTools = options.allowedTools; // Keep raw value for explicit tool checks
     this.allowedTools = this._parseAllowedTools(effectiveAllowedTools);
 
     // Storage adapter (defaults to in-memory)
@@ -481,6 +482,17 @@ export class ProbeAgent {
     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)
@@ -837,7 +849,9 @@ export class ProbeAgent {
     if (wrappedTools.searchToolInstance && isToolAllowed('search')) {
       this.toolImplementations.search = wrappedTools.searchToolInstance;
     }
-    if (wrappedTools.queryToolInstance && isToolAllowed('query')) {
+    // query tool (ast-grep) is not exposed to AI by default — models struggle with AST pattern syntax.
+    // Only register it when explicitly listed in allowedTools (not via wildcard '*').
+    if (wrappedTools.queryToolInstance && isToolAllowed('query') && this._isQueryExplicitlyAllowed()) {
       this.toolImplementations.query = wrappedTools.queryToolInstance;
     }
     if (wrappedTools.extractToolInstance && isToolAllowed('extract')) {
@@ -2008,12 +2022,15 @@ export class ProbeAgent {
     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 — 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 — 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.'
@@ -2849,10 +2866,12 @@ export class ProbeAgent {
     }
 
     // Add high-level instructions about when to use tools
+    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 — just ask questions.'
+      : '- search: Find code patterns using keyword queries with Elasticsearch syntax. Handles stemming and case variations automatically — 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`;
 
@@ -2860,19 +2879,21 @@ export class ProbeAgent {
       systemPrompt += `\n- 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
+    const searchGuidance1 = this.searchDelegate
+      ? '1. Start with search — 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 — 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 += `\n
 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 — probe handles stemming and case variations automatically
+5. If 2-3 consecutive searches return no results for a concept, stop searching for it — the term likely does not exist in that codebase
+6. Combine multiple tools to build complete understanding`;
 
     // Add workspace context
     if (this.allowedFolders && this.allowedFolders.length > 0) {
@@ -2911,10 +2932,12 @@ ${extractGuidance}
     }
 
     // Add high-level instructions about when to use tools
+    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 — just ask questions.'
+      : '- search: Find code patterns using keyword queries with Elasticsearch syntax. Handles stemming and case variations automatically — 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`;
 
@@ -2922,19 +2945,21 @@ ${extractGuidance}
       systemPrompt += `\n- 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
+    const searchGuidance2 = this.searchDelegate
+      ? '1. Start with search — 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 — 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 += `\n
 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 — probe handles stemming and case variations automatically
+5. If 2-3 consecutive searches return no results for a concept, stop searching for it — the term likely does not exist in that codebase
+6. Combine multiple tools to build complete understanding`;
 
     // Add workspace context
     if (this.allowedFolders && this.allowedFolders.length > 0) {
@@ -2990,10 +3015,10 @@ ${extractGuidance}
 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 — 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 — 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 — 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.

package/src/agent/dsl/environment.js

@@ -284,6 +284,7 @@ export function generateSandboxGlobals(options) {
       results.push(p);
 
       if (executing.size >= mapConcurrency) {
+        console.error(`[map] Concurrency limit reached (${executing.size}/${mapConcurrency}), waiting for a slot...`);
         await Promise.race(executing);
       }
     }

package/src/delegate.js

@@ -122,20 +122,20 @@ class DelegationManager {
 		}
 
 		// Need to wait in queue
-		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)`);
 
 		// Create a promise that will be resolved when a slot becomes available
 		// or rejected if session limit is exceeded or queue timeout expires
 		return new Promise((resolve, reject) => {
+			const queuedAt = Date.now();
 			const entry = {
 				resolve: null,  // Will be wrapped below
 				reject: null,   // Will be wrapped below
 				parentSessionId,
 				debug,
-				queuedAt: Date.now(),
-				timeoutId: null
+				queuedAt,
+				timeoutId: null,
+				reminderId: null
 			};
 
 			// Wrap resolve/reject to clear timeout and prevent double-settling
@@ -144,12 +144,14 @@ class DelegationManager {
 				if (settled) return;
 				settled = true;
 				if (entry.timeoutId) clearTimeout(entry.timeoutId);
+				if (entry.reminderId) clearInterval(entry.reminderId);
 				resolve(value);
 			};
 			entry.reject = (error) => {
 				if (settled) return;
 				settled = true;
 				if (entry.timeoutId) clearTimeout(entry.timeoutId);
+				if (entry.reminderId) clearInterval(entry.reminderId);
 				reject(error);
 			};
 
@@ -165,6 +167,15 @@ class DelegationManager {
 				}, effectiveTimeout);
 			}
 
+			// Always emit periodic wait visibility while queued.
+			entry.reminderId = setInterval(() => {
+				const waitedSeconds = Math.round((Date.now() - queuedAt) / 1000);
+				console.error(`[DelegationManager] Still waiting for slot (${waitedSeconds}s). ${this.globalActive}/${this.maxConcurrent} active, ${this.waitQueue.length} queued.`);
+			}, 15000);
+			if (entry.reminderId.unref) {
+				entry.reminderId.unref();
+			}
+
 			this.waitQueue.push(entry);
 		});
 	}
@@ -221,9 +232,7 @@ class DelegationManager {
 				if (sessionCount >= this.maxPerSession) {
 					// Session limit reached - reject with error (consistent with tryAcquire behavior)
 					// This is a hard limit, not something that will resolve by waiting longer
-					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, error: new Error(`Maximum delegations per session (${this.maxPerSession}) reached for session ${parentSessionId}`) });
 					// Continue to process next item in queue
 					continue;
@@ -233,10 +242,8 @@ class DelegationManager {
 			// Grant the slot
 			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(resolve);
 		}
@@ -296,6 +303,9 @@ class DelegationManager {
 			if (entry.timeoutId) {
 				clearTimeout(entry.timeoutId);
 			}
+			if (entry.reminderId) {
+				clearInterval(entry.reminderId);
+			}
 			// Reject pending entries so they don't hang
 			if (entry.reject) {
 				entry.reject(new Error('DelegationManager was cleaned up'));

package/src/downloader.js

@@ -95,9 +95,7 @@ async function acquireFileLock(lockPath, version) {
 	try {
 		// Try to create lock file atomically (fails if already exists)
 		await fs.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 (error) {
 		if (error.code === 'EEXIST') {
@@ -108,17 +106,13 @@ async function acquireFileLock(lockPath, version) {
 
 				if (lockAge > LOCK_TIMEOUT_MS) {
 					// Lock is stale, remove it
-					if (process.env.DEBUG === '1' || process.env.VERBOSE === '1') {
-						console.log(`Removing stale lock file (age: ${Math.round(lockAge / 1000)}s, pid: ${existingLock.pid})`);
-					}
+					console.log(`Removing stale lock file (age: ${Math.round(lockAge / 1000)}s, pid: ${existingLock.pid})`);
 					await fs.remove(lockPath);
 					return false; // Caller should retry
 				}
 
 				// Lock is fresh, another process is downloading
-				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) {
 				// Can't read lock file, might be corrupted - remove it
@@ -180,23 +174,23 @@ 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}`);
 
 	// Poll in a loop until binary appears, lock expires, or we timeout
 	while (Date.now() - startTime < MAX_LOCK_WAIT_MS) {
 		// Check #1: Is the binary now available?
 		if (await fs.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) / 1000);
+			console.log(`Binary now available at ${binaryPath}, download completed by another process (waited ${waitedSeconds}s)`);
 			return true;
 		}
 
 		// Check #2: Is the lock file gone? (download finished or failed)
 		const lockExists = await fs.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;
 		}
 
@@ -205,22 +199,24 @@ async function waitForFileLock(lockPath, binaryPath) {
 			const lockData = JSON.parse(await fs.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 / 1000)}s), will retry download`);
-				}
+				console.log(`Lock expired (age: ${Math.round(lockAge / 1000)}s), will retry download`);
 				return false;
 			}
 		} catch {
 			// Ignore errors reading lock file - will retry on next poll
 		}
 
+		if (Date.now() - lastStatusTime >= 15000) {
+			const elapsedSeconds = Math.round((Date.now() - startTime) / 1000);
+			console.log(`Still waiting for file lock (${elapsedSeconds}s/${MAX_LOCK_WAIT_MS / 1000}s max)`);
+			lastStatusTime = Date.now();
+		}
+
 		// Wait 1 second before checking again
 		await new Promise(resolve => setTimeout(resolve, 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 / 1000}s`);
 	return false;
 }
 
@@ -247,9 +243,7 @@ async function withDownloadLock(version, 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 (error) {
@@ -262,10 +256,16 @@ async function withDownloadLock(version, downloadFn) {
 	}
 
 	// Create new download promise with timeout protection
+	let timeoutId = null;
 	const downloadPromise = Promise.race([
 		downloadFn(),
 		new Promise((_, reject) =>
-			setTimeout(() => reject(new Error(`Download timeout after ${LOCK_TIMEOUT_MS / 1000}s`)), LOCK_TIMEOUT_MS)
+			{
+				timeoutId = setTimeout(() => reject(new Error(`Download timeout after ${LOCK_TIMEOUT_MS / 1000}s`)), LOCK_TIMEOUT_MS);
+				if (timeoutId.unref) {
+					timeoutId.unref();
+				}
+			}
 		)
 	]);
 
@@ -278,6 +278,9 @@ async function withDownloadLock(version, downloadFn) {
 		const result = await downloadPromise;
 		return result;
 	} finally {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+		}
 		// Clean up lock after download completes (success or failure)
 		downloadLocks.delete(lockKey);
 	}

package/src/tools/analyzeAll.js

@@ -227,18 +227,14 @@ async function processChunksParallel(chunks, extractionPrompt, maxWorkers, optio
 
 			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}`);
 		}
 	}
 

package/src/tools/common.js

@@ -8,7 +8,7 @@ import { resolve, isAbsolute } from 'path';
 
 // Common schemas for tool parameters (used for internal execution after XML parsing)
 export const searchSchema = z.object({
-	query: z.string().describe('Search query with Elasticsearch syntax. Use quotes for exact matches, AND/OR for boolean logic, - for negation.'),
+	query: z.string().describe('Search query — 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: z.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: z.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: z.number().nullable().optional().describe('Maximum tokens to return. Default is 20000. Set to null for unlimited results.'),
@@ -17,7 +17,7 @@ export const searchSchema = z.object({
 });
 
 export const searchAllSchema = z.object({
-	query: z.string().describe('Search query with Elasticsearch syntax. Use quotes for exact matches, AND/OR for boolean logic, - for negation.'),
+	query: z.string().describe('Search query — 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: z.string().optional().default('.').describe('Path to search in.'),
 	exact: z.boolean().optional().default(false).describe('Use exact matching instead of stemming.'),
 	maxTokensPerPage: z.number().optional().default(20000).describe('Tokens per page when paginating. Default 20000.'),
@@ -149,7 +149,8 @@ export const attemptCompletionSchema = {
 
 // Tool descriptions (used by Vercel tool() definitions)
 
-export const 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.';
+export const 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 — do NOT manually try keyword variations like "getAllUsers" then "get_all_users" then "GetAllUsers". One search covers all variations.';
+export const 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 — just ask the question naturally.';
 export const queryDescription = 'Search code using ast-grep structural pattern matching. Use this tool to find specific code structures like functions, classes, or methods.';
 export const 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.';
 export const 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.';

package/src/tools/vercel.js

@@ -9,7 +9,7 @@ import { query } from '../query.js';
 import { extract } from '../extract.js';
 import { delegate } from '../delegate.js';
 import { analyzeAll } from './analyzeAll.js';
-import { searchSchema, querySchema, extractSchema, delegateSchema, analyzeAllSchema, searchDescription, queryDescription, extractDescription, delegateDescription, analyzeAllDescription, parseTargets, parseAndResolvePaths, resolveTargetPath } from './common.js';
+import { searchSchema, querySchema, extractSchema, delegateSchema, analyzeAllSchema, searchDescription, searchDelegateDescription, queryDescription, extractDescription, delegateDescription, analyzeAllDescription, parseTargets, parseAndResolvePaths, resolveTargetPath } from './common.js';
 import { existsSync } from 'fs';
 import { formatErrorForAI } from '../utils/error-types.js';
 import { annotateOutputWithHashes } from './hashline.js';
@@ -143,11 +143,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 — 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 — 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?"',
+		'  → search "authentication" → search "session management" (two different concepts)',
+		'  Query: "Find the IP allowlist middleware"',
+		'  → search "allowlist middleware" (one search, probe handles IP/ip/Ip variations)',
+		'  Query: "How does BM25 scoring work with SIMD optimization?"',
+		'  → search "BM25 scoring" → search "SIMD optimization" (two different concepts)',
+		'',
+		'BAD search strategy (never do this):',
+		'  → search "AllowedIPs" → search "allowedIps" → search "allowed_ips" (WRONG: these are trivial case variations, probe handles them)',
+		'  → search "CIDR" → search "cidr" → search "Cidr" → search "*cidr*" (WRONG: same keyword repeated with variations)',
+		'  → search "error handling" → search "error handling" → 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 — 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" — 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 — that means the concept is absent)',
+		'5. Combine all relevant targets in your final response',
 		'',
 		`Query: ${searchQuery}`,
 		`Search path(s): ${searchPath}`,
@@ -186,10 +216,16 @@ export const searchTool = (options = {}) => {
 		return result;
 	};
 
+	// Track previous non-paginated searches to detect and block duplicates
+	const previousSearches = new Set();
+	// Track pagination counts per query to cap runaway pagination
+	const paginationCounts = new Map();
+	const MAX_PAGES_PER_QUERY = 3;
+
 	return tool({
 		name: 'search',
 		description: searchDelegate
-			? `${searchDescription} (delegates code search to a subagent and returns extracted code blocks)`
+			? searchDelegateDescription
 			: searchDescription,
 		inputSchema: searchSchema,
 		execute: async ({ query: searchQuery, path, allow_tests, exact, maxTokens: paramMaxTokens, language, session, nextPage }) => {
@@ -236,6 +272,29 @@ export const searchTool = (options = {}) => {
 			};
 
 			if (!searchDelegate) {
+				// Block duplicate non-paginated searches (models sometimes repeat the exact same call)
+				// Allow pagination: only nextPage=true is a legitimate repeat of the same query
+				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 {
+					// Cap pagination to prevent runaway page-through of broad queries
+					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 — use extract to examine specific files, or use attempt_completion to return your findings.`;
+					}
+				}
 				try {
 					const result = maybeAnnotate(await runRawSearch());
 					// Track files found in search results for staleness detection