@lincoln504/pi-research 1.3.12 → 1.4.3

package/src/prompts/system-lead-router.md

@@ -0,0 +1,122 @@
+# Research Lead — Routing
+
+You decide whether this research run continues or ends.
+
+You are given the message in two parts.
+
+**NEW SINCE YOUR LAST DECISION** holds the **full reports** from the researchers that have just finished. This is the evidence your decision turns on — read it. Each report is preceded by the **coverage digest** its own researcher wrote for it: treat that as a *claim*, and check it against the report underneath. A digest saying `Gaps: none` above a thin or hedged report is the single most important thing you can catch, because nobody else will.
+
+**REVIEWED IN EARLIER ROUNDS** holds only the coverage digests of reports you already read in full on a previous round and already judged. They are not repeated in full — you have seen them.
+
+Everything specific to this run — the root query, the current round and round budget, the agenda so far, the queries already executed, any additional user guidance, and the phase guidance for this particular round — is supplied in a **RUN CONTEXT** block at the END of the message you are given, after the reports. Read that block before deciding; the instructions below tell you how to decide, the RUN CONTEXT tells you what you are deciding about.
+
+You never write the report. When you decide the research is complete, a separate synthesis step reads every full report and writes it. Your output is a decision, not prose.
+
+## CRITICAL: Steering Compliance Checkpoint
+- **STRICT STEERING**: If the RUN CONTEXT block carries an "ADDITIONAL USER GUIDANCE" section, you MUST treat every point in it as a **mandatory rule and instruction** for your decisions, next round goals, and queries. Do not ignore them. They are directional requirements.
+- **STEERING SATISFACTION**: Before deciding to FINISH, you MUST explicitly verify that ALL user steering requirements are actually covered by the findings — not merely claimed by a digest. If ANY steering requirement is unaddressed, or only superficially covered, you MUST DELEGATE — do NOT finish. The user's guidance takes priority over round budget or feeling that research is "complete enough."
+
+{{disabled_tools_section}}
+
+---
+
+## Complexity-Aware Decision Thresholds
+
+**Complexity Level**: {{complexity_label}}
+
+{{complexity_guidance}}
+
+The phase guidance for the current round appears in the RUN CONTEXT block; it refines these thresholds for where this run currently sits in its round budget.
+
+---
+
+## Reading the evidence
+
+For **earlier rounds** you have only the digest, and you already judged that work when it arrived. For **new reports** you have the prose; the digest beside it is a claim to verify.
+
+Read a digest as follows:
+
+- **`Covered`** tells you what is established. Treat a specific, concrete `Covered` line as reliable; treat a vague one ("general background on the topic") as weak coverage that may need a follow-up.
+- **`Gaps`** is a researcher telling you directly what it could not reach. A non-"none" `Gaps` line on a topic the root query asks about is the strongest possible signal to delegate.
+- **`Unsubstantiated`** flags claims that were looked for and not grounded. Delegating a targeted follow-up on those is usually higher value than opening a new angle.
+- **`Sources: 0` or a very low count** means that researcher produced little usable material regardless of what its other lines claim. Re-cover that goal.
+- **A digest that says coverage is unknown** was derived mechanically because that researcher emitted no digest of its own. For a new report that costs you nothing — read the report. For an earlier round it means coverage there is unverified, so weigh it accordingly.
+
+**Verify the new reports rather than trusting their digests.** For each new report, read the prose and ask whether it actually establishes what its `Covered` line claims. Specific, sourced prose backs the claim up. Hedged prose, "not found in sources", a handful of thin paragraphs, or a report that never reaches its stated topic does not — in that case the goal is still open however confidently the digest is worded, and you should delegate it again.
+
+Then compare everything covered — earlier digests plus what the new reports actually establish — against the root query and the initial agenda. What the root query asks for and nothing covers is a gap.
+
+---
+
+## Decision Framework
+
+**FINISH if:** Coverage across the new reports and the earlier digests meets the complexity-specific synthesis criteria above. ("Finish" is the decision; the literal value you emit for it is `"action": "synthesize"`.)
+**DELEGATE if:** Coverage meets the complexity-specific delegation criteria above.
+**Note on Guidance**: If the user provides additional guidance mid-research (via Alt+Enter or direct follow-up), those messages will be provided to you. You MUST incorporate them into your next round's delegation goals and queries.
+
+**STAY IN SCOPE (every delegation):**
+- Going deeper on in-scope material is always welcome. Widening to new areas (breadth) is the drift to avoid — only do it when genuinely appropriate and helpful for the topic.
+- A gap is missing depth on what was asked — not a broader topic next to it. Don't add anything the query didn't ask for, even if it came up in the findings.
+- Match the query's scope-bounding constraints exactly — don't broaden them, don't narrow them.
+
+**COMMON MISTAKES TO AVOID:**
+- Do NOT finish early just because you've done "enough" rounds. Finish only when the evidence shows comprehensive coverage across all major topics the query asks about.
+- Do NOT finish with gaps remaining, hoping they can be "filled in later". Complete the research first.
+- Do NOT invent a gap outside the query's scope just to keep going or fill the budget. Finish what was asked; don't add what wasn't.
+- Do NOT write findings, prose, or a report. You have read findings, but writing the report is a separate step's job. A `reason` is one sentence.
+
+Use unique, targeted queries for any new researchers.
+
+**Decision**: Return valid JSON in a code block:
+
+**If the research is complete**:
+```json
+{
+  "action": "synthesize",
+  "reason": "<one sentence naming the coverage that makes this complete>"
+}
+```
+
+**If delegating**:
+```json
+{
+  "action": "delegate",
+  "researchers": [
+    {
+      "id": "<CURRENT_ROUND>.1",
+      "name": "<Researcher Specialty>",
+      "goal": "<Focused gap or new angle to investigate>",
+      "queries": ["<query_1>", "<query_2>", "<query_3>", "..."]
+    }
+  ],
+  "allQueries": ["<flat_list_of_all_queries_from_all_new_researchers>"]
+}
+```
+
+**DELEGATION REQUIREMENTS**:
+- **CRITICAL — Queries are mandatory**: Every researcher MUST have at least one query. Never plan a researcher without queries. Researchers receive ONLY the search results you delegate to them.
+- **Maximize queries**: For EACH researcher, generate the maximum number of targeted, specific queries within the budget. Do not plan fewer than needed — fill the budget. Queries should target primary sources and authoritative evidence.
+- **YouTube discovery**: For roughly one in {{youtube_query_every_n}} queries, append the word `youtube` to the query text (e.g. `"<topic> analysis youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip only when the gap is clearly unsuited to video.
+- **Temporal anchoring**: Anchor every new time-sensitive query to the current month and year shown at the top of this prompt. Use that exact year (and month where relevant); never default to an older year than the one shown there unless the user explicitly asks about the past.
+- **Flexible coverage**: Use up to {{max_team_size}} researchers to cover distinct angles in parallel. Scale based on research gaps — a single well-targeted researcher is often sufficient for focused gaps.
+- **Source diversity**: Encourage researchers to find multiple authoritative sources per topic area to enable comprehensive citations in the final synthesis.
+
+---
+
+## Quality Standards for Delegation
+
+When delegating, ensure:
+- **Query Specificity**: Each new query targets distinct, unexplored territory
+- **No Redundancy**: Do not repeat queries from previous rounds
+- **Specialized Focus**: Each new researcher has a clear, distinct angle
+- **Gap-Driven**: Only delegate when the evidence shows a gap that existing coverage cannot resolve
+- **Progressive Depth**: New queries go deeper, or to a new angle still inside the query's scope — never outside it, and never repeating surface-level coverage
+
+---
+
+## Output Requirements
+
+- **Researcher IDs**: Use Round.Index format — the current round number from the RUN CONTEXT block, then the researcher index. In round 3 that is **3.1**, **3.2**, and so on.
+- **Query Budget**: Use the complexity-specific budget ({{query_budget}} per researcher). Fill each researcher's query budget completely.
+- **Team Size**: Scale researcher count to match the gaps. Use up to {{max_team_size}} researchers when delegating, but a single well-targeted researcher is often sufficient for focused gaps. Don't pad the team when fewer researchers will cover the remaining gaps efficiently.
+- **Format**: ONLY return valid JSON in a code block. Never return report prose.

package/src/prompts/system-lead-synthesizer.md

@@ -0,0 +1,46 @@
+# Research Lead — Synthesis
+
+You write the final report for this research run.
+
+The research is finished. Every researcher report collected during the run is supplied to you in full, followed by a **Global Source List**, followed by a **RUN CONTEXT** block carrying the root query and any additional user guidance. Read the RUN CONTEXT block before writing: the instructions below tell you how to write, it tells you what the report is about.
+
+You do not decide anything and you do not plan further research. Your only output is the report.
+
+## CRITICAL: Steering Compliance
+If the RUN CONTEXT block carries an "ADDITIONAL USER GUIDANCE" section, treat every point in it as a **mandatory rule** governing the report's content, structure, and emphasis. The user's guidance overrides your own judgment about what to include or how to organize.
+
+{{disabled_tools_section}}
+
+---
+
+## Synthesis Protocol
+
+1. **Organization**: Organize the report logically **BY TOPIC**. Do NOT structure it by researcher or round.
+2. **Anonymity**: Do NOT reference "researchers", "agents", "reports", or the research process. Present the findings as a direct, unified knowledge base.
+3. **Master Links List**: A **Global Source List** has been provided to you, after the findings. Use these sequential numbers [1], [2], [3], etc., for all inline citations. The researcher reports provided to you have already been normalized to these global numbers. This list includes all URLs found during live research and any relevant entries from the **Local and Global Knowledge Stores**.
+4. **Exhaustive Synthesis**: Use ALL findings from ALL reports. Include every fact, date, name, and statistic verbatim. Longer is better.
+5. **Strict Grounding**: Every sentence must come from a report. Use [N] inline citations. No prior knowledge.
+6. **CRITICAL — Links at Bottom Only**:
+   - Write all topic sections first with inline citations [1], [2], etc., using the numbers from the **Global Source List**.
+   - Place exactly ONE `CITED LINKS` section at the VERY END of the entire synthesis.
+   - This section must contain the complete master list of all unique URLs exactly as provided in the **Global Source List**.
+   - Do NOT include any links within topic sections or subsections.
+   - Format: `[1] https://url.com [Source: ...] — brief description` on each line.
+
+> **MANDATORY TERMINATION RULE**: Your synthesis is not complete until it ends with `CITED LINKS`. Do NOT close the JSON object or stop generating until this section is written in full. A synthesis without `CITED LINKS` is a failed output.
+
+---
+
+## Output Requirements
+
+- **Synthesis Quality**: Logical topic-based structure in plain prose, maximal detail, NO mention of researchers, NO markdown headings or bullets.
+- **Format**: ONLY return valid JSON in a code block:
+
+```json
+{
+  "action": "synthesize",
+  "content": "<Plain prose report with [N] citations, organized by topic. No markdown headings, bullets, or bold text. Followed by the mandatory CITED LINKS section.>"
+}
+```
+
+{{partial_synthesis_section}}

package/src/sdk.ts

@@ -369,6 +369,16 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
  * Public initialization. Guarantees the SDK is ready for use.
  */
 export async function initResearchSDK(options: ResearchSDKOptions = {}): Promise<void> {
+  // A shutdown may be in flight: isInitialized only flips to false near the END
+  // of _doShutdown (after container disposal), so without this a caller racing a
+  // shutdown would hit the isInitialized branch below, log its "already
+  // initialized" warning, and return believing the SDK is ready — while the
+  // container it would use is mid-teardown or about to be nulled out from under
+  // it. Wait the shutdown out first so this call observes the real post-shutdown
+  // state, mirroring shutdownResearchSDK's symmetric wait on _initPromise.
+  if (_shutdownPromise) {
+    await _shutdownPromise.catch(() => { /* a failed shutdown must not block a fresh init */ });
+  }
   if (isInitialized) {
     logger.warn('[SDK] Research SDK already initialized. Call shutdownResearchSDK() first if you want to re-initialize with new options.');
     return;

package/src/skill-install/skill-installer.ts

@@ -480,7 +480,11 @@ export function uninstallSkill(toolIds?: string[], opts: InstallOptions = {}): U
   }
 
   for (const { tool, path: skillPath } of targets.values()) {
-    if (toolIds && toolIds.length && !toolIds.includes(tool)) {
+    // undefined = every manifest entry; an explicit (including empty) list means
+    // exactly those tools. `toolIds.length` used to gate this, so `[]` was
+    // indistinguishable from `undefined` and silently uninstalled everything —
+    // inconsistent with this file's other list params, where empty means none.
+    if (toolIds !== undefined && !toolIds.includes(tool)) {
       const e = manifest.entries.find(x => x.path === skillPath);
       if (e) keep.push(e);
       continue;

package/src/stackexchange/index.ts

@@ -27,6 +27,7 @@ import {
 } from './output/compact.ts';
 import type { ExtensionContext, AgentToolResult } from '@earendil-works/pi-coding-agent';
 import { logger } from '../logger.ts';
+import { metrics } from '../utils/metrics.ts';
 
 function notify(
   ctx: ExtensionContext,
@@ -86,6 +87,7 @@ export async function stackexchangeCommand(options: {
   try {
     // Check quota before making requests
     if (client.isQuotaExhausted()) {
+      metrics.increment('stackexchange_quota_exhausted_total', 1);
       const quota = client.getQuotaInfo();
       notify(
         ctx,
@@ -103,6 +105,7 @@ export async function stackexchangeCommand(options: {
 
     // Warn if quota is low
     if (client.isQuotaLow()) {
+      metrics.increment('stackexchange_quota_low_total', 1);
       const quota = client.getQuotaInfo();
       notify(
         ctx,

package/src/stackexchange/rest-client.ts

@@ -193,24 +193,19 @@ export class StackExchangeClient {
     });
   }
 
+  // Pure accessor — no metrics side effects. `stackexchangeCommand()` calls this
+  // repeatedly per invocation (pre-request gate checks, success footer, error
+  // footer) purely to read current state for display; incrementing counters here
+  // used to record 2-3x the real number of quota-low/exhausted events per call.
+  // The counters are incremented once, at the single gate check that actually
+  // observes each event (see stackexchange/index.ts).
   getQuotaInfo(): { remaining: number; max: number; requestCount: number; lastBackoff: number | null } {
-    const info = {
+    return {
       remaining: this.quotaRemaining,
       max: this.quotaMax,
       requestCount: this.requestCount,
       lastBackoff: this.lastBackoff,
     };
-    
-    // Track quota exhaustion events
-    if (this.isQuotaExhausted()) {
-      metrics.increment('stackexchange_quota_exhausted_total', 1);
-    }
-    
-    if (this.isQuotaLow()) {
-      metrics.increment('stackexchange_quota_low_total', 1);
-    }
-    
-    return info;
   }
 
   isQuotaExhausted(): boolean {

package/src/tools/research-knowledge-search.ts

@@ -54,6 +54,7 @@ import { loadPrompt } from '../core/llm/prompts.ts';
 import { formatParentContext } from '../orchestration/session-context.ts';
 import { getConfig, type ConfigInterface, type Config } from '../config.ts';
 import { createKnowledgeSearchPanel } from '../tui/knowledge-search-panel.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 // ---------------------------------------------------------------------------
 // Phase 1: Tool Parameters
@@ -439,6 +440,7 @@ export async function runBackgroundExtraction(
   maxTokens: number,
   thinkingLevel: Config['LLM_THINKING_LEVEL'],
   signal?: AbortSignal,
+  sessionId?: string,
 ): Promise<ResearchKnowledgeSynthesisResponse> {
   const promptTemplate = loadPrompt('research-knowledge-search-extractor');
   if (!promptTemplate) {
@@ -479,7 +481,8 @@ export async function runBackgroundExtraction(
         }, buildSafeOptions(model, {
           apiKey: auth.apiKey,
           headers: auth.headers,
-          signal
+          signal,
+          sessionId,
         }, maxTokens, thinkingLevel)),
         llmTimeout,
         'knowledge-search-extraction',
@@ -537,6 +540,7 @@ export async function runBackgroundExtraction(
       context: 'Knowledge search extraction — synthesizing answer from reference documents',
       serviceName: 'ResearchKnowledgeSearch',
       signal,
+      sessionId,
       // Match the budget of the call being repaired so a large synthesis is not re-truncated
       // at repairJsonWithLlm's smaller default (16384). Mirrors the planning-service repairs.
       maxTokens,
@@ -972,6 +976,11 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
           config.SYNTHESIS_MAX_TOKENS,
           config.LLM_THINKING_LEVEL,
           signal,
+          // Cache/session-affinity hint only (keeps repeated calls on the same warmed
+          // replica) — same resolution research-config.ts uses, since this tool has no
+          // researchId of its own to key on. ctx.sessionId is read defensively: it is
+          // not on every host's ExtensionContext shape, hence the `as any`.
+          (ctx as any).sessionId || ctx.sessionManager?.getSessionId(),
         );
 
         const durationMs = Date.now() - startTime;
@@ -983,7 +992,6 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         return buildSteeringResult(result, urls);
       } catch (error) {
         const durationMs = Date.now() - startTime;
-        const msg = error instanceof Error ? error.message : String(error);
 
         // A CANCELLED search is not an empty store. Reporting the miss string here
         // told the calling agent, definitively, that the knowledge store has
@@ -991,7 +999,7 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         // the very work the user just interrupted. Propagate the abort instead;
         // the run is ending either way. (Same misclassification as the search
         // layer's "browser workers may be unavailable" on Ctrl-C.)
-        if (signal?.aborted || (error instanceof Error && error.name === 'AbortError') || /^(aborted|research (aborted|cancelled))$/i.test(msg)) {
+        if (isCancellation(error, signal)) {
           metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'cancelled' });
           metrics.increment('research_knowledge_search_total', 1, { status: 'cancelled' });
           logger.debug('[research-knowledge-search] Cancelled mid-search — propagating rather than reporting an empty store.');

package/src/tools/research-tool-definition.ts

@@ -17,6 +17,7 @@ import type {
 import type { ExtendedExtensionContext } from '../types/extension-context.ts';
 import type { ResearchDepth, CleanupContext } from '../types/index.ts';
 import { Type, type Static } from 'typebox';
+import { Value } from 'typebox/value';
 import { validateConfig, getConfig, type ConfigInterface } from '../config.ts';
 import { tryGetServiceContainerFromCtx, getService } from '../core/service-registry.ts';
 
@@ -28,7 +29,7 @@ import { redactSecrets } from '../utils/log-utils.ts';
 import { exportResearchReport, appendExportMessage } from '../utils/research-export.ts';
 import { validateAndSanitizeQuery } from '../utils/input-validation.ts';
 import { validateInitialLinks, MAX_INITIAL_LINKS, MAX_INITIAL_LINK_CHARS } from '../utils/url-utils.ts';
-import { startResearchSession, endResearchSession, registerSessionAbort, clearSteeringMessages, getPiActivePanels } from '../orchestration/session-state.ts';
+import { startResearchSession, endResearchSession, registerSessionAbort, clearSteeringMessages, getActiveResearchRunCount } from '../orchestration/session-state.ts';
 import { createResearchTuiManager, hideWorkingIndicator } from '../tui/research-tui-manager.ts';
 import { createCleanupFunction } from '../cleanup/research-cleanup.ts';
 import { createResearchObserver, createObserverState, stopObserverWaveAnimation } from '../observers/research-observer-impl.ts';
@@ -118,6 +119,21 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
 
   type ResearchParams = Static<typeof parameters>;
 
+  // Same field shapes as `parameters`, but WITHOUT the initialLinks count/length
+  // bounds — used only for the runtime execute() gate below. validateInitialLinks
+  // already enforces those same two bounds with a specific, friendly message
+  // ("at most N URLs...", "at most N characters..."); checking them again here
+  // would just produce the generic 'invalid_parameters' rejection first and mask
+  // that better message. Structural type-checking (initialLinks must still be an
+  // array of strings) is kept, since validateInitialLinks assumes that shape.
+  const executeShapeCheck = Type.Object({
+    query: Type.String(),
+    depth: Type.Optional(Type.Integer({ minimum: 1, maximum: 3 })),
+    model: Type.Optional(Type.String()),
+    excludeTools: Type.Optional(Type.Array(Type.String())),
+    initialLinks: Type.Optional(Type.Array(Type.String())),
+  });
+
   return {
     name: 'research',
     label: 'Research',
@@ -169,6 +185,17 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
         };
       }
 
+      // Every other tool in this codebase re-validates params against its own
+      // schema before trusting it (the host does not enforce this) — this was the
+      // one exception, relying entirely on incidental downstream checks (a
+      // typeof on query, a warn-gate on excludeTools) for fields that skip both.
+      if (!Value.Check(executeShapeCheck, params)) {
+        return {
+          content: [{ type: 'text', text: 'Error: invalid parameters for research tool.' }],
+          details: { error: 'invalid_parameters' },
+        };
+      }
+
       const { query, depth: rawDepth, model: modelId, excludeTools: paramExcludeTools, initialLinks } = params as ResearchParams;
 
       // Enforce the same bounds the CLI applies to --initial-links: these links are
@@ -227,11 +254,13 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
         }
         // Steering messages are shared per pi-session. Only reset them when THIS is
         // the last active run — otherwise a finishing run wipes a concurrent sibling
-        // run's queued/active steering mid-flight. This run's panel is still
-        // registered here (endResearchSession runs later in cleanup()), so a count
-        // of <= 1 means no other run is active.
+        // run's queued/active steering mid-flight. This run's abort registration is
+        // still in place here (endResearchSession runs later in cleanup()), so a
+        // count of <= 1 means no other run is active. getActiveResearchRunCount
+        // (not getPiActivePanels) because headless runs never register a panel —
+        // a panel-based check here was always a no-op for headless callers.
         try {
-          if (getPiActivePanels(piSessionId).length <= 1) clearSteeringMessages(piSessionId);
+          if (getActiveResearchRunCount(piSessionId) <= 1) clearSteeringMessages(piSessionId);
         } catch (e) { logger.error('[research] Clear steering messages failed:', e); }
         if (detachAbortListener) {
           try { detachAbortListener(); } catch { /* best-effort */ } finally { detachAbortListener = undefined; }
@@ -344,9 +373,11 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
               // module-level piSessions map keyed by the STABLE pi session id, so
               // without this every headless run leaked them for the process
               // lifetime (the TUI branch frees them via createCleanupFunction, the
-              // SDK in its own finally; this branch freed only steering).
+              // SDK in its own finally). Steering is NOT cleared here — teardownUi()
+              // already does that, gated on getActiveResearchRunCount so a finishing
+              // run doesn't wipe a concurrent sibling headless run's steering; an
+              // unconditional clear here bypassed that guard entirely.
               endResearchSession(piSessionId, sessionResearchId);
-              clearSteeringMessages(piSessionId);
             };
             
             // Minimal stub — only stopObserverWaveAnimation touches panelState in the

package/src/tools/scrape.ts

@@ -31,6 +31,7 @@ import { ServiceNames } from '../core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from '../core/service-interfaces.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createScrapeTool(options: {
   ctx: ExtensionContext;
@@ -267,6 +268,11 @@ export function createScrapeTool(options: {
         }, container);
         freshResults = Array.isArray(results) ? results : [];
       } catch (error) {
+          // A cancelled scrape is not a failed scrape — see isCancellation.
+          if (isCancellation(error, signal)) {
+            metrics.increment('tool_scrape_calls_total', 1, { status: 'cancelled' });
+            throw error;
+          }
           const message = error instanceof Error ? error.message : String(error);
           logger.error(`[scrape tool] Scrape failed: ${message}`);
           metrics.increment('tool_scrape_calls_total', 1, { status: 'error' });

package/src/tools/search.ts

@@ -13,6 +13,7 @@ import type { SystemResearchState } from '../orchestration/deep-research-types.t
 import { logger } from '../logger.ts';
 import { type Config, getConfig } from '../config.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 import { tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
 
 export function createSearchTool(options: {
@@ -134,6 +135,12 @@ export function createSearchTool(options: {
         };
       } catch (error) {
         const elapsed = Date.now() - startTime;
+        // A cancelled search is not a failed search — see isCancellation.
+        if (isCancellation(error, signal)) {
+          metrics.observe('tool_search_duration_ms', elapsed, { status: 'cancelled' });
+          metrics.increment('tool_search_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         metrics.observe('tool_search_duration_ms', elapsed, { status: 'error' });
         metrics.increment('tool_search_calls_total', 1, { status: 'error' });
         const msg = error instanceof Error ? error.message : String(error);

package/src/tools/security.ts

@@ -11,6 +11,7 @@ import { searchSecurityDatabases } from '../security/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 import type { SecuritySearchParams } from '../security/types.ts';
 
 const MAX_DESCRIPTION_CHARS = 300;
@@ -78,18 +79,17 @@ export function createSecuritySearchTool(options: {
       _extensionCtx,
     ): Promise<AgentToolResult<unknown>> {
       const startTime = Date.now();
-      metrics.increment('tool_security_search_calls_total', 1);
 
-      // Record call in tracker - returns false if limit reached
-      const allowed = options.tracker.recordCall('security_search');
-      if (!allowed) {
-          metrics.increment('tool_security_search_calls_total', 1, { status: 'rate_limited' });
-          return {
-            content: [{ type: 'text', text: options.tracker.getLimitMessage('security_search') }],
-            details: { blocked: true, reason: 'limit_reached' },
-          };
-      }
+      // Every exit path below increments `tool_security_search_calls_total` itself
+      // (labeled with its own status) — there is no separate unconditional increment
+      // here. There used to be one, which double-counted every single call: sumCounter
+      // matches both the bare key and every labeled variant of the same base name, so
+      // the Session Metrics / Research Summary view reported exactly 2x the real count.
 
+      // Validate BEFORE spending the budget: a rejected call did no work, and charging
+      // it against the shared MAX_GATHERING_CALLS allowance turns a malformed call into
+      // a permanently lost one. See youtube-transcript for the sharpest case (a single
+      // allowed call, forfeited by a schema violation).
       if (!Value.Check(SecuritySearchParamsSchema, params)) {
           metrics.increment('tool_security_search_calls_total', 1, { status: 'invalid_params' });
           return {
@@ -150,6 +150,19 @@ export function createSecuritySearchTool(options: {
       }
       const maxResults = p.maxResults ?? 20;
 
+      // Record call in tracker - returns false if limit reached. Deliberately AFTER
+      // every semantic-validation reject above (terms/databases/severity), same
+      // reasoning as the schema check: a rejected call did no work and must not
+      // permanently consume one of the researcher's shared MAX_GATHERING_CALLS slots.
+      const allowed = options.tracker.recordCall('security_search');
+      if (!allowed) {
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'rate_limited' });
+          return {
+            content: [{ type: 'text', text: options.tracker.getLimitMessage('security_search') }],
+            details: { blocked: true, reason: 'limit_reached' },
+          };
+      }
+
       metrics.increment('tool_security_search_terms_total', terms.length);
       metrics.increment('tool_security_search_databases_total', databases.length);
 
@@ -167,6 +180,14 @@ export function createSecuritySearchTool(options: {
         results = await searchSecurityDatabases(searchParams, signal);
       } catch (error) {
         const duration = Date.now() - startTime;
+        // A cancelled search is not a database outage — see isCancellation. The
+        // "temporary issue - try again later" text below invites exactly the retry
+        // the user just interrupted.
+        if (isCancellation(error, signal)) {
+          metrics.observe('tool_security_search_duration_ms', duration, { status: 'cancelled' });
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         metrics.observe('tool_security_search_duration_ms', duration, { status: 'error' });
         metrics.increment('tool_security_search_calls_total', 1, { status: 'error' });
         const errorMsg = error instanceof Error ? error.message : String(error);

package/src/tools/stackexchange.ts

@@ -10,6 +10,7 @@ import { Value } from 'typebox/value';
 import { stackexchangeCommand } from '../stackexchange/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createStackexchangeTool(options: {
   ctx: ExtensionContext;
@@ -74,6 +75,15 @@ export function createStackexchangeTool(options: {
       _onUpdate,
       extensionCtx,
     ): Promise<AgentToolResult<unknown>> {
+      // Validate BEFORE spending the budget — see security.ts. A rejected call did no
+      // work and must not consume one of MAX_GATHERING_CALLS.
+      if (!Value.Check(StackExchangeParamsSchema, params)) {
+          return {
+            content: [{ type: 'text', text: 'Invalid parameters for stackexchange tool.' }],
+            details: { error: 'invalid_parameters' },
+          };
+      }
+
       // Record call in tracker - returns false if limit reached
       const allowed = tracker.recordCall('stackexchange');
       if (!allowed) {
@@ -83,13 +93,6 @@ export function createStackexchangeTool(options: {
           };
       }
 
-      if (!Value.Check(StackExchangeParamsSchema, params)) {
-          return {
-            content: [{ type: 'text', text: 'Invalid parameters for stackexchange tool.' }],
-            details: { error: 'invalid_parameters' },
-          };
-      }
-
       const p = params as StackExchangeParams;
       const command = p.command;
 
@@ -105,6 +108,9 @@ export function createStackexchangeTool(options: {
           signal,
         });
       } catch (error) {
+        // A cancelled query was never rate-limited — see isCancellation. Naming a
+        // quota the run never hit is a cause the agent can carry into its report.
+        if (isCancellation(error, signal)) throw error;
         const errorMsg = error instanceof Error ? error.message : String(error);
         return {
           content: [

package/src/tools/youtube-transcript.ts

@@ -24,6 +24,7 @@ import { cacheScrapedContent, registerScrapedLinks, registerTranscribedLinks, re
 import { type Config, getConfig } from '../config.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createYoutubeTranscriptTool(options: {
   ctx: ExtensionContext;
@@ -75,18 +76,12 @@ export function createYoutubeTranscriptTool(options: {
       _onUpdate: AgentToolUpdateCallback<unknown>,
       extensionCtx: ExtensionContext,
     ): Promise<AgentToolResult<unknown>> {
-      // Rate-limit enforcement (one call per researcher).
-      if (tracker) {
-        const allowed = tracker.recordCall('youtube_transcript');
-        if (!allowed) {
-          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'rate_limited' });
-          return {
-            content: [{ type: 'text', text: tracker.getLimitMessage('youtube_transcript') }],
-            details: { blocked: true, reason: 'limit_reached' },
-          };
-        }
-      }
-
+      // Validate BEFORE spending the budget. Charging a rejected call is not a rate
+      // limit, it is a forfeit: this tool's schema caps `urls` at maxVideos while the
+      // per-researcher allowance is a single call, so a researcher passing one URL too
+      // many got a validation error AND lost its only call — and the retry was then told
+      // "You have already used your one youtube_transcript call", which is false. The
+      // round loses transcripts entirely. grep and search already validate first.
       if (!Value.Check(YoutubeParamsSchema, params)) {
         metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'invalid_params' });
         return {
@@ -105,6 +100,19 @@ export function createYoutubeTranscriptTool(options: {
         };
       }
 
+      // Rate-limit enforcement (one call per researcher), now that the call is one that
+      // would actually do work.
+      if (tracker) {
+        const allowed = tracker.recordCall('youtube_transcript');
+        if (!allowed) {
+          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'rate_limited' });
+          return {
+            content: [{ type: 'text', text: tracker.getLimitMessage('youtube_transcript') }],
+            details: { blocked: true, reason: 'limit_reached' },
+          };
+        }
+      }
+
       // Resolve config against the live cwd for timeout/lang. The video cap stays
       // `maxVideos` (the factory value the schema's maxItems was built from) so the
       // schema gate and the command-level cap can never disagree. The PoToken
@@ -151,6 +159,12 @@ export function createYoutubeTranscriptTool(options: {
 
         return result;
       } catch (error) {
+        // A cancelled batch is not bot-protection — see isCancellation. "Continue
+        // with the rest of your research" is the opposite of what a Ctrl-C means.
+        if (isCancellation(error, signal)) {
+          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         const errorMsg = error instanceof Error ? error.message : String(error);
         logger.error(`[youtube_transcript tool] Failed: ${errorMsg}`);
         metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'error' });