@rigour-labs/mcp 5.3.3 → 5.5.0

package/dist/advertised-tools.d.ts

@@ -0,0 +1,722 @@
+/** Context, quality, and cost telemetry tools every agent should see first. */
+export declare const ESSENTIAL_CONTEXT_TOOLS: readonly ["rigour_recall", "rigour_index", "rigour_context_scope", "rigour_check_pattern", "rigour_check", "rigour_remember", "rigour_explain", "rigour_get_fix_packet", "rigour_review", "rigour_security_audit", "rigour_forget", "rigour_context_stats", "rigour_task_cost", "rigour_cache_stats", "rigour_context_explain"];
+/** Multi-agent governance, hooks, and execution tools with dispatch handlers. */
+export declare const GOVERNANCE_TOOLS: readonly ["rigour_agent_register", "rigour_agent_deregister", "rigour_checkpoint", "rigour_handoff", "rigour_handoff_accept", "rigour_hooks_check", "rigour_hooks_init", "rigour_run", "rigour_run_supervised"];
+export declare const ADVERTISED_TOOLS: Set<string>;
+export declare function getAdvertisedToolDefinitions(): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            files: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            deep: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            pro: {
+                type: string;
+                description: string;
+            };
+            apiKey: {
+                type: string;
+                description: string;
+            };
+            provider: {
+                type: string;
+                description: string;
+            };
+            apiBaseUrl: {
+                type: string;
+                description: string;
+            };
+            modelName: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            deep_default_mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            key: {
+                type: string;
+                description: string;
+            };
+            value: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            key: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                description: string;
+            };
+            intent: {
+                type: string;
+                description: string;
+            };
+            file: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            silent: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            maxRetries: {
+                type: string;
+                description: string;
+            };
+            dryRun: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            agentId: {
+                type: string;
+                description: string;
+            };
+            taskScope: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            progressPct: {
+                type: string;
+                description: string;
+            };
+            filesChanged: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            summary: {
+                type: string;
+                description: string;
+            };
+            qualityScore: {
+                type: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            fromAgentId: {
+                type: string;
+                description: string;
+            };
+            toAgentId: {
+                type: string;
+                description: string;
+            };
+            taskDescription: {
+                type: string;
+                description: string;
+            };
+            filesInScope: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            agentId: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            handoffId: {
+                type: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            files: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            timeout: {
+                type: string;
+                description: string;
+            };
+            text: {
+                type: string;
+                description: string;
+            };
+            agent: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tool: {
+                type: string;
+                description: string;
+            };
+            force: {
+                type: string;
+                description: string;
+            };
+            dryRun: {
+                type: string;
+                description: string;
+            };
+            dlp: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            pro: {
+                type: string;
+                description: string;
+            };
+            apiKey: {
+                type: string;
+                description: string;
+            };
+            provider: {
+                type: string;
+                description: string;
+            };
+            apiBaseUrl: {
+                type: string;
+                description: string;
+            };
+            modelName: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            limit: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            repository: {
+                type: string;
+                description: string;
+            };
+            branch: {
+                type: string;
+                description: string;
+            };
+            diff: {
+                type: string;
+                description: string;
+            };
+            files: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            target: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            semantic: {
+                type: string;
+                description: string;
+            };
+            force: {
+                type: string;
+                description: string;
+            };
+            output: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+})[];

package/dist/advertised-tools.js

@@ -0,0 +1,46 @@
+/**
+ * MCP tools advertised to clients via ListTools.
+ *
+ * Essential context/quality tools stay visible for day-to-day agent work.
+ * Governance tools are included so Cursor and other MCP clients can discover
+ * multi-agent registration, checkpoints, handoffs, hooks, and supervised runs
+ * without hunting for undocumented callable tools.
+ */
+import { TOOL_DEFINITIONS } from './tools/definitions.js';
+/** Context, quality, and cost telemetry tools every agent should see first. */
+export const ESSENTIAL_CONTEXT_TOOLS = [
+    'rigour_recall',
+    'rigour_index',
+    'rigour_context_scope',
+    'rigour_check_pattern',
+    'rigour_check',
+    'rigour_remember',
+    'rigour_explain',
+    'rigour_get_fix_packet',
+    'rigour_review',
+    'rigour_security_audit',
+    'rigour_forget',
+    'rigour_context_stats',
+    'rigour_task_cost',
+    'rigour_cache_stats',
+    'rigour_context_explain',
+];
+/** Multi-agent governance, hooks, and execution tools with dispatch handlers. */
+export const GOVERNANCE_TOOLS = [
+    'rigour_agent_register',
+    'rigour_agent_deregister',
+    'rigour_checkpoint',
+    'rigour_handoff',
+    'rigour_handoff_accept',
+    'rigour_hooks_check',
+    'rigour_hooks_init',
+    'rigour_run',
+    'rigour_run_supervised',
+];
+export const ADVERTISED_TOOLS = new Set([
+    ...ESSENTIAL_CONTEXT_TOOLS,
+    ...GOVERNANCE_TOOLS,
+]);
+export function getAdvertisedToolDefinitions() {
+    return TOOL_DEFINITIONS.filter(t => ADVERTISED_TOOLS.has(t.name));
+}

package/dist/index.js

@@ -18,8 +18,8 @@ import { bindServer } from './utils/notifications.js';
 import { getMcpVersion } from './utils/package-version.js';
 // Dashboard (MCP App)
 import { DASHBOARD_URI, getDashboardHtml, pushTimelineEntry, updateScore } from './dashboard/index.js';
-// Tool definitions
-import { TOOL_DEFINITIONS } from './tools/definitions.js';
+// Tool definitions & advertised registry
+import { getAdvertisedToolDefinitions } from './advertised-tools.js';
 // Tool handlers
 import { handleCheck, handleExplain, handleStatus, handleGetFixPacket, handleListGates, handleGetConfig } from './tools/quality-handlers.js';
 import { handleRemember, handleRecall, handleForget } from './tools/memory-handlers.js';
@@ -34,32 +34,12 @@ import { handleContextStats, handleTaskCost, handleCacheStats, handleContextExpl
 import { handleIndex } from './tools/index-handlers.js';
 import { recordContextEvent, estimateTokenCount } from '@rigour-labs/core';
 // ─── Server Setup ─────────────────────────────────────────────────
-const server = new Server({ name: "rigour-mcp", version: getMcpVersion('5.3.2') }, { capabilities: { tools: {}, prompts: {}, logging: {}, resources: {} } });
+const server = new Server({ name: "rigour-mcp", version: getMcpVersion('5.5.0') }, { capabilities: { tools: {}, prompts: {}, logging: {}, resources: {} } });
 // Bind server for logging notifications from handlers
 bindServer(server);
 // ─── Tool Listing ─────────────────────────────────────────────────
-// Only expose essential tools by default to improve agent tool selection.
-// Research shows agents degrade at 30+ tools (wrong picks, hallucinated args).
-// Power-user tools are still callable — they just aren't advertised in the tool list.
-const ESSENTIAL_TOOLS = new Set([
-    'rigour_recall', // Load project memory (START of every task)
-    'rigour_index', // Build/refresh pattern index (if stale)
-    'rigour_context_scope', // Scoped file retrieval BEFORE reading files
-    'rigour_check_pattern', // Check if code exists (BEFORE creating new code)
-    'rigour_check', // Run quality gates (BEFORE declaring done)
-    'rigour_remember', // Store conventions/decisions
-    'rigour_explain', // Explain gate failures
-    'rigour_get_fix_packet', // Get structured fix instructions on FAIL
-    'rigour_review', // Review diffs
-    'rigour_security_audit', // CVE check
-    'rigour_forget', // Remove stored memory
-    'rigour_context_stats', // Context retrieval efficiency & avoided tokens
-    'rigour_task_cost', // Verified vs estimated avoided costs
-    'rigour_cache_stats', // 4-layer cache statistics
-    'rigour_context_explain', // Explain context inclusion/exclusion audit
-]);
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: TOOL_DEFINITIONS.filter(t => ESSENTIAL_TOOLS.has(t.name)),
+    tools: getAdvertisedToolDefinitions(),
 }));
 // ─── Resource Listing (MCP App Dashboard) ────────────────────────
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
@@ -219,8 +199,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 break;
             }
             case "rigour_context_scope": {
-                const { query, limit } = args;
-                result = await handleContextScope(cwd, query, limit);
+                const { query, limit, taskId, agentId } = args;
+                result = await handleContextScope(cwd, query, limit, taskId, agentId);
                 break;
             }
             default:
@@ -231,15 +211,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const telemetry = result?._telemetry;
             const resultText = Array.isArray(result?.content) ? result.content.map((c) => c.text || '').join('\n') : '';
             const returnedTokens = telemetry?.returnedTokens ?? estimateTokenCount(resultText);
-            await recordContextEvent({
-                taskId: args?.taskId || args?.task_id,
-                agentId: args?.agentId || args?.agent_id,
-                toolName: name,
-                cacheStatus: telemetry?.cacheStatus ?? 'none',
-                candidateTokens: telemetry?.candidateTokens ?? returnedTokens,
-                returnedTokens,
-                deduplicatedTokens: telemetry?.deduplicatedTokens ?? 0,
-            }, cwd);
+            if (!telemetry?.skipRecording) {
+                await recordContextEvent({
+                    taskId: telemetry?.taskId
+                        || args?.taskId
+                        || args?.task_id,
+                    agentId: telemetry?.agentId
+                        || args?.agentId
+                        || args?.agent_id,
+                    toolName: name,
+                    queryHash: telemetry?.queryHash,
+                    cacheStatus: telemetry?.cacheStatus ?? 'none',
+                    candidateTokens: telemetry?.candidateTokens ?? returnedTokens,
+                    returnedTokens,
+                    deduplicatedTokens: telemetry?.deduplicatedTokens ?? 0,
+                }, cwd);
+            }
         }
         catch {
             // non-blocking context telemetry logging

package/dist/tools/context-handlers.d.ts

@@ -13,4 +13,4 @@ export declare function handleContextStats(cwd: string, taskId?: string): Promis
 export declare function handleTaskCost(cwd: string, taskId?: string): Promise<ToolResult>;
 export declare function handleCacheStats(cwd: string): Promise<ToolResult>;
 export declare function handleContextExplain(cwd: string, target: string, taskId?: string): Promise<ToolResult>;
-export declare function handleContextScope(cwd: string, query: string, limit?: number): Promise<ToolResult>;
+export declare function handleContextScope(cwd: string, query: string, limit?: number, taskId?: string, agentId?: string): Promise<ToolResult>;

package/dist/tools/context-handlers.js

@@ -10,7 +10,8 @@
  */
 import fs from 'fs-extra';
 import path from 'path';
-import { getTaskContextStats, getTaskCostStats, getCacheStats, explainContext, getSemanticQueryCache, setSemanticQueryCache, estimateTokenCount, } from '@rigour-labs/core';
+import { createHash } from 'crypto';
+import { getTaskContextStats, getTaskCostStats, getCacheStats, explainContext, getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, filterExistingEditScope, estimateTokenCount, } from '@rigour-labs/core';
 import { loadPatternIndex, getDefaultIndexPath, generateEmbedding, semanticSearch, } from '@rigour-labs/core/pattern-index';
 import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
 import { appendContextFooter } from '../utils/context-footer.js';
@@ -94,6 +95,20 @@ export async function handleContextExplain(cwd, target, taskId) {
         };
     }
 }
+function hashScopeQuery(query) {
+    return createHash('sha256').update(query.trim().toLowerCase()).digest('hex').slice(0, 16);
+}
+function scopeTelemetryMeta(opts) {
+    return buildTelemetryMeta({
+        candidateText: opts.candidateText,
+        returnedText: opts.returnedText,
+        cacheStatus: opts.cacheStatus,
+        deduplicatedTokens: opts.deduplicatedTokens,
+        taskId: opts.taskId,
+        agentId: opts.agentId,
+        queryHash: hashScopeQuery(opts.query),
+    });
+}
 function textMatchPatterns(query, patterns, limit) {
     const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
     const scored = patterns.map(p => {
@@ -107,23 +122,88 @@ function textMatchPatterns(query, patterns, limit) {
         .slice(0, limit)
         .map(s => s.pattern);
 }
-export async function handleContextScope(cwd, query, limit = 10) {
+async function serveCachedScope(cached, opts) {
+    const originalScope = cached.editScope || [];
+    const { valid, missing } = await filterExistingEditScope(originalScope, opts.cwd);
+    // Quality guard: require majority of scoped files still present, else recompute.
+    if (originalScope.length > 0) {
+        const retention = valid.length / originalScope.length;
+        if (valid.length === 0 || retention < 0.5) {
+            return null;
+        }
+    }
+    const validSet = new Set(valid);
+    const validationScope = (cached.validationScope || []).filter((item) => {
+        // Keep entries that don't look like file paths, or whose path still exists.
+        const maybePath = item.replace(/^review\s+/i, '').trim();
+        if (!maybePath.includes('/') && !maybePath.endsWith('.ts') && !maybePath.endsWith('.tsx')) {
+            return true;
+        }
+        return validSet.has(maybePath) || valid.some((f) => item.includes(f));
+    });
+    const evidence = (cached.evidence || []).filter((line) => {
+        if (missing.length === 0)
+            return true;
+        return !missing.some((m) => line.includes(m));
+    });
+    const payload = {
+        ...cached,
+        editScope: valid,
+        validationScope,
+        evidence,
+        staleFilesDropped: missing,
+        cacheNote: opts.note,
+    };
+    const cachedText = JSON.stringify(payload, null, 2);
+    const telemetry = scopeTelemetryMeta({
+        candidateText: opts.fullIndexCandidate,
+        returnedText: cachedText,
+        cacheStatus: opts.cacheStatus,
+        query: opts.query,
+        taskId: opts.taskId,
+        agentId: opts.agentId,
+    });
+    const label = opts.cacheStatus === 'partial-hit'
+        ? 'CONTEXT SCOPE (partial cache)'
+        : 'CONTEXT SCOPE (cached)';
+    const text = `${label}\n\n${cachedText}`;
+    return {
+        content: [{ type: 'text', text: appendContextFooter(text, telemetry, 'rigour_check_pattern before creating code') }],
+        _telemetry: telemetry,
+    };
+}
+export async function handleContextScope(cwd, query, limit = 10, taskId, agentId) {
     const commitSha = await getWorkspaceCommitSha(cwd);
     const indexPath = getDefaultIndexPath(cwd);
     const fullIndexCandidate = `Full repository scan for: ${query}`;
     const cached = await getSemanticQueryCache(query, commitSha, cwd);
     if (cached) {
-        const cachedText = JSON.stringify(cached, null, 2);
-        const telemetry = buildTelemetryMeta({
-            candidateText: fullIndexCandidate,
-            returnedText: cachedText,
-            cacheStatus: 'semantic-hit',
+        const served = await serveCachedScope(cached, {
+            cwd,
+            query,
+            fullIndexCandidate,
+            // Exact query+commit key hit — content-addressed semantic layer.
+            cacheStatus: 'exact-hit',
+            taskId,
+            agentId,
         });
-        const text = `CONTEXT SCOPE (cached)\n\n${cachedText}`;
-        return {
-            content: [{ type: 'text', text: appendContextFooter(text, telemetry, 'rigour_check_pattern before creating code') }],
-            _telemetry: telemetry,
-        };
+        if (served)
+            return served;
+    }
+    // Quality-safe power-up: reuse highly overlapping queries at the same commit only.
+    const related = await findRelatedSemanticQueryCache(query, commitSha, cwd);
+    if (related) {
+        const served = await serveCachedScope(related.entry, {
+            cwd,
+            query,
+            fullIndexCandidate,
+            cacheStatus: 'partial-hit',
+            taskId,
+            agentId,
+            note: `Reused related query at same commit (overlap ${(related.overlap * 100).toFixed(0)}%): "${related.sourceQuery}"`,
+        });
+        if (served)
+            return served;
     }
     const index = await loadPatternIndex(indexPath);
     if (!index) {
@@ -131,10 +211,13 @@ export async function handleContextScope(cwd, query, limit = 10) {
             + 'Without an index, agents tend to read entire directories — wasting tokens.';
         return {
             content: [{ type: 'text', text }],
-            _telemetry: buildTelemetryMeta({
+            _telemetry: scopeTelemetryMeta({
                 candidateText: fullIndexCandidate,
                 returnedText: text,
                 cacheStatus: 'miss',
+                query,
+                taskId,
+                agentId,
             }),
         };
     }
@@ -144,12 +227,16 @@ export async function handleContextScope(cwd, query, limit = 10) {
         try {
             const queryVector = await generateEmbedding(query);
             const similarities = semanticSearch(queryVector, index.patterns);
+            // Slightly stricter threshold — quality over vanity hit-rate; partial cache covers near-queries.
             matched = index.patterns
                 .map((p, i) => ({ pattern: p, similarity: similarities[i] ?? 0 }))
-                .filter(r => r.similarity > 0.3)
+                .filter(r => r.similarity > 0.4)
                 .sort((a, b) => b.similarity - a.similarity)
                 .slice(0, limit)
                 .map(r => r.pattern);
+            if (matched.length === 0) {
+                matched = textMatchPatterns(query, index.patterns, limit);
+            }
         }
         catch {
             matched = textMatchPatterns(query, index.patterns, limit);
@@ -201,11 +288,14 @@ export async function handleContextScope(cwd, query, limit = 10) {
         confidence: matched.length > 0 ? 0.85 : 0.3,
     }, cwd);
     const resultText = JSON.stringify(scopePayload, null, 2);
-    const telemetry = buildTelemetryMeta({
+    const telemetry = scopeTelemetryMeta({
         candidateText: fullIndexCandidate,
         returnedText: resultText,
         cacheStatus: 'miss',
         deduplicatedTokens: scopePayload.estimatedTokensSaved,
+        query,
+        taskId,
+        agentId,
     });
     return {
         content: [{

package/dist/tools/definitions.d.ts

@@ -709,6 +709,14 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
             cwd: {
                 type: "string";
                 description: string;

package/dist/tools/definitions.js

@@ -635,6 +635,8 @@ export const TOOL_DEFINITIONS = [
                 ...cwdParam(),
                 query: { type: "string", description: "Natural-language description of what you need to work on (e.g. 'add priority field to task service')." },
                 limit: { type: "number", description: "Maximum number of pattern matches to return (default: 10)." },
+                taskId: { type: "string", description: "Optional task ID for context telemetry attribution." },
+                agentId: { type: "string", description: "Optional agent ID for context telemetry attribution." },
             },
             required: ["cwd", "query"],
         },

package/dist/utils/context-telemetry.d.ts

@@ -5,6 +5,10 @@ export type TelemetryMeta = {
     cacheStatus: CacheStatus;
     deduplicatedTokens?: number;
     isEstimated?: boolean;
+    taskId?: string;
+    agentId?: string;
+    queryHash?: string;
+    skipRecording?: boolean;
 };
 export type ToolResult = {
     content: {
@@ -22,6 +26,10 @@ export declare function buildTelemetryMeta(opts: {
     returnedText: string;
     cacheStatus: CacheStatus;
     deduplicatedTokens?: number;
+    taskId?: string;
+    agentId?: string;
+    queryHash?: string;
+    skipRecording?: boolean;
 }): TelemetryMeta;
 /** Resolve a short commit/ref fingerprint for cache keys. */
 export declare function getWorkspaceCommitSha(cwd: string): Promise<string>;

package/dist/utils/context-telemetry.js

@@ -11,6 +11,10 @@ export function buildTelemetryMeta(opts) {
         cacheStatus: opts.cacheStatus,
         deduplicatedTokens: opts.deduplicatedTokens ?? 0,
         isEstimated: true,
+        taskId: opts.taskId,
+        agentId: opts.agentId,
+        queryHash: opts.queryHash,
+        skipRecording: opts.skipRecording,
     };
 }
 /** Resolve a short commit/ref fingerprint for cache keys. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/mcp",
-  "version": "5.3.3",
+  "version": "5.5.0",
   "description": "MCP server + live dashboard for AI code governance — OWASP LLM Top 10 (10/10), real-time MCP App UI, 25+ security patterns, Bayesian learning Brain, hallucinated import detection, multi-agent governance. Works with Claude, Cursor, VS Code, ChatGPT, Goose, Windsurf. Industry presets for HIPAA, SOC2, FedRAMP.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -62,7 +62,7 @@
     "execa": "^8.0.1",
     "fs-extra": "^11.2.0",
     "yaml": "^2.8.2",
-    "@rigour-labs/core": "5.3.3"
+    "@rigour-labs/core": "5.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",