@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/orchestration/researcher-executor.ts

@@ -0,0 +1,394 @@
+/**
+ * Researcher Executor
+ *
+ * Handles execution of individual researchers
+ */
+
+import type { ResearchMessage } from '../types/index.ts';
+import type { SystemResearchState } from './deep-research-types.ts';
+import { createResearcherSession } from './researcher.ts';
+import { registerScrapedLinks } from '../utils/shared-links.ts';
+import { ensureAssistantResponse } from '../utils/text-utils.ts';
+import { extractUsage } from '../types/llm.ts';
+import { logger } from '../logger.ts';
+import { metrics } from '../utils/metrics.ts';
+import { ServiceNames,
+  type IResearchSynthesisService,
+} from '../core/service-interfaces.ts';
+import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
+import type { ResearchSessionService } from './research-session-service.ts';
+import { loadPrompt } from '../core/llm/prompts.ts';
+import { injectCurrentDate } from '../core/llm/inject-date.ts';
+import { recordResearcherFailure, getSteeringMessages } from './session-state.ts';
+import type { RunResearcherOptions } from './orchestration-types.ts';
+
+/**
+ * Run a single researcher with retries
+ */
+export async function runResearcher(options: RunResearcherOptions): Promise<void> {
+  const {
+    config: researcherConfig,
+    initialLinks,
+    historicalUrls,
+    researchId,
+    round,
+    query,
+    complexity,
+    ctx,
+    model,
+    researchConfig: config,
+    planningService,
+    observer,
+    signal,
+    sessionId,
+  } = options;
+  
+  const id = String(researcherConfig.id);
+  const container = tryGetServiceContainerFromCtx(ctx);
+  observer?.onResearcherStart?.(id, researcherConfig.name, researcherConfig.goal, round);
+  metrics.increment('researchers_launched_total', 1, { mode: 'deep', complexity: String(complexity), round: String(round) });
+
+  const currentPlan = planningService.getCurrentPlan(researchId);
+  const previousQueriesSection = currentPlan?.allQueries && currentPlan.allQueries.length > 0
+    ? `\n### Previous Queries (Sibling Researchers)\n${currentPlan.allQueries.map((q: string) => `- ${q}`).join('\n')}\n`
+    : '';
+
+  let storeSection = '';
+  if (historicalUrls.length > 0) {
+    storeSection = '\n## Knowledge Store\n' +
+      'The following URLs were found in the knowledge store from previous research sessions. ' +
+      'Scrape each URL to retrieve its full current content. The summary below describes what was previously found at that URL — use it as a guide for what to expect.\n' +
+      historicalUrls.map(e => `- ${e.url}\n  Previous summary: ${e.description}`).join('\n');
+  }
+
+  const researcherPromptTemplate = loadPrompt('researcher');
+  if (initialLinks.length === 0 && historicalUrls.length === 0) {
+    logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links; skipping.`);
+    // Use the resolved sessionId (= piSessionId), NOT the raw ctx.sessionId: when
+    // ctx.sessionId is unset but sessionManager supplies a real id (common in SDK
+    // use), recording under ctx.sessionId would file this no-links skip under a
+    // different id than shouldStopResearch() checks, so the fast-stop guard would
+    // under-count exactly the broad-search-failure case it exists to catch.
+    recordResearcherFailure(sessionId, researchId, id);
+    metrics.increment('researcher_skipped_total', 1, { mode: 'deep', complexity: String(complexity), reason: 'no_initial_links' });
+    observer?.onResearcherFailure?.(id, 'No initial search results or historical links available');
+    return;
+  }
+
+  let evidenceSection = '';
+  if (initialLinks.length > 0) {
+    evidenceSection = `## Evidence Provided\nInitial search results provided the following URLs to investigate:\n${initialLinks.map(l => `- ${l}`).join('\n')}`;
+  }
+
+  const maxAttempts = config.RESEARCHER_MAX_RETRIES + 1;
+  let lastError: unknown;
+  const researcherExecutionStartMs = Date.now();
+  const deliveredSteeringIds = new Set<string>();
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (attempt > 1) {
+      const delay = Math.min(1000 * Math.pow(2, attempt - 2), config.RESEARCHER_MAX_RETRY_DELAY_MS);
+      logger.warn(`[ResearcherExecutor] Researcher ${id} retry ${attempt - 1}/${config.RESEARCHER_MAX_RETRIES} after ${delay}ms`);
+      observer?.onResearcherProgress?.(id, 'retry');
+      await new Promise(r => setTimeout(r, delay));
+    }
+
+    // Generate prompt for this attempt, incorporating ALL steering messages delivered so far
+    const allSteering = getSteeringMessages(sessionId);
+    let steeringSection = '';
+    if (allSteering.length > 0) {
+        steeringSection = '\n\n### ADDITIONAL USER GUIDANCE (Mandatory directional rules for your research)\n' +
+            allSteering.map(m => {
+                deliveredSteeringIds.add(m.id);
+                return `- ${m.text}`;
+            }).join('\n');
+    }
+
+    const prompt = injectCurrentDate(researcherPromptTemplate, 'researcher')
+      // Function replacers so a `$`-bearing dynamic value (scraped evidence, store
+      // descriptions, or an LLM-authored goal containing $&, $$, $1, …) is inserted
+      // literally instead of being interpreted as a String.replace substitution pattern.
+      .replace('{{goal}}', () => researcherConfig.goal)
+      .replace('{{store_section}}', () => storeSection)
+      .replace('{{evidence_section}}', () => evidenceSection)
+      .replace('{{coordination_section}}', () => previousQueriesSection)
+      .replace('{{extra_tool_guidelines}}', '')
+      .trim() + steeringSection;
+
+    logger.debug(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} System Prompt:\n${prompt}`);
+
+    const workerExclude = ['search'];
+    const mergedExclude = [...new Set([...workerExclude, ...(options.excludeTools || [])])];
+
+    // Grounding gate: when the scrape tool is enabled for this researcher, a report grounded in
+    // NO real source (and no knowledge-store summaries to fall back on) is ungrounded.
+    // A researcher is grounded when it retrieved real content from any content-retrieval tool:
+    //   - successfulScrapeCount: successes the scrape tool reports (fresh fetches AND cache hits)
+    //     via the onUrlScrapeResult callback below. youtube_transcript routes its per-video
+    //     successes through the SAME callback, so transcript fetches count here too.
+    //   - nonScrapeGroundingHits: real items returned by the non-URL grounding tools
+    //     (security_search, stackexchange), reported uniformly as details.groundingHits on the
+    //     tool_execution_end event. (grep is local code search, not a web-research source, and
+    //     wraps an opaque SDK result, so it is intentionally NOT a grounding signal.)
+    //   - historicalUrls: knowledge-store summaries supplied to this researcher.
+    // Per-attempt: each retry builds a fresh session, so both counts reset at the top of the body.
+    //
+    // The gate is a PRODUCTION guard against ungrounded real research. It does not apply when
+    // scraping is mocked: PI_RESEARCH_MOCK_SCRAPE (a TEST-ONLY mode, not a product feature)
+    // serves a tiny stub that never passes content validation, so there are zero real scrapes
+    // by design — applying the gate there would fail every researcher even with a capable model
+    // (which is exactly what made mocked demo/test runs look like "the model can't research").
+    const scrapeEnabled = !mergedExclude.includes('scrape') && process.env['PI_RESEARCH_MOCK_SCRAPE'] !== 'true';
+    let successfulScrapeCount = 0;
+    let nonScrapeGroundingHits = 0;
+
+    const { session, resolvedModel } = await createResearcherSession({
+      cwd: ctx.cwd,
+      ctxModel: model,
+      modelRegistry: ctx.modelRegistry,
+      systemPrompt: prompt,
+      extensionCtx: ctx,
+      excludeTools: mergedExclude,
+      researcherId: id,
+      config,
+      getGlobalState: (): SystemResearchState => ({
+        version: 1,
+        researchId,
+        rootQuery: query,
+        complexity,
+        currentRound: round,
+        status: 'researching',
+        lastUpdated: Date.now(),
+        initialAgenda: [],
+        allScrapedLinks: [],
+        aspects: {},
+      }),
+      updateGlobalLinks: (links) => registerScrapedLinks(researchId, links),
+      onSearchProgress: (links) => {
+        observer?.onResearcherProgress?.(id, `${links} results`);
+      },
+      onUrlScrapeResult: (_url, success) => {
+        if (success) successfulScrapeCount++;
+        observer?.onToolResult?.(id, success);
+      },
+    });
+
+    // Hand the freshly-created AgentSession to the cleanup machinery before any
+    // other work. createResearcherSession() above already allocated a live
+    // session; if resolving/registering the session service throws (container
+    // disposed mid-run, race), the session is not yet owned by
+    // cleanupResearchServices and would leak unaborted. Abort it directly on any
+    // failure in this window, then rethrow. (Same acquire-before-teardown-wired
+    // class as the ghost-panel fix.)
+    // Undefined until the registration below succeeds: if getService throws, the
+    // finally must NOT dereference it (that TypeError would mask the real error).
+    let sessionService: ResearchSessionService | undefined;
+    try {
+      sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
+      sessionService.registerSession(researchId, id, session, () => session.abort().catch((err) => logger.warn('[ResearcherExecutor] Session abort failed:', err)));
+    } catch (registrationError) {
+      await session.abort().catch(() => { /* best-effort: session is being discarded */ });
+      throw registrationError;
+    }
+
+    let lastSteeringCheck = Date.now();
+
+    // User-supplied observer callbacks (SDK consumers) are invoked from inside
+    // session event dispatch — a throw there would propagate into the session's
+    // event loop. Isolate them the way TuiPulse isolates its subscribers.
+    const safeObserve = (fn: () => void): void => {
+      try { fn(); } catch (err) { logger.debug('[ResearcherExecutor] Observer callback threw:', err); }
+    };
+
+    const subscription = session.subscribe((event: any) => {
+      // Check for new steering messages periodically
+      const now = Date.now();
+      if (now - lastSteeringCheck > 500) {
+        lastSteeringCheck = now;
+        const allSteering = getSteeringMessages(sessionId);
+        for (const msg of allSteering) {
+          if (!deliveredSteeringIds.has(msg.id)) {
+            deliveredSteeringIds.add(msg.id);
+            session.steer(msg.text).catch(e => logger.warn('[ResearcherExecutor] Failed to deliver steering:', e));
+            logger.debug(`[ResearcherExecutor] Delivered mid-flight steering message to ${id}: ${msg.text}`);
+          }
+        }
+      }
+
+      if (event.type === 'message_update') {
+        const ame = event.assistantMessageEvent as any;
+        if (ame?.type === 'start') {
+          const inputTokens: number = ame.partial?.usage?.input ?? 0;
+          if (inputTokens > 0) {
+            safeObserve(() => observer?.onResearcherTokensHint?.(id, inputTokens));
+          }
+        }
+      } else if (event.type === 'message_end') {
+        const msg = event.message as unknown as ResearchMessage;
+        if (msg?.['role'] !== 'assistant') return;
+
+        const rawUsage = msg['usage'] as any;
+        if (rawUsage) {
+          const { tokens, cost } = extractUsage(resolvedModel, rawUsage);
+
+          if (tokens > 0 || cost > 0) {
+            metrics.increment('llm_tokens_total', tokens, { component: 'researcher', complexity: String(complexity) });
+            metrics.increment('llm_cost_total', cost, { component: 'researcher', complexity: String(complexity) });
+            safeObserve(() => observer?.onResearcherProgress?.(id, undefined, tokens, cost));
+            safeObserve(() => observer?.onTokensConsumed?.(tokens, cost));
+          }
+        }
+      } else if (event.type === 'tool_execution_start') {
+        safeObserve(() => observer?.onResearcherProgress?.(id, `${event.toolName}`));
+      } else if (event.type === 'tool_execution_end') {
+        safeObserve(() => observer?.onResearcherProgress?.(id, `done:${event.toolName}`));
+        // Per-tool flash for non-scrape tools (scrape uses per-URL callback instead)
+        if (event.toolName !== 'scrape') {
+          safeObserve(() => observer?.onToolResult?.(id, !event.isError));
+        }
+        // Grounding accumulation for the non-URL grounding tools. They don't go through
+        // onUrlScrapeResult, so they report how many real items they retrieved via a uniform
+        // details.groundingHits field (e.g. security_search = vulnerabilities found,
+        // stackexchange = questions/answers returned). Soft-failures (rate-limit, API error,
+        // empty result) omit it or report 0, so they correctly do NOT count as grounding.
+        const details = (event.result as { details?: { groundingHits?: unknown } } | undefined)?.details;
+        const hits = details?.groundingHits;
+        if (typeof hits === 'number' && hits > 0) {
+          nonScrapeGroundingHits += hits;
+        }
+      }
+    });
+
+    try {
+      let timeoutId: NodeJS.Timeout | undefined;
+      const timeoutPromise = new Promise<void>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          const msg = `Researcher ${id} (${researcherConfig.name}) timed out after ${config.RESEARCHER_TIMEOUT_MS}ms`;
+          session.abort().catch((err) => {
+            logger.warn('[ResearcherExecutor] Failed to abort timed-out researcher session:', err);
+          }).finally(() => reject(new Error(msg)));
+        }, config.RESEARCHER_TIMEOUT_MS);
+      });
+
+      let abortCleanup: (() => void) | undefined;
+      try {
+        const promptPromise = session.prompt(`Topic: ${researcherConfig.name}\nGoal: ${researcherConfig.goal}\n\nPerform your research and submit your full report now.`);
+        promptPromise.catch((err: Error) => logger.debug(`[ResearcherExecutor] Background session prompt rejection: ${err.message}`));
+        await Promise.race([
+          promptPromise,
+          timeoutPromise,
+          ...(signal ? [
+            new Promise<never>((_, reject) => {
+              const onAbort = () => {
+                session.abort().catch(err => logger.warn('[ResearcherExecutor] Failed to abort session on signal:', err));
+                reject(new Error('Aborted'));
+              };
+              if (signal.aborted) {
+                onAbort();
+              } else {
+                signal.addEventListener('abort', onAbort, { once: true });
+                abortCleanup = () => signal.removeEventListener('abort', onAbort);
+              }
+            })
+          ] : []),
+        ]);
+      } finally {
+        clearTimeout(timeoutId);
+        abortCleanup?.();
+      }
+
+      const responseText = ensureAssistantResponse(session, id);
+      const researcherDuration = Date.now() - researcherExecutionStartMs;
+      metrics.observe('researcher_execution_latency_ms', researcherDuration, { mode: 'deep', complexity: String(complexity), round: String(round) });
+      logger.debug(`[ResearcherExecutor] Researcher ${id} Final Response:\n${responseText}`);
+
+      // Grounding gate (see scrapeEnabled / successfulScrapeCount above). A deep researcher
+      // cannot search (workerExclude = ['search']); scrape is its only path to real sources.
+      // If scrape was available but produced zero successful fetches AND no knowledge-store
+      // summaries were supplied (historicalUrls), the report is not grounded in any source —
+      // do NOT land it. Retry first (a transiently blocked scrape may recover); on the final
+      // attempt this falls through to `throw lastError`, which runResearchers catches and
+      // records as a researcher failure (same contract as retry-exhaustion).
+      if (scrapeEnabled && successfulScrapeCount === 0 && nonScrapeGroundingHits === 0 && historicalUrls.length === 0) {
+        lastError = new Error(`Researcher ${id} produced an ungrounded report: scrape tool enabled but zero successful scrapes and no other grounding`);
+        metrics.increment('researcher_ungrounded_total', 1, { mode: 'deep', complexity: String(complexity), round: String(round) });
+        // Do NOT retry an ungrounded report when the run is being torn down (quit/SIGTERM sets
+        // container.isDisposing without necessarily aborting the signal). A retry rebuilds the
+        // session and relaunches a search/scrape burst into a WorkerPool that dispose() is
+        // destroying — the same "Cannot execute a task on destroying pool" storm the catch-block
+        // guard prevents. This branch exits via `continue`, so it needs the guard too.
+        if (signal?.aborted || container?.isDisposing) {
+          logger.debug(`[ResearcherExecutor] Researcher ${id} ungrounded but run aborting/disposing; skipping retries.`);
+          break;
+        }
+        logger.warn(`[ResearcherExecutor] Researcher ${id} attempt ${attempt}/${maxAttempts} ungrounded (scrape enabled, 0 successful scrapes, 0 security/stackexchange grounding hits, no knowledge-store grounding); ${attempt < maxAttempts ? 'retrying' : 'failing'}`);
+        continue;
+      }
+
+      const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+      synthesisService.storeReport(researchId, `${round}.${id}`, responseText);
+
+      observer?.onResearcherComplete?.(id, responseText);
+      return;
+    } catch (err) {
+      const researcherDuration = Date.now() - researcherExecutionStartMs;
+      metrics.observe('researcher_execution_latency_ms', researcherDuration, { mode: 'deep', complexity: String(complexity), round: String(round), status: 'error' });
+      metrics.increment('researcher_errors_total', 1, { mode: 'deep', complexity: String(complexity), round: String(round) });
+      lastError = err;
+      const errMsg = err instanceof Error ? err.message : String(err);
+
+      // Attempt to salvage partial content on timeout or error
+      try {
+        const partialResponse = ensureAssistantResponse(session, id);
+        // Apply the same grounding gate to salvaged partials: a timed-out/errored researcher
+        // with zero successful scrapes, zero non-scrape grounding hits, and no knowledge-store
+        // grounding has nothing real to land, so skip the salvage store and fall through to the
+        // retry/abort handling below.
+        const ungrounded = scrapeEnabled && successfulScrapeCount === 0 && nonScrapeGroundingHits === 0 && historicalUrls.length === 0;
+        if (partialResponse && partialResponse.trim().length > 50 && !ungrounded) {
+          const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+          synthesisService.storeReport(researchId, `${round}.${id}`, partialResponse + '\n\n---\n*WARNING: This report was truncated due to a timeout/error. Content may be incomplete.*');
+          logger.log(`[ResearcherExecutor] Researcher ${id} salvaged partial content (${partialResponse.length} chars) after error: ${errMsg}`);
+          observer?.onResearcherComplete?.(id, partialResponse);
+          return;
+        }
+      } catch (salvageErr) {
+        logger.debug(`[ResearcherExecutor] Researcher ${id} salvage attempt failed:`, salvageErr);
+      }
+      
+      // Skip retries when the run is being torn down: an aborted signal, an explicit
+      // "Aborted" error, or the service container entering disposal (SIGTERM/quit
+      // mid-run, which throws "…during container disposal" from getService). Retrying
+      // during disposal is futile — services are being destroyed — and it relaunches
+      // search bursts into a WorkerPool that dispose() is simultaneously destroying,
+      // producing a storm of "Cannot execute a task on destroying pool" errors.
+      if (signal?.aborted || errMsg === 'Aborted' || errMsg.includes('during container disposal') || container?.isDisposing) {
+        logger.debug(`[ResearcherExecutor] Researcher ${id} aborted or container disposing, skipping retries.`);
+        break; // Break out of the attempt loop
+      }
+
+      if (attempt < maxAttempts) {
+        logger.warn(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} failed: ${errMsg}; will retry`);
+      } else {
+        logger.error(`[ResearcherExecutor] Researcher ${id} failed all ${maxAttempts} attempts: ${errMsg}`);
+        metrics.increment('researcher_retries_exhausted_total', 1, { mode: 'deep', complexity: String(complexity) });
+      }
+    } finally {
+      subscription();
+      await session.abort().catch((err) => {
+        logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id}:`, err);
+      });
+      sessionService?.unregisterSession(researchId, id);
+
+      // Restore the default thinking label now that the researcher is done.
+      // Otherwise "Researcher X" persists for all subsequent agent turns.
+      // Symmetric with where the label is set (researcher.ts): a no-op in the
+      // research TUI, where the label is never applied in the first place.
+      if (ctx.mode !== 'tui' && ctx.hasUI && typeof ctx.ui.setHiddenThinkingLabel === 'function') {
+        ctx.ui.setHiddenThinkingLabel();
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/orchestration/researcher.ts

@@ -3,102 +3,175 @@
  *
  * Responsible for instantiating individual researcher agent sessions. 
  * Each researcher is an autonomous agent equipped with a suite of specialized tools:
- * - Web search via SearXNG
+ * - Web search via DuckDuckGo Lite
  * - Context-aware URL scraping via Playwright
  * - Security vulnerability database queries (NVD, CISA, OSV)
  * - Technical Q&A retrieval from Stack Exchange
  * - Local code search via Ripgrep
+ * - Knowledge store search for historical data
  */
 
-import type { AgentSession, ModelRegistry, SettingsManager, ExtensionContext } from '@mariozechner/pi-coding-agent';
-import { createAgentSession, createReadTool, SessionManager } from '@mariozechner/pi-coding-agent';
-import type { Model } from '@mariozechner/pi-ai';
+import type { AgentSession, ModelRegistry, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { createAgentSession, SessionManager, SettingsManager as SettingsManagerClass } from '@earendil-works/pi-coding-agent';
+import type { Model } from '@earendil-works/pi-ai';
 import { createResearchTools } from '../tools/index.ts';
 import { makeResourceLoader } from '../utils/make-resource-loader.ts';
 import { ToolUsageTracker, createDefaultToolLimits } from '../utils/tool-usage-tracker.ts';
 import type { SystemResearchState } from './deep-research-types.ts';
+import type { Config } from '../config.ts';
+import { logger } from '../logger.ts';
+
+import { resolveResearchModel } from '../core/llm/research-model-resolver.ts';
 
 export interface CreateResearcherSessionOptions {
   cwd: string;
   ctxModel: Model<any> | undefined;
   modelRegistry: ModelRegistry;
-  settingsManager: SettingsManager;
   systemPrompt: string;
-  searxngUrl: string;
   extensionCtx: ExtensionContext;
   // Optional: real closures for global state management
   getGlobalState?: () => SystemResearchState;
   updateGlobalLinks?: (links: string[]) => void;
-  /** Returns tokens consumed by this researcher session so far (for context-aware scrape gating). */
-  getTokensUsed?: () => number;
-  /** Model context window size in tokens. */
-  contextWindowSize?: number;
+  /** Optional researcher ID for per-researcher scrape tracking. */
+  researcherId?: string;
+  /** Callback invoked during search with cumulative link count found so far */
+  onSearchProgress?: (links: number) => void;
+  /** Fires for each individual URL scrape result (per-URL TUI flash). */
+  onUrlScrapeResult?: (url: string, success: boolean) => void;
+  /** List of tool names to disable for this researcher. */
+  excludeTools?: string[];
+  config?: Config;
+}
+
+export interface ResolvedResearcherSession {
+  session: AgentSession;
+  /** The model actually used for this session (after RESEARCH_MODEL resolution). */
+  resolvedModel: Model<any>;
 }
 
-export async function createResearcherSession(options: CreateResearcherSessionOptions): Promise<AgentSession> {
+export async function createResearcherSession(options: CreateResearcherSessionOptions): Promise<ResolvedResearcherSession> {
   const {
     cwd,
     ctxModel,
     modelRegistry,
-    settingsManager,
     systemPrompt,
-    searxngUrl,
     extensionCtx,
     getGlobalState,
     updateGlobalLinks,
-    getTokensUsed,
-    contextWindowSize,
+    researcherId,
+    onSearchProgress,
+    onUrlScrapeResult,
+    excludeTools = [],
+    config,
   } = options;
 
-  // Validate required parameters
-  if (!ctxModel) {
-    throw new Error('No model selected. Please select a model before using the research tool.');
-  }
-
   if (!systemPrompt || typeof systemPrompt !== 'string') {
     throw new Error('Invalid system prompt: must be a non-empty string');
   }
 
-  if (!searxngUrl || typeof searxngUrl !== 'string') {
-    throw new Error('Invalid SearXNG URL: must be a non-empty string');
-  }
+  // Create a mutable reference to the session so the tools can access it
+  // before the createAgentSession call returns.
+  const sessionRef: { session: AgentSession | null } = { session: null };
 
-  // Create tool usage tracker for this researcher
-  const tracker = new ToolUsageTracker(createDefaultToolLimits());
+  // Resolve model using centralized priority logic
+  const modelToUse = resolveResearchModel({
+    modelRegistry,
+    config,
+    hostModel: ctxModel,
+    cwd,
+  });
 
-  // Use provided closures or fallback to safe dummies
-  const globalState = getGlobalState || (() => ({} as any));
-  const globalLinks = updateGlobalLinks || (() => {});
+  logger.info(`[Researcher] Using model for researcher ${researcherId}: ${modelToUse.provider}/${modelToUse.id}`);
 
   try {
+    const tracker = new ToolUsageTracker(createDefaultToolLimits(config));
+
+    // Use provided closures or fallback to safe dummies
+    const globalLinks = updateGlobalLinks || (() => {});
+
+    const customTools = createResearchTools({
+      cwd,
+      ctx: extensionCtx,
+      tracker,
+      getGlobalState,
+      updateGlobalLinks: globalLinks,
+      researcherId,
+      onSearchProgress: onSearchProgress,
+      onUrlScrapeResult: onUrlScrapeResult,
+      getTokensUsed: () => {
+        if (!sessionRef.session) return 0;
+        
+        // Prefer getContextUsage as it accounts for the full context window history
+        if (typeof (sessionRef.session as any).getContextUsage === 'function') {
+          const usage = (sessionRef.session as any).getContextUsage();
+          if (usage && typeof usage.tokens === 'number') return usage.tokens;
+        }
+        
+        // Fallback to cumulative session usage
+        if (typeof (sessionRef.session as any).getUsage === 'function') {
+          const usage = (sessionRef.session as any).getUsage();
+          return (usage.input || 0) + (usage.output || 0);
+        }
+        
+        return 0;
+      },
+      contextWindowSize: modelToUse.contextWindow,
+      config,
+    });
+
+    // Explicit allowlist of custom tools minus dangerous built-ins.
+    const defaultExclude = ['bash', 'write', 'edit', 'repl', 'git', 'terminal'];
+    const mergedExclude = [...new Set([...defaultExclude, ...excludeTools])];
+
+    const tools = customTools.map(t => t.name).filter(name => !mergedExclude.includes(name));
+
+    // Build a researcher-scoped settings manager with provider retries restored to 2.
+    // v0.76.0 changed the SDK default to 0; transient network errors during long researcher
+    // runs would otherwise fail the entire researcher rather than retrying the LLM call.
+    const researcherSettings = SettingsManagerClass.inMemory({ retry: { provider: { maxRetries: 2 } } });
+
     const result = await createAgentSession({
       cwd,
-      tools: [createReadTool(cwd)],
-      customTools: createResearchTools({
-        searxngUrl,
-        ctx: extensionCtx,
-        tracker,
-        getGlobalState: globalState,
-        updateGlobalLinks: globalLinks,
-        getTokensUsed,
-        contextWindowSize,
-      }),
+      customTools,
+      tools, // Explicit allowlist (BUG-1 fix)
       sessionManager: SessionManager.inMemory(), // Each researcher gets its own isolated session
-      settingsManager,
-      model: ctxModel,
+      settingsManager: researcherSettings,
+      model: modelToUse,
       modelRegistry,
       resourceLoader: makeResourceLoader(systemPrompt),
+      // Thinking/reasoning is disabled for researcher agents: they do retrieval and
+      // synthesis from scraped pages, not open-ended reasoning. Keeping it off reduces
+      // latency and token cost for at most a marginal quality gain in this use case.
+      // Honors the system-wide PI_RESEARCH_LLM_THINKING_LEVEL override (default 'off').
+      // pi-coding-agent clamps the level to whatever the chosen model supports.
+      thinkingLevel: config?.LLM_THINKING_LEVEL ?? 'off',
     });
 
+    // Customize the agent thinking label for researchers (e.g. "Researcher 1.1")
+    // so non-TUI surfaces can tell concurrent researchers apart. Skip this in the
+    // research TUI (mode === 'tui'): the panel already shows every researcher, and
+    // the host renders this label as dim/italic thinking text ABOVE the panel —
+    // stray output the panel was meant to replace. Use the researcherId passed by
+    // the caller (not regex on the prompt, since the ID is never templated in).
+    if (extensionCtx.mode !== 'tui' && extensionCtx.hasUI && typeof extensionCtx.ui.setHiddenThinkingLabel === 'function') {
+      extensionCtx.ui.setHiddenThinkingLabel(
+        researcherId ? `Researcher ${researcherId}` : undefined
+      );
+    }
+
+    logger.log(`[Researcher] Created session with model=${modelToUse?.id || 'unknown'}`);
+
     if (!result || !result.session) {
       throw new Error('Session creation returned invalid result');
     }
 
-    return result.session;
+    sessionRef.session = result.session;
+
+    return { session: result.session, resolvedModel: modelToUse };
   } catch (error) {
     const errorMsg = error instanceof Error ? error.message : String(error);
     throw new Error(`Failed to create researcher session: ${errorMsg}`, {
       cause: error,
     });
   }
-}
+}