@rigour-labs/mcp 5.2.9 → 5.3.0

package/dist/tools/definitions.d.ts

@@ -316,6 +316,14 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
             cwd: {
                 type: "string";
                 description: string;
@@ -603,4 +611,116 @@ export declare const TOOL_DEFINITIONS: ({
         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;
+            };
+            cwd: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
 })[];

package/dist/tools/definitions.js

@@ -192,7 +192,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "rigour_recall",
-        description: "Load project memory and stored conventions. CALL THIS at the start of every coding task to restore team decisions, naming conventions, and architectural preferences stored from previous sessions.",
+        description: "Load project memory and stored conventions. CALL THIS at the START of every coding task (before reading files) to restore team decisions, naming conventions, and architectural preferences. Returns index health status and uses semantic cache on repeat calls — second recall with the same key is served from cache.",
         inputSchema: {
             type: "object",
             properties: {
@@ -332,15 +332,17 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "rigour_checkpoint",
-        description: "Record a quality checkpoint during long-running agent execution. Use periodically (every 15-30 min) to enable drift detection and quality monitoring. Essential for GPT-5.3 coworking mode.",
+        description: "Record a quality checkpoint during long-running agent execution. Use periodically (every 15-30 min) to enable drift detection, quality monitoring, and compact subagent handoffs. Triggers incremental pattern index refresh when filesChanged is provided. Essential for GPT-5.3 coworking mode — call BEFORE rigour_handoff to compress context under 2K tokens.",
         inputSchema: {
             type: "object",
             properties: {
                 ...cwdParam(),
                 progressPct: { type: "number", description: "Estimated progress percentage (0-100)." },
-                filesChanged: { type: "array", items: { type: "string" }, description: "List of files modified since last checkpoint." },
+                filesChanged: { type: "array", items: { type: "string" }, description: "List of files modified since last checkpoint. Triggers incremental index refresh." },
                 summary: { type: "string", description: "Brief description of work done since last checkpoint." },
                 qualityScore: { type: "number", description: "Self-assessed quality score (0-100). Be honest - artificially high scores trigger drift detection." },
+                agentId: { type: "string", description: "Optional agent ID for checkpoint packet binding." },
+                taskId: { type: "string", description: "Optional task ID for checkpoint metrics." },
             },
             required: ["cwd", "progressPct", "summary", "qualityScore"],
         },
@@ -525,4 +527,123 @@ export const TOOL_DEFINITIONS = [
             openWorldHint: false,
         },
     },
+    // ─── Context Telemetry & Cost Efficiency ───────────────
+    {
+        name: "rigour_context_stats",
+        description: "Returns context retrieval efficiency, candidate tokens vs returned tokens, potential avoided tokens, cache hit rate, and repeated reads prevented.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...cwdParam(),
+                taskId: { type: "string", description: "Optional Task ID (e.g. 'CTP-142') to filter statistics." },
+            },
+            required: ["cwd"],
+        },
+        annotations: {
+            title: "Context Stats",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "rigour_task_cost",
+        description: "Returns both verified actual model usage/cost (from Cursor Admin API or imported CSV) and Rigour estimated avoided context/cost USD.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...cwdParam(),
+                taskId: { type: "string", description: "Optional Task ID (e.g. 'CTP-142') to filter cost stats." },
+            },
+            required: ["cwd"],
+        },
+        annotations: {
+            title: "Task Cost Breakdown",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "rigour_cache_stats",
+        description: "Returns detailed performance stats across all 4 cache layers (exact hits, semantic hits, partial hits, misses, hit rate, tokens served from cache).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...cwdParam(),
+            },
+            required: ["cwd"],
+        },
+        annotations: {
+            title: "Cache Efficiency Stats",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "rigour_context_explain",
+        description: "Audits why specific files/services were included or excluded, cache hit/miss status, invalidation reasons, and prior agent requests.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...cwdParam(),
+                target: { type: "string", description: "File path, service name, or query term to explain." },
+                taskId: { type: "string", description: "Optional Task ID to restrict audit trace." },
+            },
+            required: ["cwd", "target"],
+        },
+        annotations: {
+            title: "Context Explainability Audit",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    // ─── Pattern Index & Scoped Context ──────────────────
+    {
+        name: "rigour_index",
+        description: "Build or update the Rigour pattern index (.rigour/patterns.json). CALL THIS when the index is missing or stale — before rigour_context_scope or rigour_check_pattern. One AST pass extracts functions, classes, routes, and signatures for reuse. Use semantic=true for embedding-based search.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...cwdParam(),
+                semantic: { type: "boolean", description: "Generate semantic embeddings for better matching (requires Transformers.js). Default: false." },
+                force: { type: "boolean", description: "Force a full rebuild instead of incremental update. Default: false." },
+                output: { type: "string", description: "Custom path for the index file." },
+            },
+            required: ["cwd"],
+        },
+        annotations: {
+            title: "Build Pattern Index",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "rigour_context_scope",
+        description: "CALL THIS BEFORE reading source files. Returns a minimal editScope (3-10 files) with signatures from the pattern index instead of full file bodies. Uses semantic search when embeddings are available. If index is missing, instructs to call rigour_index first. Highest-impact token saver in the Rigour protocol.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...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)." },
+            },
+            required: ["cwd", "query"],
+        },
+        annotations: {
+            title: "Scoped Context Retrieval",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
 ];

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

@@ -0,0 +1,6 @@
+import { type ToolResult } from '../utils/context-telemetry.js';
+export declare function handleIndex(cwd: string, options?: {
+    semantic?: boolean;
+    force?: boolean;
+    output?: string;
+}): Promise<ToolResult>;

package/dist/tools/index-handlers.js

@@ -0,0 +1,95 @@
+/**
+ * Pattern Index MCP Tool Handler
+ *
+ * Wraps PatternIndexer for agent-accessible index build/update.
+ */
+import path from 'path';
+import { PatternIndexer, savePatternIndex, loadPatternIndex, getDefaultIndexPath, } from '@rigour-labs/core/pattern-index';
+import { setStaticCache, setComponentCache, } from '@rigour-labs/core';
+import { notifyProgress } from '../utils/notifications.js';
+import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
+import { appendContextFooter } from '../utils/context-footer.js';
+import fs from 'fs-extra';
+async function syncIndexToCache(cwd, index) {
+    const commitSha = await getWorkspaceCommitSha(cwd);
+    const repo = path.basename(cwd);
+    const byFile = new Map();
+    for (const pattern of index.patterns) {
+        const list = byFile.get(pattern.file) ?? [];
+        list.push(pattern);
+        byFile.set(pattern.file, list);
+    }
+    for (const [filePath, patterns] of byFile) {
+        const absPath = path.join(cwd, filePath);
+        let content = '';
+        try {
+            if (await fs.pathExists(absPath)) {
+                content = await fs.readFile(absPath, 'utf-8');
+            }
+        }
+        catch {
+            content = patterns.map(p => p.signature ?? p.name).join('\n');
+        }
+        await setStaticCache(repo, 'main', filePath, content || filePath, {
+            exports: patterns.map(p => p.name),
+            rigourPatterns: patterns.map(p => `${p.type}:${p.name}`),
+            ownership: path.dirname(filePath),
+        }, cwd);
+        const componentName = path.dirname(filePath) || filePath;
+        const dossier = {
+            component: componentName,
+            responsibility: `Indexed patterns in ${filePath}`,
+            canonicalFiles: [filePath],
+            contracts: patterns.filter(p => p.type === 'interface' || p.type === 'type').map(p => p.name),
+            directConsumers: [],
+            validationCommands: [],
+        };
+        await setComponentCache(componentName, commitSha, dossier, `index-${index.lastUpdated}`, '3', cwd);
+    }
+}
+export async function handleIndex(cwd, options = {}) {
+    const indexPath = options.output || getDefaultIndexPath(cwd);
+    const candidateEstimate = 'Full codebase AST scan for pattern extraction';
+    try {
+        notifyProgress('info', 'Building pattern index...');
+        const indexer = new PatternIndexer(cwd, { useEmbeddings: options.semantic ?? false });
+        const existingIndex = await loadPatternIndex(indexPath);
+        let index;
+        if (existingIndex && !options.force) {
+            index = await indexer.updateIndex(existingIndex);
+        }
+        else {
+            index = await indexer.buildIndex();
+        }
+        await savePatternIndex(index, indexPath);
+        await syncIndexToCache(cwd, index);
+        notifyProgress('info', 'Pattern index complete');
+        const byType = Object.entries(index.stats.byType)
+            .map(([type, count]) => `${type}: ${count}`)
+            .join(', ');
+        let text = `✅ PATTERN INDEX ${options.force ? 'REBUILT' : 'UPDATED'}\n\n`;
+        text += `- Total Patterns: ${index.stats.totalPatterns}\n`;
+        text += `- Total Files: ${index.stats.totalFiles}\n`;
+        text += `- Index Path: ${indexPath}\n`;
+        text += `- Duration: ${index.stats.indexDurationMs}ms\n`;
+        if (options.semantic)
+            text += `- Semantic Search: Enabled\n`;
+        text += `- Types: ${byType}\n\n`;
+        text += `Index synced to context cache layers. Use rigour_context_scope before reading files.`;
+        const telemetry = buildTelemetryMeta({
+            candidateText: candidateEstimate,
+            returnedText: text,
+            cacheStatus: 'miss',
+        });
+        return {
+            content: [{ type: 'text', text: appendContextFooter(text, telemetry, 'rigour_context_scope("your task")') }],
+            _telemetry: telemetry,
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `RIGOUR ERROR: Failed to build pattern index: ${error.message}` }],
+            isError: true,
+        };
+    }
+}

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

@@ -1,10 +1,4 @@
-type ToolResult = {
-    content: {
-        type: string;
-        text: string;
-    }[];
-};
+import { type ToolResult } from '../utils/context-telemetry.js';
 export declare function handleRemember(cwd: string, key: string, value: string): Promise<ToolResult>;
 export declare function handleRecall(cwd: string, key?: string): Promise<ToolResult>;
 export declare function handleForget(cwd: string, key: string): Promise<ToolResult>;
-export {};

package/dist/tools/memory-handlers.js

@@ -10,7 +10,10 @@
  * @since v4.2.0  — DLP gate on memory persistence
  */
 import { loadMemory, saveMemory } from '../utils/config.js';
-import { scanInputForCredentials, formatDLPAlert, createDLPAuditEntry } from '@rigour-labs/core';
+import { scanInputForCredentials, formatDLPAlert, createDLPAuditEntry, getSemanticQueryCache, setSemanticQueryCache, estimateTokenCount, } from '@rigour-labs/core';
+import { loadPatternIndex, getDefaultIndexPath, } from '@rigour-labs/core/pattern-index';
+import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
+import { appendContextFooter } from '../utils/context-footer.js';
 import fs from 'fs-extra';
 import path from 'path';
 /**
@@ -49,6 +52,29 @@ function extractStrings(obj, out) {
             extractStrings(v, out);
     }
 }
+async function getIndexHealthBlock(cwd) {
+    const indexPath = getDefaultIndexPath(cwd);
+    const index = await loadPatternIndex(indexPath);
+    if (!index) {
+        return '\n\n📊 Pattern Index: NOT FOUND — call rigour_index to enable scope optimization and reinvention detection.';
+    }
+    return `\n\n📊 Pattern Index: ${index.stats.totalPatterns} patterns across ${index.stats.totalFiles} files (updated ${index.lastUpdated}).`;
+}
+function wrapRecallResult(text, candidateText, cacheStatus, deduplicatedTokens = 0) {
+    const telemetry = buildTelemetryMeta({
+        candidateText,
+        returnedText: text,
+        cacheStatus,
+        deduplicatedTokens,
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: appendContextFooter(text, telemetry, 'rigour_context_scope("your task")'),
+            }],
+        _telemetry: telemetry,
+    };
+}
 export async function handleRemember(cwd, key, value) {
     // Fallback: if key is missing but value exists, auto-generate a key
     if (!key && value) {
@@ -103,11 +129,21 @@ export async function handleRemember(cwd, key, value) {
     };
 }
 export async function handleRecall(cwd, key) {
+    const commitSha = await getWorkspaceCommitSha(cwd);
+    const cacheQuery = key ? `recall:${key}` : 'recall:all';
     const store = await loadMemory(cwd);
+    const candidateText = JSON.stringify(store);
+    const cached = await getSemanticQueryCache(cacheQuery, commitSha, cwd);
+    if (cached?.evidence?.length) {
+        const cachedBody = cached.evidence.join('\n');
+        const indexHealth = await getIndexHealthBlock(cwd);
+        return wrapRecallResult(`${cachedBody}${indexHealth}`, candidateText, 'semantic-hit', Math.max(0, estimateTokenCount(candidateText) - estimateTokenCount(cachedBody)));
+    }
     if (key) {
         const memory = store.memories[key];
         if (!memory) {
-            return { content: [{ type: "text", text: `NO MEMORY FOUND for key "${key}". Use rigour_remember to store instructions.` }] };
+            const text = `NO MEMORY FOUND for key "${key}". Use rigour_remember to store instructions.${await getIndexHealthBlock(cwd)}`;
+            return wrapRecallResult(text, candidateText, 'miss');
         }
         // ── DLP Gate on recall: catch credentials stored before DLP existed ──
         const dlpResult = scanInputForCredentials(memory.value);
@@ -125,11 +161,24 @@ export async function handleRecall(cwd, key) {
                     }],
             };
         }
-        return { content: [{ type: "text", text: `RECALLED MEMORY [${key}]:\n${memory.value}\n\n(Stored: ${memory.timestamp})` }] };
+        const body = `RECALLED MEMORY [${key}]:\n${memory.value}\n\n(Stored: ${memory.timestamp})`;
+        const indexHealth = await getIndexHealthBlock(cwd);
+        const fullText = `${body}${indexHealth}`;
+        await setSemanticQueryCache(cacheQuery, commitSha, {
+            query: cacheQuery,
+            resolvedOwner: 'memory',
+            editScope: [],
+            validationScope: [],
+            evidence: [body],
+            commitSha,
+            confidence: 1,
+        }, cwd);
+        return wrapRecallResult(fullText, candidateText, 'miss');
     }
     const keys = Object.keys(store.memories);
     if (keys.length === 0) {
-        return { content: [{ type: "text", text: "NO MEMORIES STORED. Use rigour_remember to persist important instructions." }] };
+        const text = `NO MEMORIES STORED. Use rigour_remember to persist important instructions.${await getIndexHealthBlock(cwd)}`;
+        return wrapRecallResult(text, candidateText, 'miss');
     }
     // ── DLP scan all memories on bulk recall ──
     const cleanMemories = [];
@@ -157,7 +206,17 @@ export async function handleRecall(cwd, key) {
     else {
         text = "NO MEMORIES STORED. Use rigour_remember to persist important instructions.";
     }
-    return { content: [{ type: "text", text }] };
+    text += await getIndexHealthBlock(cwd);
+    await setSemanticQueryCache(cacheQuery, commitSha, {
+        query: cacheQuery,
+        resolvedOwner: 'memory',
+        editScope: [],
+        validationScope: [],
+        evidence: [text],
+        commitSha,
+        confidence: 1,
+    }, cwd);
+    return wrapRecallResult(text, candidateText, 'miss', Math.max(0, estimateTokenCount(candidateText) - estimateTokenCount(text)));
 }
 export async function handleForget(cwd, key) {
     const store = await loadMemory(cwd);

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

@@ -1,9 +1,3 @@
-type ToolResult = {
-    content: {
-        type: string;
-        text: string;
-    }[];
-};
+import { type ToolResult } from '../utils/context-telemetry.js';
 export declare function handleCheckPattern(cwd: string, patternName: string, type?: string, intent?: string, file?: string): Promise<ToolResult>;
 export declare function handleSecurityAudit(cwd: string): Promise<ToolResult>;
-export {};

package/dist/tools/pattern-handlers.js

@@ -9,8 +9,10 @@ import path from "path";
 import yaml from "yaml";
 import fs from "fs-extra";
 import { PatternMatcher, loadPatternIndex, getDefaultIndexPath, StalenessDetector, SecurityDetector, } from "@rigour-labs/core/pattern-index";
-import { ConfigSchema } from "@rigour-labs/core";
+import { ConfigSchema, getSemanticQueryCache, setSemanticQueryCache, estimateTokenCount } from "@rigour-labs/core";
 import { notifyProgress } from '../utils/notifications.js';
+import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
+import { appendContextFooter } from '../utils/context-footer.js';
 /**
  * Check if a file path is protected by safety.protected_paths in rigour.yml.
  * Returns the matched pattern or null.
@@ -41,7 +43,33 @@ async function checkFileGuard(cwd, filePath) {
         return normalized.startsWith(clean + '/');
     }) ?? null;
 }
+function buildCacheQuery(patternName, type, intent, file) {
+    return `check_pattern:${patternName}:${type ?? ''}:${intent ?? ''}:${file ?? ''}`;
+}
 export async function handleCheckPattern(cwd, patternName, type, intent, file) {
+    const commitSha = await getWorkspaceCommitSha(cwd);
+    const cacheQuery = buildCacheQuery(patternName, type, intent, file);
+    const indexPath = getDefaultIndexPath(cwd);
+    const index = await loadPatternIndex(indexPath);
+    const indexScanEstimate = index
+        ? `Pattern index scan (${index.stats.totalPatterns} patterns) for ${patternName}`
+        : `Full pattern discovery for ${patternName}`;
+    const cached = await getSemanticQueryCache(cacheQuery, commitSha, cwd);
+    if (cached?.evidence?.length) {
+        const cachedText = cached.evidence.join('\n');
+        const telemetry = buildTelemetryMeta({
+            candidateText: indexScanEstimate,
+            returnedText: cachedText,
+            cacheStatus: 'exact-hit',
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: appendContextFooter(cachedText, telemetry, 'proceed with implementation or rigour_check when done'),
+                }],
+            _telemetry: telemetry,
+        };
+    }
     let resultText = "";
     // 0. File Guard — BLOCK writes to protected paths
     if (file) {
@@ -52,12 +80,18 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
             resultText += `This path matches protected pattern "${matched}" in rigour.yml.\n`;
             resultText += `CI/CD pipelines, governance configs, and protected docs require human review.\n\n`;
             resultText += `RECOMMENDED ACTION: STOP. Do not create or modify this file. Ask the human to make this change manually.`;
-            return { content: [{ type: "text", text: resultText }] };
+            const telemetry = buildTelemetryMeta({
+                candidateText: indexScanEstimate,
+                returnedText: resultText,
+                cacheStatus: 'miss',
+            });
+            return {
+                content: [{ type: "text", text: appendContextFooter(resultText, telemetry) }],
+                _telemetry: telemetry,
+            };
         }
     }
     // 1. Check for Reinvention
-    const indexPath = getDefaultIndexPath(cwd);
-    const index = await loadPatternIndex(indexPath);
     if (index) {
         const matcher = new PatternMatcher(index);
         const matchResult = await matcher.match({ name: patternName, type, intent });
@@ -68,7 +102,7 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
         }
     }
     else {
-        resultText += `⚠️ Pattern index not found. Run 'rigour index' to enable reinvention detection.\n\n`;
+        resultText += `⚠️ Pattern index not found. Run rigour_index to enable reinvention detection.\n\n`;
     }
     // 2. Check for Staleness/Best Practices
     const detector = new StalenessDetector(cwd);
@@ -110,12 +144,42 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
         }
         resultText += `\nRECOMMENDED ACTION: ${recommendation}`;
     }
-    return { content: [{ type: "text", text: resultText }] };
+    await setSemanticQueryCache(cacheQuery, commitSha, {
+        query: cacheQuery,
+        resolvedOwner: file ? path.dirname(file) : 'patterns',
+        editScope: file ? [file] : [],
+        validationScope: [],
+        evidence: [resultText],
+        commitSha,
+        confidence: resultText.includes('✅') ? 0.9 : 0.7,
+    }, cwd);
+    const telemetry = buildTelemetryMeta({
+        candidateText: indexScanEstimate,
+        returnedText: resultText,
+        cacheStatus: 'miss',
+        deduplicatedTokens: index
+            ? Math.max(0, estimateTokenCount(indexScanEstimate) - estimateTokenCount(resultText))
+            : 0,
+    });
+    return {
+        content: [{
+                type: "text",
+                text: appendContextFooter(resultText, telemetry, 'rigour_check before declaring done'),
+            }],
+        _telemetry: telemetry,
+    };
 }
 export async function handleSecurityAudit(cwd) {
     notifyProgress("info", "Running CVE security audit...");
     const security = new SecurityDetector(cwd);
     const summary = await security.getSecuritySummary();
     notifyProgress("info", "Security audit complete");
-    return { content: [{ type: "text", text: summary }] };
+    return {
+        content: [{ type: "text", text: summary }],
+        _telemetry: buildTelemetryMeta({
+            candidateText: summary,
+            returnedText: summary,
+            cacheStatus: 'none',
+        }),
+    };
 }

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

@@ -0,0 +1,6 @@
+/**
+ * Closed-loop context efficiency footers appended to MCP tool responses.
+ */
+import type { TelemetryMeta } from './context-telemetry.js';
+export declare function formatContextFooter(meta: TelemetryMeta, nextStep?: string): string;
+export declare function appendContextFooter(text: string, meta: TelemetryMeta | undefined, nextStep?: string): string;

package/dist/utils/context-footer.js

@@ -0,0 +1,19 @@
+export function formatContextFooter(meta, nextStep) {
+    const saved = Math.max(0, meta.candidateTokens - meta.returnedTokens);
+    let footer = `\n\n[Rigour Context] cache=${meta.cacheStatus}`;
+    if (saved > 0) {
+        footer += ` | saved~${saved.toLocaleString()} tokens`;
+    }
+    if (meta.deduplicatedTokens && meta.deduplicatedTokens > 0) {
+        footer += ` | dedup~${meta.deduplicatedTokens.toLocaleString()} tokens`;
+    }
+    if (nextStep) {
+        footer += ` | Next: ${nextStep}`;
+    }
+    return footer;
+}
+export function appendContextFooter(text, meta, nextStep) {
+    if (!meta)
+        return text;
+    return text + formatContextFooter(meta, nextStep);
+}