openlore 2.0.7 → 2.0.8

package/dist/cli/commands/mcp.js

@@ -22,14 +22,20 @@ const _pkgVersion = _require('../../../package.json').version;
 import { Command } from 'commander';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, McpError, ErrorCode, LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, } from '@modelcontextprotocol/sdk/types.js';
+import { validateToolArgs, withToolTimeout, capOutput, classifyToolError, } from '../../core/services/mcp-handlers/tool-guard.js';
 import { sanitizeMcpError, validateDirectory } from '../../core/services/mcp-handlers/utils.js';
 import { createTracker, updateTracker, getFreshnessSignal } from '../../core/services/mcp-handlers/epistemic-lease.js';
 import { emit } from '../../core/services/telemetry.js';
-import { DEFAULT_DRIFT_MAX_FILES } from '../../constants.js';
+import { DEFAULT_DRIFT_MAX_FILES, MCP_TOOL_MAX_BYTES } from '../../constants.js';
 import { handleGetCallGraph, handleGetSubgraph, handleAnalyzeImpact, handleGetLowRiskRefactorCandidates, handleGetLeafFunctions, handleGetCriticalHubs, handleGetGodFunctions, handleGetFileDependencies, handleTraceExecutionPath, } from '../../core/services/mcp-handlers/graph.js';
 import { handleSearchCode, handleSuggestInsertionPoints, handleSearchSpecs, handleListSpecDomains, handleGetSpec, handleUnifiedSearch, } from '../../core/services/mcp-handlers/semantic.js';
 import { handleOrient } from '../../core/services/mcp-handlers/orient.js';
+import { handleSelectTests } from '../../core/services/mcp-handlers/test-impact.js';
+import { handleFindDeadCode } from '../../core/services/mcp-handlers/reachability.js';
+import { handleStructuralDiff } from '../../core/services/mcp-handlers/structural-diff.js';
+import { handleGetChangeCoupling } from '../../core/services/mcp-handlers/change-coupling.js';
+import { handleCheckArchitecture } from '../../core/services/mcp-handlers/architecture.js';
 import { handleGenerateChangeProposal, handleAnnotateStory } from '../../core/services/mcp-handlers/change.js';
 import { handleRecordDecision, handleListDecisions, handleApproveDecision, handleRejectDecision, handleSyncDecisions, } from '../../core/services/mcp-handlers/decisions.js';
 import { handleAnalyzeCodebase, handleGetArchitectureOverview, handleGetRefactorReport, handleGetDuplicateReport, handleGetSignatures, handleGetMapping, handleCheckSpecDrift, handleGetFunctionSkeleton, handleGetFunctionBody, handleGetDecisions, handleGetRouteInventory, handleGetMiddlewareInventory, handleGetSchemaInventory, handleGetUIComponents, handleGetEnvVars, handleGetExternalPackages, handleAuditSpecCoverage, handleGenerateTests, handleGetTestCoverage, handleGetMinimalContext, handleGetCluster, handleDetectChanges, } from '../../core/services/mcp-handlers/analysis.js';
@@ -339,6 +345,107 @@ export const TOOL_DEFINITIONS = [
             required: ['directory', 'symbol'],
         },
     },
+    {
+        name: 'select_tests',
+        description: 'USE THIS WHEN: you changed code and want to know which tests to run — ' +
+            '"which tests cover parseConfig?", "what should I run for this diff?". ' +
+            'Walks the call graph BACKWARD from the change to every test that transitively reaches it, ' +
+            'with the reaching path per test. Deterministic, offline, no test run. ' +
+            'It is an over-approximate PRIORITIZER (run these first), not a sound replacement for the full ' +
+            'suite — the response states its confidence and coverage. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                changedSymbols: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Changed function/method names. Provide this OR diffRef.',
+                },
+                diffRef: {
+                    type: 'string',
+                    description: 'Git ref to diff the working tree against (e.g. "HEAD", "main"). Provide this OR changedSymbols.',
+                },
+                maxDepth: { type: 'number', description: 'Backward reachability depth (default 12)' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'find_dead_code',
+        description: 'USE THIS WHEN: "what code is unreachable / dead?", "is anything calling X?", or ' +
+            '"what becomes dead if I delete X?". Cross-language mark-and-sweep reachability from roots ' +
+            '(tests, imported symbols, route handlers, main) over the call graph. ' +
+            'Pass ifDeleted to get the downstream-only-reachable set for a symbol. ' +
+            'Results are confidence-tagged CANDIDATES, never deletion authority — dynamic dispatch, DI, ' +
+            'and external consumers cause false positives, stated in the response. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                ifDeleted: { type: 'string', description: 'Symbol name — returns what becomes dead if it is deleted (delete-impact mode)' },
+                maxResults: { type: 'number', description: 'Max candidate-dead results (default 100)' },
+                filePattern: { type: 'string', description: 'Only report candidates whose file path contains this substring' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'structural_diff',
+        description: 'USE THIS WHEN reviewing or refactoring a change: "what changed structurally?", ' +
+            '"whose callers are now stale?". A graph diff (complement to git diff) between two states ' +
+            '(working tree vs a ref, or two refs): functions/edges added & removed, signature changes, ' +
+            'and the existing callers now STALE because a callee signature moved under them. ' +
+            'Rename/move ambiguity is flagged, not guessed. Deterministic, offline. Run analyze_codebase ' +
+            'first for stale-caller analysis.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                baseRef: { type: 'string', description: 'Old state to diff against (default "HEAD")' },
+                headRef: { type: 'string', description: 'New state (a git ref). Omit to use the working tree.' },
+                maxResults: { type: 'number', description: 'Cap reported items per category (default 200)' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'get_change_coupling',
+        description: 'USE THIS WHEN: "what changes together with this file?" or "what is the most volatile code?". ' +
+            'Mined from local git history (not the call graph): co-change coupling surfaces invisible ' +
+            'coupling with no import/call edge (the config + parser that move in lockstep), and ' +
+            'volatility/churn flags risky high-change code. Pass a file for its coupling, or omit for the ' +
+            'most-volatile overview. Advisory signal (correlation, not causation); bulk commits filtered. ' +
+            'Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                file: { type: 'string', description: 'A file to query its coupling/volatility. Omit for the most-volatile overview.' },
+                limit: { type: 'number', description: 'Cap results (default 20)' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'check_architecture',
+        description: 'USE THIS BEFORE adding an import to check it against the repo\'s architecture rules, or to ' +
+            'list current architecture violations. Opt-in and inert unless the repo declares rules in ' +
+            '.openlore/architecture.json (layers / forbidden / allowedOnly) or via an "Invariant:" marker ' +
+            'in a synced ADR. Pre-edit mode: pass {from, to} ("may a file under <from> import <to>?") for a ' +
+            'deterministic allowed/denied + the governing rule + why, BEFORE you write the code. Scan mode: ' +
+            'pass only {directory} for the full current-violations report. Cross-language, offline, ' +
+            'deterministic; complements (does not replace) CI linters. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                from: { type: 'string', description: 'Pre-edit mode: the file that would gain the import (relative or absolute). Requires "to".' },
+                to: { type: 'string', description: 'Pre-edit mode: the target file path or exported symbol being imported. Requires "from".' },
+            },
+            required: ['directory'],
+        },
+    },
     {
         name: 'get_low_risk_refactor_candidates',
         description: 'Return the safest functions to refactor first: low fan-in (few callers), ' +
@@ -1116,7 +1223,7 @@ const TOOL_ANNOTATIONS = {
     orient: _RO, analyze_codebase: _RWI, get_architecture_overview: _RO,
     get_refactor_report: _RO, get_call_graph: _RO, get_duplicate_report: _RO,
     get_signatures: _RO, get_subgraph: _RO, trace_execution_path: _RO,
-    get_mapping: _RO, check_spec_drift: _RO, analyze_impact: _RO,
+    get_mapping: _RO, check_spec_drift: _RO, analyze_impact: _RO, select_tests: _RO, find_dead_code: _RO, structural_diff: _RO, get_change_coupling: _RO, check_architecture: _RO,
     get_low_risk_refactor_candidates: _RO, get_leaf_functions: _RO,
     get_critical_hubs: _RO, get_function_skeleton: _RO, get_god_functions: _RO,
     suggest_insertion_points: _RO, search_code: _RO, list_spec_domains: _RO,
@@ -1129,6 +1236,21 @@ const TOOL_ANNOTATIONS = {
     detect_changes: _RO, record_decision: _RW, list_decisions: _RO,
     approve_decision: _RWI, reject_decision: _RWI, sync_decisions: _RWI,
 };
+// Tools that touch external entities (LLM / network) → openWorldHint: true.
+// Everything else is local, deterministic, closed-world analysis.
+const OPEN_WORLD_TOOLS = new Set(['generate_tests', 'generate_change_proposal', 'annotate_story']);
+/** Human-readable title from a snake_case tool name (spec-11 annotations). */
+function toolTitle(name) {
+    return name.split('_').map(w => (w ? w[0].toUpperCase() + w.slice(1) : w)).join(' ');
+}
+/** Full MCP `annotations` for a tool: read/write hints + title + openWorldHint (spec-11). */
+export function toolAnnotations(name) {
+    return {
+        title: toolTitle(name),
+        ...(TOOL_ANNOTATIONS[name] ?? _RO),
+        openWorldHint: OPEN_WORLD_TOOLS.has(name),
+    };
+}
 const MINIMAL_TOOLS = new Set([
     'orient', 'search_code', 'record_decision', 'detect_changes', 'check_spec_drift',
 ]);
@@ -1184,7 +1306,7 @@ async function startMcpServer(options = {}) {
     const { version: pkgVersion } = _require('../../../package.json');
     const server = new Server({ name: 'openlore', version: pkgVersion }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: activeTools.map(t => ({ ...t, annotations: TOOL_ANNOTATIONS[t.name] })),
+        tools: activeTools.map(t => ({ ...t, annotations: toolAnnotations(t.name) })),
     }));
     // Per-session epistemic lease tracker — re-initialized when directory changes.
     let tracker;
@@ -1197,8 +1319,16 @@ async function startMcpServer(options = {}) {
     server.setRequestHandler(InitializeRequestSchema, async (request) => {
         agentName = request.params.clientInfo?.name ?? 'unknown';
         agentVersion = request.params.clientInfo?.version ?? 'unknown';
+        // Protocol negotiation (spec-12): echo the client's requested version when we
+        // support it (per the SDK's pinned set), else offer our latest supported one.
+        const requested = request.params.protocolVersion;
+        const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+            ? requested
+            : LATEST_PROTOCOL_VERSION;
         return {
-            protocolVersion: request.params.protocolVersion,
+            protocolVersion,
+            // Honest capabilities: only `tools`. No `listChanged` — the tool list is
+            // static per session, so we don't advertise a capability we don't implement.
             capabilities: { tools: {} },
             serverInfo: { name: 'openlore', version: _pkgVersion },
         };
@@ -1225,6 +1355,17 @@ async function startMcpServer(options = {}) {
         const _dir = args.directory;
         const directory = typeof _dir === 'string' ? _dir : '';
         const _t0 = Date.now();
+        // Input validation (spec-10) against the tool's own declared inputSchema, before
+        // dispatch. Invalid args become a JSON-RPC -32602 error (spec-12), not an
+        // isError tool result — a malformed request is a protocol error, not a tool failure.
+        {
+            const toolDef = TOOL_DEFINITIONS.find(t => t.name === name);
+            const argError = toolDef ? validateToolArgs(args, toolDef.inputSchema) : null;
+            if (argError) {
+                emit(directory, 'mcp', { event: 'tool_error', tool: name, ms: Date.now() - _t0, agent: agentName, code: 'INVALID_ARGS', error: argError });
+                throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for "${name}": ${argError}`);
+            }
+        }
         try {
             const filePath = args.filePath;
             // Init (or re-init when project directory changes between calls)
@@ -1236,205 +1377,240 @@ async function startMcpServer(options = {}) {
             if (tracker && directory)
                 updateTracker(tracker, name, directory, typeof filePath === 'string' ? filePath : undefined);
             let result;
-            if (name === 'orient') {
-                const { task, limit = 5 } = args;
-                result = await handleOrient(directory, task, limit);
-                if (result && typeof result === 'object') {
-                    const r = result;
-                    emit(directory, 'orient', {
-                        event: 'orient_call',
-                        agent: agentName,
-                        functions: Array.isArray(r['relevantFunctions']) ? r['relevantFunctions'].length : 0,
-                        files: Array.isArray(r['relevantFiles']) ? r['relevantFiles'].length : 0,
-                        spec_domains: Array.isArray(r['specDomains']) ? r['specDomains'].length : 0,
-                        insertion_points: Array.isArray(r['insertionPoints']) ? r['insertionPoints'].length : 0,
-                    });
+            let _unknownTool = false;
+            // Per-tool timeout (spec-10): race the dispatch against the tool's budget so a
+            // pathological hang can never wedge the server. Slow tools (analysis, LLM) have
+            // generous overrides in MCP_TOOL_TIMEOUT_OVERRIDES.
+            await withToolTimeout((async () => {
+                if (name === 'orient') {
+                    const { task, limit = 5 } = args;
+                    result = await handleOrient(directory, task, limit);
+                    if (result && typeof result === 'object') {
+                        const r = result;
+                        emit(directory, 'orient', {
+                            event: 'orient_call',
+                            agent: agentName,
+                            functions: Array.isArray(r['relevantFunctions']) ? r['relevantFunctions'].length : 0,
+                            files: Array.isArray(r['relevantFiles']) ? r['relevantFiles'].length : 0,
+                            spec_domains: Array.isArray(r['specDomains']) ? r['specDomains'].length : 0,
+                            insertion_points: Array.isArray(r['insertionPoints']) ? r['insertionPoints'].length : 0,
+                        });
+                    }
                 }
-            }
-            else if (name === 'analyze_codebase') {
-                const { directory, force = false } = args;
-                result = await handleAnalyzeCodebase(directory, force);
-            }
-            else if (name === 'get_architecture_overview') {
-                const { directory } = args;
-                result = await handleGetArchitectureOverview(directory);
-            }
-            else if (name === 'get_refactor_report') {
-                const { directory } = args;
-                result = await handleGetRefactorReport(directory);
-            }
-            else if (name === 'get_call_graph') {
-                const { directory } = args;
-                result = await handleGetCallGraph(directory);
-            }
-            else if (name === 'get_signatures') {
-                const { directory, filePattern } = args;
-                result = await handleGetSignatures(directory, filePattern);
-            }
-            else if (name === 'get_subgraph') {
-                const { directory, functionName, direction = 'downstream', maxDepth = 3, format = 'json' } = args;
-                result = await handleGetSubgraph(directory, functionName, direction, maxDepth, format);
-            }
-            else if (name === 'trace_execution_path') {
-                const { directory, entryFunction, targetFunction, maxDepth = 6, maxPaths = 10 } = args;
-                result = await handleTraceExecutionPath(directory, entryFunction, targetFunction, maxDepth, maxPaths);
-            }
-            else if (name === 'get_mapping') {
-                const { directory, domain, orphansOnly } = args;
-                result = await handleGetMapping(directory, domain, orphansOnly);
-            }
-            else if (name === 'analyze_impact') {
-                const { directory, symbol, depth = 2 } = args;
-                result = await handleAnalyzeImpact(directory, symbol, depth);
-            }
-            else if (name === 'get_low_risk_refactor_candidates') {
-                const { directory, limit = 5, filePattern } = args;
-                result = await handleGetLowRiskRefactorCandidates(directory, limit, filePattern);
-            }
-            else if (name === 'get_leaf_functions') {
-                const { directory, limit = 20, filePattern, sortBy = 'fanIn' } = args;
-                result = await handleGetLeafFunctions(directory, limit, filePattern, sortBy);
-            }
-            else if (name === 'get_critical_hubs') {
-                const { directory, limit = 10, minFanIn = 3 } = args;
-                result = await handleGetCriticalHubs(directory, limit, minFanIn);
-            }
-            else if (name === 'get_duplicate_report') {
-                const { directory } = args;
-                result = await handleGetDuplicateReport(directory);
-            }
-            else if (name === 'get_function_skeleton') {
-                const { directory, filePath } = args;
-                result = await handleGetFunctionSkeleton(directory, filePath);
-            }
-            else if (name === 'get_god_functions') {
-                const { directory, filePath, fanOutThreshold = 8 } = args;
-                result = await handleGetGodFunctions(directory, filePath, fanOutThreshold);
-            }
-            else if (name === 'check_spec_drift') {
-                const { directory, base = 'auto', files = [], domains = [], failOn = 'warning', maxFiles = DEFAULT_DRIFT_MAX_FILES } = args;
-                result = await handleCheckSpecDrift(directory, base, files, domains, failOn, maxFiles);
-            }
-            else if (name === 'search_code') {
-                const { directory, query, limit = 10, language, minFanIn } = args;
-                result = await handleSearchCode(directory, query, limit, language, minFanIn);
-            }
-            else if (name === 'suggest_insertion_points') {
-                const { directory, description, limit = 5, language } = args;
-                result = await handleSuggestInsertionPoints(directory, description, limit, language);
-            }
-            else if (name === 'search_specs') {
-                const { directory, query, limit = 10, domain, section } = args;
-                result = await handleSearchSpecs(directory, query, limit, domain, section);
-            }
-            else if (name === 'search_unified') {
-                const { directory, query, limit = 10, language, domain, section } = args;
-                result = await handleUnifiedSearch(directory, query, limit, language, domain, section);
-            }
-            else if (name === 'list_spec_domains') {
-                const { directory } = args;
-                result = await handleListSpecDomains(directory);
-            }
-            else if (name === 'get_spec') {
-                const { directory, domain } = args;
-                result = await handleGetSpec(directory, domain);
-            }
-            else if (name === 'get_function_body') {
-                const { directory, filePath, functionName } = args;
-                result = await handleGetFunctionBody(directory, filePath, functionName);
-            }
-            else if (name === 'get_file_dependencies') {
-                const { directory, filePath, direction = 'both' } = args;
-                result = await handleGetFileDependencies(directory, filePath, direction);
-            }
-            else if (name === 'generate_change_proposal') {
-                const { directory, description, slug, storyContent } = args;
-                result = await handleGenerateChangeProposal(directory, description, slug, storyContent);
-            }
-            else if (name === 'annotate_story') {
-                const { directory, storyFilePath, description } = args;
-                result = await handleAnnotateStory(directory, storyFilePath, description);
-            }
-            else if (name === 'get_decisions') {
-                const { directory, query } = args;
-                result = await handleGetDecisions(directory, query);
-            }
-            else if (name === 'get_route_inventory') {
-                const { directory } = args;
-                result = await handleGetRouteInventory(directory);
-            }
-            else if (name === 'get_middleware_inventory') {
-                const { directory } = args;
-                result = await handleGetMiddlewareInventory(directory);
-            }
-            else if (name === 'get_schema_inventory') {
-                const { directory } = args;
-                result = await handleGetSchemaInventory(directory);
-            }
-            else if (name === 'get_ui_components') {
-                const { directory } = args;
-                result = await handleGetUIComponents(directory);
-            }
-            else if (name === 'get_env_vars') {
-                const { directory } = args;
-                result = await handleGetEnvVars(directory);
-            }
-            else if (name === 'get_external_packages') {
-                const { directory } = args;
-                result = await handleGetExternalPackages(directory);
-            }
-            else if (name === 'audit_spec_coverage') {
-                const { directory, maxUncovered = 50, hubThreshold = 5 } = args;
-                result = await handleAuditSpecCoverage(directory, maxUncovered, hubThreshold);
-            }
-            else if (name === 'generate_tests') {
-                const { directory, domains, framework, useLlm, dryRun } = args;
-                result = await handleGenerateTests({ directory, domains, framework, useLlm, dryRun });
-            }
-            else if (name === 'get_test_coverage') {
-                const { directory, domains, minCoverage } = args;
-                result = await handleGetTestCoverage({ directory, domains, minCoverage });
-            }
-            else if (name === 'get_minimal_context') {
-                const { directory, functionName, filePath } = args;
-                result = await handleGetMinimalContext(directory, functionName, filePath);
-            }
-            else if (name === 'get_cluster') {
-                const { directory, functionName } = args;
-                result = await handleGetCluster(directory, functionName);
-            }
-            else if (name === 'detect_changes') {
-                const { directory, base } = args;
-                result = await handleDetectChanges(directory, base);
-            }
-            else if (name === 'record_decision') {
-                const { directory, title, rationale, consequences, affectedFiles, supersedes, scope } = args;
-                result = await handleRecordDecision(directory, title, rationale, consequences, affectedFiles, supersedes, scope);
-            }
-            else if (name === 'list_decisions') {
-                const { directory, status } = args;
-                result = await handleListDecisions(directory, status);
-            }
-            else if (name === 'approve_decision') {
-                const { directory, id, note } = args;
-                result = await handleApproveDecision(directory, id, note);
-            }
-            else if (name === 'reject_decision') {
-                const { directory, id, note } = args;
-                result = await handleRejectDecision(directory, id, note);
-            }
-            else if (name === 'sync_decisions') {
-                const { directory, dryRun = false, id } = args;
-                result = await handleSyncDecisions(directory, dryRun, id);
-            }
-            else {
+                else if (name === 'analyze_codebase') {
+                    const { directory, force = false } = args;
+                    result = await handleAnalyzeCodebase(directory, force);
+                }
+                else if (name === 'get_architecture_overview') {
+                    const { directory } = args;
+                    result = await handleGetArchitectureOverview(directory);
+                }
+                else if (name === 'get_refactor_report') {
+                    const { directory } = args;
+                    result = await handleGetRefactorReport(directory);
+                }
+                else if (name === 'get_call_graph') {
+                    const { directory } = args;
+                    result = await handleGetCallGraph(directory);
+                }
+                else if (name === 'get_signatures') {
+                    const { directory, filePattern } = args;
+                    result = await handleGetSignatures(directory, filePattern);
+                }
+                else if (name === 'get_subgraph') {
+                    const { directory, functionName, direction = 'downstream', maxDepth = 3, format = 'json' } = args;
+                    result = await handleGetSubgraph(directory, functionName, direction, maxDepth, format);
+                }
+                else if (name === 'trace_execution_path') {
+                    const { directory, entryFunction, targetFunction, maxDepth = 6, maxPaths = 10 } = args;
+                    result = await handleTraceExecutionPath(directory, entryFunction, targetFunction, maxDepth, maxPaths);
+                }
+                else if (name === 'get_mapping') {
+                    const { directory, domain, orphansOnly } = args;
+                    result = await handleGetMapping(directory, domain, orphansOnly);
+                }
+                else if (name === 'analyze_impact') {
+                    const { directory, symbol, depth = 2 } = args;
+                    result = await handleAnalyzeImpact(directory, symbol, depth);
+                }
+                else if (name === 'select_tests') {
+                    const { directory, changedSymbols, diffRef, maxDepth } = args;
+                    result = await handleSelectTests({ directory, changedSymbols, diffRef, maxDepth });
+                }
+                else if (name === 'find_dead_code') {
+                    const { directory, ifDeleted, maxResults, filePattern } = args;
+                    result = await handleFindDeadCode({ directory, ifDeleted, maxResults, filePattern });
+                }
+                else if (name === 'structural_diff') {
+                    const { directory, baseRef, headRef, maxResults } = args;
+                    result = await handleStructuralDiff({ directory, baseRef, headRef, maxResults });
+                }
+                else if (name === 'get_change_coupling') {
+                    const { directory, file, limit } = args;
+                    result = await handleGetChangeCoupling({ directory, file, limit });
+                }
+                else if (name === 'check_architecture') {
+                    const { directory, from, to } = args;
+                    result = await handleCheckArchitecture({ directory, from, to });
+                }
+                else if (name === 'get_low_risk_refactor_candidates') {
+                    const { directory, limit = 5, filePattern } = args;
+                    result = await handleGetLowRiskRefactorCandidates(directory, limit, filePattern);
+                }
+                else if (name === 'get_leaf_functions') {
+                    const { directory, limit = 20, filePattern, sortBy = 'fanIn' } = args;
+                    result = await handleGetLeafFunctions(directory, limit, filePattern, sortBy);
+                }
+                else if (name === 'get_critical_hubs') {
+                    const { directory, limit = 10, minFanIn = 3 } = args;
+                    result = await handleGetCriticalHubs(directory, limit, minFanIn);
+                }
+                else if (name === 'get_duplicate_report') {
+                    const { directory } = args;
+                    result = await handleGetDuplicateReport(directory);
+                }
+                else if (name === 'get_function_skeleton') {
+                    const { directory, filePath } = args;
+                    result = await handleGetFunctionSkeleton(directory, filePath);
+                }
+                else if (name === 'get_god_functions') {
+                    const { directory, filePath, fanOutThreshold = 8 } = args;
+                    result = await handleGetGodFunctions(directory, filePath, fanOutThreshold);
+                }
+                else if (name === 'check_spec_drift') {
+                    const { directory, base = 'auto', files = [], domains = [], failOn = 'warning', maxFiles = DEFAULT_DRIFT_MAX_FILES } = args;
+                    result = await handleCheckSpecDrift(directory, base, files, domains, failOn, maxFiles);
+                }
+                else if (name === 'search_code') {
+                    const { directory, query, limit = 10, language, minFanIn } = args;
+                    result = await handleSearchCode(directory, query, limit, language, minFanIn);
+                }
+                else if (name === 'suggest_insertion_points') {
+                    const { directory, description, limit = 5, language } = args;
+                    result = await handleSuggestInsertionPoints(directory, description, limit, language);
+                }
+                else if (name === 'search_specs') {
+                    const { directory, query, limit = 10, domain, section } = args;
+                    result = await handleSearchSpecs(directory, query, limit, domain, section);
+                }
+                else if (name === 'search_unified') {
+                    const { directory, query, limit = 10, language, domain, section } = args;
+                    result = await handleUnifiedSearch(directory, query, limit, language, domain, section);
+                }
+                else if (name === 'list_spec_domains') {
+                    const { directory } = args;
+                    result = await handleListSpecDomains(directory);
+                }
+                else if (name === 'get_spec') {
+                    const { directory, domain } = args;
+                    result = await handleGetSpec(directory, domain);
+                }
+                else if (name === 'get_function_body') {
+                    const { directory, filePath, functionName } = args;
+                    result = await handleGetFunctionBody(directory, filePath, functionName);
+                }
+                else if (name === 'get_file_dependencies') {
+                    const { directory, filePath, direction = 'both' } = args;
+                    result = await handleGetFileDependencies(directory, filePath, direction);
+                }
+                else if (name === 'generate_change_proposal') {
+                    const { directory, description, slug, storyContent } = args;
+                    result = await handleGenerateChangeProposal(directory, description, slug, storyContent);
+                }
+                else if (name === 'annotate_story') {
+                    const { directory, storyFilePath, description } = args;
+                    result = await handleAnnotateStory(directory, storyFilePath, description);
+                }
+                else if (name === 'get_decisions') {
+                    const { directory, query } = args;
+                    result = await handleGetDecisions(directory, query);
+                }
+                else if (name === 'get_route_inventory') {
+                    const { directory } = args;
+                    result = await handleGetRouteInventory(directory);
+                }
+                else if (name === 'get_middleware_inventory') {
+                    const { directory } = args;
+                    result = await handleGetMiddlewareInventory(directory);
+                }
+                else if (name === 'get_schema_inventory') {
+                    const { directory } = args;
+                    result = await handleGetSchemaInventory(directory);
+                }
+                else if (name === 'get_ui_components') {
+                    const { directory } = args;
+                    result = await handleGetUIComponents(directory);
+                }
+                else if (name === 'get_env_vars') {
+                    const { directory } = args;
+                    result = await handleGetEnvVars(directory);
+                }
+                else if (name === 'get_external_packages') {
+                    const { directory } = args;
+                    result = await handleGetExternalPackages(directory);
+                }
+                else if (name === 'audit_spec_coverage') {
+                    const { directory, maxUncovered = 50, hubThreshold = 5 } = args;
+                    result = await handleAuditSpecCoverage(directory, maxUncovered, hubThreshold);
+                }
+                else if (name === 'generate_tests') {
+                    const { directory, domains, framework, useLlm, dryRun } = args;
+                    result = await handleGenerateTests({ directory, domains, framework, useLlm, dryRun });
+                }
+                else if (name === 'get_test_coverage') {
+                    const { directory, domains, minCoverage } = args;
+                    result = await handleGetTestCoverage({ directory, domains, minCoverage });
+                }
+                else if (name === 'get_minimal_context') {
+                    const { directory, functionName, filePath } = args;
+                    result = await handleGetMinimalContext(directory, functionName, filePath);
+                }
+                else if (name === 'get_cluster') {
+                    const { directory, functionName } = args;
+                    result = await handleGetCluster(directory, functionName);
+                }
+                else if (name === 'detect_changes') {
+                    const { directory, base } = args;
+                    result = await handleDetectChanges(directory, base);
+                }
+                else if (name === 'record_decision') {
+                    const { directory, title, rationale, consequences, affectedFiles, supersedes, scope } = args;
+                    result = await handleRecordDecision(directory, title, rationale, consequences, affectedFiles, supersedes, scope);
+                }
+                else if (name === 'list_decisions') {
+                    const { directory, status } = args;
+                    result = await handleListDecisions(directory, status);
+                }
+                else if (name === 'approve_decision') {
+                    const { directory, id, note } = args;
+                    result = await handleApproveDecision(directory, id, note);
+                }
+                else if (name === 'reject_decision') {
+                    const { directory, id, note } = args;
+                    result = await handleRejectDecision(directory, id, note);
+                }
+                else if (name === 'sync_decisions') {
+                    const { directory, dryRun = false, id } = args;
+                    result = await handleSyncDecisions(directory, dryRun, id);
+                }
+                else {
+                    _unknownTool = true;
+                }
+            })(), name);
+            if (_unknownTool) {
                 return {
                     content: [{ type: 'text', text: `Unknown tool: ${name}` }],
                     isError: true,
                 };
             }
-            emit(directory, 'mcp', { event: 'tool_call', tool: name, ms: Date.now() - _t0, agent: agentName, agent_version: agentVersion });
-            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            const rawText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            // Output cap (spec-10): truncate deterministically with a how-to-narrow note
+            // rather than silently dropping data or blowing the agent's context.
+            const { text, truncated } = capOutput(rawText, MCP_TOOL_MAX_BYTES);
+            emit(directory, 'mcp', {
+                event: 'tool_call', tool: name, ms: Date.now() - _t0, agent: agentName, agent_version: agentVersion,
+                bytes: Buffer.byteLength(text, 'utf8'), outcome: truncated ? 'truncated' : 'ok',
+            });
             const signal = tracker ? getFreshnessSignal(tracker) : null;
             // Freshness signal is a separate content item — never concatenated into
             // the result body — so structured outputs (JSON, patches) are not corrupted.
@@ -1446,9 +1622,17 @@ async function startMcpServer(options = {}) {
             return { content };
         }
         catch (err) {
-            emit(directory, 'mcp', { event: 'tool_error', tool: name, ms: Date.now() - _t0, agent: agentName, error: sanitizeMcpError(err) });
+            // A thrown McpError is a protocol-level error (e.g. -32602) — let the SDK
+            // serialize it as a JSON-RPC error response, not a tool isError result.
+            if (err instanceof McpError)
+                throw err;
+            // Error normalization (spec-10): a stable code taxonomy, distinguishing
+            // "repo not analyzed yet" (actionable) from real failures and timeouts.
+            const code = classifyToolError(err);
+            const message = sanitizeMcpError(err);
+            emit(directory, 'mcp', { event: 'tool_error', tool: name, ms: Date.now() - _t0, agent: agentName, code, outcome: 'error', error: message });
             return {
-                content: [{ type: 'text', text: `Tool error: ${sanitizeMcpError(err)}` }],
+                content: [{ type: 'text', text: `Tool error [${code}]: ${message}` }],
                 isError: true,
             };
         }