smart-context-mcp 1.11.0 → 1.14.0

package/README.md

@@ -56,7 +56,7 @@ Restart your AI client. Done.
 # Check installed version
 npm list -g smart-context-mcp
 
-# Should show: smart-context-mcp@1.11.0 (or later)
+# Should show: smart-context-mcp@1.14.0 (or later)
 
 # Update to latest version
 npm update -g smart-context-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-context-mcp",
   "mcpName": "io.github.Arrayo/smart-context-mcp",
-  "version": "1.11.0",
+  "version": "1.14.0",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",
@@ -60,6 +60,7 @@
     "init:clients": "node ./scripts/init-clients.js",
     "smoke:formats": "node ./scripts/format-smoke.js",
     "test": "node --test --test-concurrency=1 ./tests/*.test.js",
+    "test:fast": "node --test --test-concurrency=4 ./tests/*.test.js",
     "verify": "node ./scripts/verify-features-direct.js",
     "benchmark": "node ./scripts/run-benchmark.js",
     "benchmark:orchestration": "node ./evals/orchestration-benchmark.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Arrayo/smart-context-mcp",
     "source": "github"
   },
-  "version": "1.11.0",
+  "version": "1.14.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-context-mcp",
-      "version": "1.11.0",
+      "version": "1.14.0",
       "transport": {
         "type": "stdio"
       },

package/src/index-manager.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { execFile as execFileCallback } from 'node:child_process';
 import { promisify } from 'node:util';
 import { projectRoot } from './utils/paths.js';
-import { loadIndex, buildIndex as buildIndexCore } from './index.js';
+import { loadIndex, buildIndexIncremental, persistIndex } from './index.js';
 
 const execFile = promisify(execFileCallback);
 
@@ -83,23 +83,28 @@ export const ensureIndexReady = async (options = {}) => {
   }
   
   log('Building search index...');
-  
+
   try {
-    const buildPromise = buildIndexCore({ root, incremental: true });
+    const buildPromise = (async () => {
+      const { index, stats } = buildIndexIncremental(root);
+      await persistIndex(index, root);
+      return { stats, fileCount: Object.keys(index.files).length, version: index.version };
+    })();
+
     const result = await Promise.race([
       buildPromise,
-      timeout(timeoutMs, 'Index build timeout')
+      timeout(timeoutMs, 'Index build timeout'),
     ]);
-    
+
     saveIndexMetadata({
       builtAt: Date.now(),
       gitHead: getGitHead(root),
-      fileCount: result?.files?.length || 0,
-      version: result?.version
+      fileCount: result.fileCount,
+      version: result.version,
     }, root);
-    
+
     log('Index ready');
-    return { status: 'built', cached: false, fileCount: result?.files?.length || 0 };
+    return { status: 'built', cached: false, fileCount: result.fileCount };
   } catch (error) {
     log(`Index build failed: ${error.message}`);
     return { status: 'fallback', error: error.message };

package/src/server.js

@@ -39,7 +39,7 @@ export const asTextResult = (result) => ({
   content: [
     {
       type: 'text',
-      text: JSON.stringify(result, null, 2),
+      text: JSON.stringify(result),
     },
   ],
 });
@@ -61,7 +61,7 @@ export const createDevctxServer = () => {
 
   server.prompt(
     'use-devctx',
-    'Force the agent to use devctx tools for the current task. Use this prompt at the start of your message to ensure devctx is used instead of native tools.',
+    'Force the agent to use devctx tools for the current task.',
     {},
     async () => ({
       messages: [
@@ -69,7 +69,7 @@ export const createDevctxServer = () => {
           role: 'user',
           content: {
             type: 'text',
-            text: 'Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)',
+            text: 'Use devctx MCP tools for this task. Start with smart_context(task) for multi-file context. Use smart_read(outline) → smart_read(symbol) cascade for individual files. Never use native Read on large files.',
           },
         },
       ],
@@ -78,7 +78,7 @@ export const createDevctxServer = () => {
 
   server.prompt(
     'devctx-workflow',
-    'Complete devctx workflow template with all recommended steps. Includes session start, context building, file reading, and session end.',
+    'Complete devctx workflow for complex tasks with session continuity.',
     {},
     async () => ({
       messages: [
@@ -86,15 +86,7 @@ export const createDevctxServer = () => {
           role: 'user',
           content: {
             type: 'text',
-            text: `Follow this devctx workflow:
-
-1. smart_turn(start) - Start session and recover previous context
-2. smart_context(task) - Build complete context for the task
-3. smart_search(query) - Search for specific patterns if needed
-4. smart_read(file) - Read files with appropriate mode (outline/signatures/symbol)
-5. smart_turn(end) - Save checkpoint for next session
-
-Use devctx tools instead of native Read/Grep/Shell when possible.`,
+            text: 'Follow devctx workflow: 1) smart_turn(start) to recover session 2) smart_context(task) for curated context (replaces search+read cycle) 3) smart_read(symbol) only for specific functions not covered by smart_context 4) smart_turn(end) to checkpoint. Never skip to smart_read(full) — use the cascade: outline → signatures → symbol → full.',
           },
         },
       ],
@@ -103,7 +95,7 @@ Use devctx tools instead of native Read/Grep/Shell when possible.`,
 
   server.prompt(
     'devctx-preflight',
-    'Preflight checklist before starting work. Ensures index is built and session is initialized.',
+    'Preflight: build index and initialize session before work.',
     {},
     async () => ({
       messages: [
@@ -111,13 +103,7 @@ Use devctx tools instead of native Read/Grep/Shell when possible.`,
           role: 'user',
           content: {
             type: 'text',
-            text: `Preflight checklist:
-
-1. build_index(incremental=true) - Build/update symbol index
-2. smart_turn(start) - Initialize session and recover context
-3. Proceed with your task using devctx tools
-
-This ensures optimal performance and context recovery.`,
+            text: 'Preflight: 1) build_index(incremental=true) 2) smart_turn(start) 3) Proceed with devctx tools.',
           },
         },
       ],
@@ -126,7 +112,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_read',
-    'Read a file with token-efficient modes. PREFER outline/signatures/symbol — full mode saves 0 tokens (same content as native Read, capped at 12k chars). Mode guide: outline (~90% savings): file structure, exports, top-level symbols — use for orientation, code review, deciding what to read next. signatures (~85% savings): function/method signatures only — use when you need parameter names and return types without bodies. symbol: extract one or more functions/classes/methods by name (string or array for batch) — use when you know exactly what to read; add context=true to include callers, tests, and referenced types from the dependency graph (returns graphCoverage: full|partial|none). range: specific line range with line numbers — use only when you need exact lines. full: raw file content, no compression, no savings — only use when the exact byte-for-byte content is required (e.g. config files, lock files). maxTokens: token budget — auto-selects the most detailed mode that fits (full → outline → signatures → truncated). Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
+    'Read a file with token-efficient modes. ALWAYS prefer outline/signatures/symbol over full. Reading cascade: outline → signatures → symbol → range → full (last resort). Mode guide: outline (~90% savings): file structure, exports, top-level symbols — use first for orientation. signatures (~85% savings): function signatures with parameters and return types — use when you need the API surface. symbol: extract specific functions/classes by name (string or array) — use when you know what to read; add context=true for callers, tests, and dependencies. range: specific line range — use only when you need exact lines. full: raw content, no savings — only for config/lock files. maxTokens: token budget — auto-cascades to fit (outline → signatures → truncated). Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
     {
       filePath: z.string(),
       mode: z.enum(['full', 'outline', 'signatures', 'range', 'symbol']).optional(),
@@ -160,18 +146,19 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_search',
-    'Search code across the project using ripgrep (with filesystem fallback). Returns grouped, ranked results. Optional intent (implementation/debug/tests/config/docs/explore) adjusts ranking: tests boosts test files, config boosts config files, docs reduces penalty on READMEs. Includes a unified confidence block: { level, indexFreshness } plus retrievalConfidence and provenance metadata.',
+    'Search code with ranked, deduplicated results and index boosting. Best for: finding where a symbol is defined/used, understanding call chains, locating implementations. NOT ideal for: exact string matching (use Grep), finding files by name (use Glob), broad multi-word queries (generates noise). Optional intent adjusts ranking. maxFiles caps the number of files returned (default 15). When >30 files match, results include a hint suggesting Grep instead.',
     {
       query: z.string(),
       cwd: z.string().optional(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
+      maxFiles: z.number().int().min(1).max(50).optional(),
     },
-    async ({ query, cwd = '.', intent }) => asTextResult(await smartSearch({ query, cwd, intent })),
+    async ({ query, cwd = '.', intent, maxFiles }) => asTextResult(await smartSearch({ query, cwd, intent, maxFiles })),
   );
 
   server.tool(
     'smart_context',
-    'Get curated context for a task in one call. Combines smart_search + smart_read + graph expansion. Returns relevant files, evidence for why each file was included, related tests, dependencies, symbol previews from the index, and symbol details — optimized for tokens. Includes a unified confidence block: { indexFreshness, graphCoverage } indicating index state and how complete the relational context is. Replaces the manual search → read → read cycle. Optional intent override, token budget, diff mode (pass diff=true for HEAD or diff="main" to scope context to changed files only), detail mode (minimal=index+signatures+snippets, balanced=default, deep=full content), include array to control which fields are returned (["content","graph","hints","symbolDetail"]), and prefetch=true to enable intelligent context prediction based on historical patterns (reduces round-trips by 40-60%).',
+    'PREFERRED for multi-file tasks. Gets curated context in one call — replaces the manual search → read → read cycle. Combines search + graph expansion + selective reading. Returns relevant files with symbols and content, optimized for tokens. Options: intent, maxTokens (budget), diff (true for HEAD or branch name), detail (minimal/balanced/deep), include (content/graph/hints/symbolDetail), prefetch (true for predictive loading). Call this FIRST before individual smart_read/smart_search calls.',
     {
       task: z.string(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
@@ -188,7 +175,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_shell',
-    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. For large diffs: output is split by file (up to 8 files, 60 lines each) with a hint to run git show -- <file> for the full body of any truncated file; prefer git diff --stat first to see which files changed, then git show -- <file> per file for targeted reading. Includes a unified confidence block: { blocked, timedOut }.',
+    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. For large diffs: output is split by file (up to 8 files, 60 lines each); prefer git diff --stat first, then git show -- <file> per file.',
     {
       command: z.string(),
     },

package/src/tokenCounter.js

@@ -1,12 +1,35 @@
 import { encodingForModel } from 'js-tiktoken';
 
-const fallbackModel = 'gpt-4o-mini';
-const encoder = encodingForModel(fallbackModel);
+const CLAUDE_ALIASES = new Set(['claude', 'anthropic']);
 
-export const countTokens = (text = '') => {
-  if (!text) {
-    return 0;
+// js-tiktoken does not ship Claude's tokenizer; gpt-4o (o200k_base) is the
+// closest available encoding. Accuracy for Claude models: ±15-20%.
+const CLAUDE_FALLBACK = 'gpt-4o';
+const DEFAULT_MODEL = 'gpt-4o-mini';
+
+const resolveModel = () => {
+  const requested = (process.env.DEVCTX_TOKEN_MODEL || '').toLowerCase().trim();
+  if (!requested) return DEFAULT_MODEL;
+  if (CLAUDE_ALIASES.has(requested) || requested.startsWith('claude')) {
+    return CLAUDE_FALLBACK;
+  }
+  return requested;
+};
+
+const buildEncoder = () => {
+  const model = resolveModel();
+  try {
+    return encodingForModel(model);
+  } catch {
+    return encodingForModel(DEFAULT_MODEL);
   }
+};
 
+// Encoder is initialised once; if the env var changes at runtime the process
+// must be restarted (acceptable for a CLI/MCP server).
+const encoder = buildEncoder();
+
+export const countTokens = (text = '') => {
+  if (!text) return 0;
   return encoder.encode(String(text)).length;
 };

package/src/tools/smart-context.js

@@ -15,7 +15,6 @@ import { predictContextFiles, recordContextAccess } from '../context-patterns.js
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
 import { createProgressReporter } from '../streaming.js';
 import { 
   getDetailedDiff, 
@@ -35,7 +34,6 @@ import {
 } from '../utils/query-extraction.js';
 import {
   dedupeEvidence,
-  formatReasonIncluded,
   buildSymbolPreviews,
   attachSymbolEvidence,
   computeStaticUtility,
@@ -226,29 +224,6 @@ const getSymbolSignatureLimit = (item, detailMode, readMode) => {
 const getSymbolSignatures = (entries, maxItems = 10) =>
   entries.filter((entry) => entry.signature).slice(0, maxItems).map((entry) => entry.signature);
 
-const serializeEvidencePayload = (item) => {
-  const evidence = dedupeEvidence(item.evidence ?? []);
-  if (evidence.length === 0) return [];
-
-  const limit = item.role === 'primary' ? 2 : 1;
-  const preferred = item.role === 'primary'
-    ? evidence
-    : [
-      evidence.find((entry) => ['testOf', 'dependencyOf', 'dependentOf'].includes(entry.type)),
-      evidence[0],
-    ].filter(Boolean);
-
-  return uniqueList(preferred)
-    .slice(0, limit)
-    .map((entry) => ({
-      type: entry.type,
-      ...(entry.via ? { via: entry.via } : {}),
-      ...(entry.query && item.role === 'primary' ? { query: entry.query } : {}),
-      ...(entry.ref && item.role === 'primary' ? { ref: entry.ref } : {}),
-      ...(Array.isArray(entry.symbols) && entry.symbols.length > 0 ? { symbols: entry.symbols.slice(0, 2) } : {}),
-    }));
-};
-
 const shouldIncludeSymbolNames = (item, symbolPreviews, readMode) => {
   if (item.role === 'primary') return true;
   if (readMode === 'full') return true;
@@ -273,14 +248,10 @@ const buildContextItemPayload = (item, index, detailMode, readMode = 'index-only
   const symbolSignatures = shouldIncludeSymbolSignatures(item, symbolPreviews)
     ? getSymbolSignatures(fileSymbolEntries, getSymbolSignatureLimit(item, detailMode, readMode))
     : [];
-  const evidence = serializeEvidencePayload(item);
 
   return {
     file: item.rel,
     role: item.role,
-    readMode,
-    reasonIncluded: formatReasonIncluded(item.evidence),
-    evidence,
     ...(fileSymbols.length > 0 ? { symbols: fileSymbols } : {}),
     ...(symbolSignatures.length > 0 ? { symbolSignatures } : {}),
     ...(symbolPreviews.length > 0 ? { symbolPreviews } : {}),
@@ -669,16 +640,9 @@ export const smartContext = async ({
 
         const filtered = filterFoundSymbols(symbolResult.content, symbolCandidates);
         if (filtered) {
-          const symbolEvidence = dedupeEvidence([{
-            type: 'symbolDetail',
-            symbols: symbolCandidates.slice(0, 3),
-          }]);
           const symbolPayload = {
             file: topPrimary.rel,
             role: 'symbolDetail',
-            readMode: 'symbol',
-            reasonIncluded: formatReasonIncluded(symbolEvidence),
-            evidence: symbolEvidence,
             content: filtered,
           };
           const symbolTokens = countTokens(JSON.stringify(symbolPayload));
@@ -692,7 +656,6 @@ export const smartContext = async ({
                 const existing = context[existingIdx];
                 const signaturesOnly = {
                   ...existing,
-                  readMode: 'signatures-only',
                   content: '(omitted — see symbolDetail)',
                 };
                 const oldTokens = countTokens(JSON.stringify(existing));
@@ -747,7 +710,6 @@ export const smartContext = async ({
 
   const contentTokens = countTokens(context.map((c) => c.content).join('\n'));
   const previewTokens = context.reduce((sum, item) => sum + countTokens(JSON.stringify(item.symbolPreviews ?? [])), 0);
-  const indexOnlyItems = context.filter((item) => item.readMode === 'index-only').length;
   const contentItems = context.filter((item) => typeof item.content === 'string' && item.content.length > 0).length;
   const primaryItem = context.find((item) => item.role === 'primary');
 
@@ -816,17 +778,6 @@ export const smartContext = async ({
   };
 
   const filesIncluded = new Set(context.map((c) => c.file)).size;
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_context',
-    target: task,
-    metrics: {
-      rawTokens: totalRawTokens,
-      compressedTokens: totalCompressedTokens,
-      savedTokens,
-    },
-    startTime: enableProgress ? startTime : null,
-    filesCount: filesIncluded,
-  });
 
   if (progress) {
     progress.complete({
@@ -845,28 +796,20 @@ export const smartContext = async ({
     confidence: { indexFreshness, graphCoverage: graphCov },
     context,
     ...(includeSet.has('graph') ? { graph: graphSummary, graphCoverage: graphCov } : {}),
-    metrics: {
-      contentTokens,
-      totalTokens: 0,
+    stats: {
       filesIncluded,
       filesEvaluated: expanded.size,
-      savingsPct,
       detailMode,
-      include: [...includeSet],
-      previewTokens,
-      indexOnlyItems,
-      contentItems,
-      primaryReadMode: primaryItem?.readMode ?? null,
+      totalTokens: countTokens(context.map((c) => c.content || '').join('')),
       ...(prefetchResult ? {
         prefetch: {
           enabled: true,
           confidence: prefetchResult.confidence || 0,
           predictedFiles: prefetchResult.predicted?.length || 0,
-          matchedPattern: prefetchResult.matchedPattern || null
-        }
-      } : {})
+          matchedPattern: prefetchResult.matchedPattern || null,
+        },
+      } : {}),
     },
-    metricsDisplay,
     ...(includeSet.has('hints') ? { hints } : {}),
   };
 
@@ -875,7 +818,5 @@ export const smartContext = async ({
     result.diffSummary = diffSummary;
   }
 
-  result.metrics.totalTokens = countTokens(JSON.stringify(result));
-
   return result;
 };

package/src/tools/smart-read/code.js

@@ -105,15 +105,25 @@ const formatDeclarationName = (name) => {
 
 const collectVariableNames = (declarationList) => declarationList.declarations.map((declaration) => formatDeclarationName(declaration.name));
 
-const formatTopLevelStatement = (statement, sourceFile) => {
+const getFunctionSignature = (statement, sourceFile) => {
+  const body = statement.body;
+  if (!body) return statement.getText(sourceFile).split('\n')[0];
+  const fullText = statement.getText(sourceFile);
+  const bodyOffset = body.getStart(sourceFile) - statement.getStart(sourceFile);
+  const sig = fullText.slice(0, bodyOffset).replace(/\s+$/, '');
+  return sig.length > 120 ? `${sig.slice(0, 120)}...` : sig;
+};
+
+const formatTopLevelStatement = (statement, sourceFile, mode = 'outline') => {
   const exported = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
   const prefix = exported ? 'export ' : '';
 
   if (ts.isImportDeclaration(statement)) {
-    return formatImport(statement);
+    return null;
   }
 
   if (ts.isFunctionDeclaration(statement)) {
+    if (mode === 'signatures') return getFunctionSignature(statement, sourceFile);
     return `${prefix}function ${getNodeName(statement)}()`;
   }
 
@@ -143,7 +153,8 @@ const formatTopLevelStatement = (statement, sourceFile) => {
   }
 
   if (ts.isExportAssignment(statement)) {
-    return `export default ${statement.expression.getText(sourceFile)}`;
+    const text = statement.expression.getText(sourceFile);
+    return `export default ${text.length > 60 ? `${text.slice(0, 60)}...` : text}`;
   }
 
   return statement.getText(sourceFile).split('\n')[0];
@@ -248,7 +259,8 @@ export const summarizeCode = (fullPath, content, mode) => {
   const sourceFile = parseSource(fullPath, content);
   const topLevel = sourceFile.statements.flatMap((statement) => {
     if (isIIFE(statement)) return extractIIFEMembers(statement, sourceFile);
-    return [formatTopLevelStatement(statement, sourceFile)];
+    const formatted = formatTopLevelStatement(statement, sourceFile, mode);
+    return formatted !== null ? [formatted] : [];
   });
   const hooks = collectHooks(sourceFile);
 

package/src/tools/smart-read-batch.js

@@ -4,7 +4,6 @@ import { countTokens } from '../tokenCounter.js';
 export const smartReadBatch = async ({ files, maxTokens }) => {
   const results = [];
   let totalTokens = 0;
-  let totalRawTokens = 0;
   let filesSkipped = 0;
 
   for (const item of files) {
@@ -40,13 +39,11 @@ export const smartReadBatch = async ({ files, maxTokens }) => {
         parser: readResult.parser,
         truncated: readResult.truncated,
         content: readResult.content,
-        ...(readResult.confidence ? { confidence: readResult.confidence } : {}),
         ...(readResult.indexHint !== undefined ? { indexHint: readResult.indexHint } : {}),
         ...(readResult.chosenMode ? { chosenMode: readResult.chosenMode, budgetApplied: true } : {}),
       });
 
       totalTokens += itemTokens;
-      totalRawTokens += readResult.metrics?.rawTokens ?? 0;
     } catch (err) {
       results.push({
         filePath: item.path,
@@ -56,17 +53,12 @@ export const smartReadBatch = async ({ files, maxTokens }) => {
     }
   }
 
-  const totalSavingsPct = totalRawTokens > 0
-    ? Math.max(0, Math.round(((totalRawTokens - totalTokens) / totalRawTokens) * 100))
-    : 0;
-
   return {
     results,
     metrics: {
       totalTokens,
       filesRead: results.length,
       filesSkipped,
-      totalSavingsPct,
     },
   };
 };

package/src/tools/smart-read.js

@@ -12,7 +12,6 @@ import { countTokens } from '../tokenCounter.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
 import { createProgressReporter } from '../streaming.js';
 
 const execFile = promisify(execFileCb);
@@ -563,16 +562,6 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
     context: `${lineCount} lines, ${metrics.rawTokens} tokens → ${metrics.compressedTokens} tokens`,
   });
 
-  const confidence = { parser, truncated, cached: cacheHit && !contextResult };
-  if (contextResult) confidence.graphCoverage = contextResult.graphCoverage;
-
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_read',
-    target: path.relative(effectiveRoot, fullPath),
-    metrics,
-    startTime: enableProgress ? startTime : null,
-  });
-
   if (progress) {
     progress.complete({
       file: path.relative(effectiveRoot, fullPath),
@@ -588,12 +577,7 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
     parser,
     truncated,
     content: compressedText,
-    confidence,
-    metrics,
-    metricsDisplay,
   };
-
-  if (cacheHit && !contextResult) result.cached = true;
   if (mode === 'symbol') result.indexHint = indexHintUsed;
   if (validBudget && effectiveMode !== mode) {
     result.chosenMode = effectiveMode;

package/src/tools/smart-search.js

@@ -12,7 +12,6 @@ import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
 import { IGNORED_DIRS, IGNORED_FILE_NAMES, IGNORED_FILE_PATTERNS } from '../config/ignored-paths.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
 import { createProgressReporter } from '../streaming.js';
 import { ensureIndexReady } from '../index-manager.js';
 
@@ -325,16 +324,20 @@ const buildZeroResultsMessage = (query, searchMode, provenance) => {
   return lines.join('\n');
 };
 
-const buildCompactResult = (groups, totalMatches, query, root, searchMode, provenance) => {
+const MAX_RESULT_FILES = 15;
+
+const buildCompactResult = (groups, totalMatches, query, root, searchMode, provenance, totalFiles) => {
   if (totalMatches === 0) {
     return buildZeroResultsMessage(query, searchMode, provenance);
   }
 
   const modeLabel = searchMode === 'exact' ? '' : searchMode === 'regex' ? ' [regex fallback]' : ` [term expansion: ${(provenance?.expandedTerms ?? []).join(', ')}]`;
 
+  const topGroups = groups.slice(0, MAX_RESULT_FILES);
+
   if (totalMatches <= 20) {
     const header = modeLabel ? `# Search mode:${modeLabel}\n\n` : '';
-    return header + groups
+    return header + topGroups
       .flatMap((group) => group.matches)
       .map(formatMatch)
       .join('\n');
@@ -342,29 +345,34 @@ const buildCompactResult = (groups, totalMatches, query, root, searchMode, prove
 
   const lines = [
     `query: ${query}${modeLabel}`,
-    `root: ${root}`,
-    `total matches: ${totalMatches}`,
-    `matched files: ${groups.length}`,
+    `total: ${totalMatches} matches in ${totalFiles ?? groups.length} files${totalFiles && totalFiles > groups.length ? ` (showing top ${groups.length})` : ''}`,
     '',
     '# Top files',
   ];
 
-  for (const group of groups.slice(0, 10)) {
+  for (const group of topGroups.slice(0, 10)) {
     lines.push(`${group.count} match(es), score ${group.score} :: ${group.file}`);
   }
 
   lines.push('', '# Sample matches');
 
-  for (const group of groups.slice(0, 5)) {
-    for (const match of group.matches.slice(0, 3)) {
+  const topScore = topGroups[0]?.score ?? 0;
+  for (const group of topGroups.slice(0, 5)) {
+    const linesPerFile = group.score >= topScore * 0.7 ? 5 : 2;
+    for (const match of group.matches.slice(0, linesPerFile)) {
       lines.push(formatMatch(match));
     }
   }
 
+  const fileCount = totalFiles ?? groups.length;
+  if (fileCount > 30) {
+    lines.push('', `# Note: ${fileCount} files matched — query may be too broad. Use Grep for exact pattern matching.`);
+  }
+
   return lines.join('\n');
 };
 
-export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = false, progress: enableProgress = false }) => {
+export const smartSearch = async ({ query, cwd = '.', intent, maxFiles, _testForceWalk = false, progress: enableProgress = false }) => {
   const progress = enableProgress ? createProgressReporter('smart_search') : null;
   const startTime = Date.now();
   
@@ -464,8 +472,11 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
     }
   }
 
+  const effectiveMaxFiles = maxFiles ?? MAX_RESULT_FILES;
+  const cappedGroups = groups.slice(0, effectiveMaxFiles);
+
   const rawText = dedupedMatches.map(formatMatch).join('\n');
-  const compressedText = truncate(buildCompactResult(groups, dedupedMatches.length, query, root, searchMode, provenance), 5000);
+  const compressedText = truncate(buildCompactResult(cappedGroups, dedupedMatches.length, query, root, searchMode, provenance, groups.length), 5000);
   const metrics = buildMetrics({
     tool: 'smart_search',
     target: `${root} :: ${query}`,
@@ -506,16 +517,6 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
   else if (usedFallback) retrievalConfidence = provenance?.skippedItemsTotal > 0 ? 'low' : 'medium';
   else if (provenance?.skippedItemsTotal > 0) retrievalConfidence = 'low';
 
-  const confidence = { level: retrievalConfidence, indexFreshness };
-
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_search',
-    target: query,
-    metrics,
-    startTime: enableProgress ? startTime : null,
-    filesCount: groups.length,
-  });
-
   if (progress) {
     progress.complete({
       query,
@@ -528,23 +529,17 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
 
   const result = {
     query,
-    root,
-    engine,
-    retrievalConfidence,
     indexFreshness,
-    sourceBreakdown: breakdown,
-    confidence,
     ...(validIntent ? { intent: validIntent } : {}),
     ...(indexHits ? { indexBoosted: indexHits.size } : {}),
     totalMatches: dedupedMatches.length,
     matchedFiles: groups.length,
-    topFiles: groups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
+    topFiles: cappedGroups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
     matches: compressedText,
-    metrics,
-    metricsDisplay,
   };
 
-  if (provenance) result.provenance = provenance;
+  if (provenance?.fallbackReason) result.searchMode = provenance.fallbackReason;
+  if (retrievalConfidence !== 'high') result.retrievalConfidence = retrievalConfidence;
 
   return result;
 };

package/src/tools/smart-shell.js

@@ -7,10 +7,13 @@ import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
-
 const execFile = promisify(execFileCallback);
 const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
+const DEFAULT_TIMEOUT_MS = 15000;
+const getTimeoutMs = () => {
+  const env = parseInt(process.env.DEVCTX_SHELL_TIMEOUT_MS, 10);
+  return Number.isFinite(env) && env > 0 ? env : DEFAULT_TIMEOUT_MS;
+};
 const allowedCommands = new Set(['pwd', 'ls', 'find', 'rg', 'git', 'npm', 'pnpm', 'yarn', 'bun']);
 const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse', 'blame']);
 const allowedPackageManagerSubcommands = new Set(['test', 'run', 'lint', 'build', 'typecheck', 'check']);
@@ -237,8 +240,6 @@ const buildBlockedResult = async (command, message) => {
     exitCode: 126,
     blocked: true,
     output: message,
-    confidence: { blocked: true, timedOut: false },
-    metrics,
   };
 };
 
@@ -273,16 +274,17 @@ export const smartShell = async ({ command }) => {
   }
 
   const resolvedFile = file === 'rg' ? rgPath : file;
+  const timeoutMs = getTimeoutMs();
   const execution = await execFile(resolvedFile, args, {
     cwd: projectRoot,
     maxBuffer: 1024 * 1024 * 10,
-    timeout: 15000,
+    timeout: timeoutMs,
   }).then(
     ({ stdout, stderr }) => ({ stdout, stderr, code: 0 }),
     (error) => ({
       stdout: error.stdout ?? '',
       stderr: error.killed
-        ? `Command timed out after 15s: ${command}`
+        ? `Command timed out after ${timeoutMs / 1000}s: ${command}`
         : (error.stderr ?? error.message ?? ''),
       code: Number.isInteger(error.code) ? error.code : 1,
       timedOut: !!error.killed,
@@ -331,24 +333,13 @@ export const smartShell = async ({ command }) => {
     context: `${outputLines} lines → ${compressedText.split('\n').length} lines (relevant only)`,
   });
 
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_shell',
-    target: command,
-    metrics,
-    startTime: null,
-  });
-
   const result = {
     command,
     exitCode: execution.code,
     blocked: false,
     output: compressedText,
-    confidence: { blocked: false, timedOut: !!execution.timedOut },
-    metrics,
-    metricsDisplay,
+    ...(execution.timedOut ? { timedOut: true } : {}),
   };
 
-  if (execution.timedOut) result.timedOut = true;
-
   return result;
 };

package/src/tools/smart-turn.js

@@ -13,6 +13,9 @@ import { smartContext } from './smart-context.js';
 import { smartMetrics } from './smart-metrics.js';
 import { smartSummary } from './smart-summary.js';
 
+const isStorageUnhealthy = (health) =>
+  health && health.status !== 'ok' && health.status !== null && health.status !== undefined;
+
 const DEFAULT_START_MAX_TOKENS = 400;
 const DEFAULT_END_MAX_TOKENS = 500;
 const DEFAULT_END_EVENT = 'milestone';
@@ -129,10 +132,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
       state: 'resume',
       shouldReuseContext: true,
       reason: 'A persisted session was found and no prompt terms were available for comparison.',
-      sharedTerms: [],
-      promptTermCount: 0,
-      summaryTermCount: 0,
-      matchScore: 1,
     };
   }
 
@@ -147,10 +146,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
       state: 'aligned',
       shouldReuseContext: true,
       reason: 'Prompt terms align with persisted task context.',
-      sharedTerms: sharedTerms.slice(0, 8),
-      promptTermCount: promptTerms.length,
-      summaryTermCount: summaryTerms.length,
-      matchScore,
     };
   }
 
@@ -159,10 +154,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
       state: 'possible_shift',
       shouldReuseContext: true,
       reason: 'Prompt partially overlaps the persisted context; review before continuing.',
-      sharedTerms: sharedTerms.slice(0, 8),
-      promptTermCount: promptTerms.length,
-      summaryTermCount: summaryTerms.length,
-      matchScore,
     };
   }
 
@@ -170,10 +161,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
     state: 'context_mismatch',
     shouldReuseContext: false,
     reason: 'Prompt terms do not align with the persisted session summary.',
-    sharedTerms: [],
-    promptTermCount: promptTerms.length,
-    summaryTermCount: summaryTerms.length,
-    matchScore,
   };
 };
 
@@ -342,7 +329,7 @@ const buildStartRecommendedPath = ({
     autoCreated,
     isolatedSession,
     nextTools: [...new Set(nextTools)],
-    steps,
+    instructions: steps.map((s) => `${s.tool}: ${s.instruction}`).join(' | '),
   };
 };
 
@@ -389,7 +376,7 @@ const buildEndRecommendedPath = ({ event, checkpoint, mutationSafety, workflow }
         : 'checkpointed',
     checkpointEvent: event,
     nextTools: [...new Set(nextTools)],
-    steps,
+    instructions: steps.map((s) => `${s.tool}: ${s.instruction}`).join(' | '),
   };
 };
 
@@ -579,7 +566,7 @@ const startTurn = async ({
     ...(summaryResult.candidates ? { candidates: summaryResult.candidates } : {}),
     ...(summaryResult.recommendedSessionId ? { recommendedSessionId: summaryResult.recommendedSessionId } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
-    storageHealth: summaryResult.storageHealth ?? metrics?.storageHealth ?? null,
+    ...(isStorageUnhealthy(summaryResult.storageHealth ?? metrics?.storageHealth) ? { storageHealth: summaryResult.storageHealth ?? metrics?.storageHealth } : {}),
     recommendedPath,
     message: mutationSafety?.blocked
       ? mutationSafety.message
@@ -694,7 +681,7 @@ const endTurn = async ({
     checkpoint,
     ...(workflow ? { workflow } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
-    storageHealth: checkpoint.storageHealth ?? metrics?.storageHealth ?? null,
+    ...(isStorageUnhealthy(checkpoint.storageHealth ?? metrics?.storageHealth) ? { storageHealth: checkpoint.storageHealth ?? metrics?.storageHealth } : {}),
     recommendedPath,
     message: mutationSafety?.blocked ? mutationSafety.message : checkpoint.message,
   }, {

package/src/utils/mutation-safety.js

@@ -77,9 +77,9 @@ export const attachSafetyMetadata = (
 
   return {
     ...result,
-    ...(mutationSafety ? { mutationSafety } : {}),
-    repoSafety,
-    sideEffectsSuppressed: Boolean(sideEffectsSuppressed),
+    ...(mutationSafety?.blocked ? { mutationSafety } : {}),
+    ...(repoSafety && (mutationSafety?.blocked || sideEffectsSuppressed) ? { repoSafety } : {}),
+    ...(sideEffectsSuppressed ? { sideEffectsSuppressed: true } : {}),
     ...(degraded ? { degradedMode: degraded } : {}),
   };
 };

package/src/utils/text.js

@@ -8,6 +8,7 @@ export const truncate = (text = '', maxChars = 4000) => {
 
 export const uniqueLines = (text = '') => {
   const seen = new Set();
+  let prevEmpty = false;
 
   return text
     .split('\n')
@@ -15,9 +16,13 @@ export const uniqueLines = (text = '') => {
       const key = line.trim();
 
       if (!key) {
+        if (prevEmpty) return false;
+        prevEmpty = true;
         return true;
       }
 
+      prevEmpty = false;
+
       if (seen.has(key)) {
         return false;
       }