@bryan-thompson/inspector-assessment-client 1.27.0 → 1.29.0

package/lib/services/assessment/modules/annotations/AlignmentChecker.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Alignment Checker Module
+ * Handles tool annotation alignment detection, extraction, and metrics calculation
+ *
+ * Extracted from ToolAnnotationAssessor.ts as part of Issue #105 refactoring.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ToolAnnotationResult, AssessmentStatus, ToolParamProgress, AnnotationSource } from "../../../../lib/assessmentTypes.js";
+import type { CompiledPatterns, ServerPersistenceContext } from "../../config/annotationPatterns.js";
+/**
+ * Extracted annotation structure from a tool
+ */
+export interface ExtractedAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    title?: string;
+    description?: string;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    source: AnnotationSource;
+}
+/**
+ * Alignment metrics result
+ */
+export interface AlignmentMetricsResult {
+    metrics: {
+        coverage: number;
+        consistency: number;
+        correctness: number;
+        reviewRequired: number;
+    };
+    alignmentBreakdown: {
+        aligned: number;
+        misaligned: number;
+        reviewRecommended: number;
+        unknown: number;
+    };
+}
+/**
+ * Extract annotations from a tool
+ * Checks multiple sources in priority order: annotations object, direct properties, metadata
+ */
+export declare function extractAnnotations(tool: Tool): ExtractedAnnotations;
+/**
+ * Extract extended metadata from tool (Issue #54)
+ * Extracts rate limits, permissions, return schemas, and bulk operation support
+ */
+export declare function extractExtendedMetadata(tool: Tool): ToolAnnotationResult["extendedMetadata"];
+/**
+ * Extract parameters from tool input schema
+ */
+export declare function extractToolParams(schema: unknown): ToolParamProgress[];
+/**
+ * Assess a single tool's annotations
+ */
+export declare function assessSingleTool(tool: Tool, compiledPatterns: CompiledPatterns, persistenceContext?: ServerPersistenceContext): ToolAnnotationResult;
+/**
+ * Determine overall status based on tool results
+ */
+export declare function determineAnnotationStatus(results: ToolAnnotationResult[], totalTools: number): AssessmentStatus;
+/**
+ * Calculate metrics and alignment breakdown
+ */
+export declare function calculateMetrics(results: ToolAnnotationResult[], totalTools: number): AlignmentMetricsResult;
+//# sourceMappingURL=AlignmentChecker.d.ts.map

package/lib/services/assessment/modules/annotations/AlignmentChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlignmentChecker.d.ts","sourceRoot":"","sources":["../../../../../src/services/assessment/modules/annotations/AlignmentChecker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EAEhB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,iCAAiC,CAAC;AAsEzC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,kBAAkB,EAAE;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,oBAAoB,CA8DnE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,GACT,oBAAoB,CAAC,kBAAkB,CAAC,CA6D1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,EAAE,CAqBtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,gBAAgB,EAAE,gBAAgB,EAClC,kBAAkB,CAAC,EAAE,wBAAwB,GAC5C,oBAAoB,CAkItB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,oBAAoB,EAAE,EAC/B,UAAU,EAAE,MAAM,GACjB,gBAAgB,CA8BlB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,oBAAoB,EAAE,EAC/B,UAAU,EAAE,MAAM,GACjB,sBAAsB,CA2BxB"}

package/lib/services/assessment/modules/annotations/AlignmentChecker.js

@@ -0,0 +1,289 @@
+/**
+ * Alignment Checker Module
+ * Handles tool annotation alignment detection, extraction, and metrics calculation
+ *
+ * Extracted from ToolAnnotationAssessor.ts as part of Issue #105 refactoring.
+ */
+import { scanDescriptionForPoisoning } from "./DescriptionPoisoningDetector.js";
+import { detectAnnotationDeception, isActionableConfidence, } from "./AnnotationDeceptionDetector.js";
+import { inferBehavior } from "./BehaviorInference.js";
+/**
+ * Extract annotations from a tool
+ * Checks multiple sources in priority order: annotations object, direct properties, metadata
+ */
+export function extractAnnotations(tool) {
+    const extendedTool = tool;
+    // Priority 1: Check annotations object (MCP 2024-11 spec)
+    if (extendedTool.annotations) {
+        const hasAnnotations = extendedTool.annotations.readOnlyHint !== undefined ||
+            extendedTool.annotations.destructiveHint !== undefined;
+        if (hasAnnotations) {
+            return {
+                readOnlyHint: extendedTool.annotations.readOnlyHint,
+                destructiveHint: extendedTool.annotations.destructiveHint,
+                title: extendedTool.annotations.title || extendedTool.title,
+                description: tool.description,
+                idempotentHint: extendedTool.annotations.idempotentHint,
+                openWorldHint: extendedTool.annotations.openWorldHint,
+                source: "mcp",
+            };
+        }
+    }
+    // Priority 2: Check direct properties
+    if (extendedTool.readOnlyHint !== undefined ||
+        extendedTool.destructiveHint !== undefined) {
+        return {
+            readOnlyHint: extendedTool.readOnlyHint,
+            destructiveHint: extendedTool.destructiveHint,
+            title: extendedTool.title,
+            description: tool.description,
+            idempotentHint: extendedTool.idempotentHint,
+            openWorldHint: extendedTool.openWorldHint,
+            source: "mcp",
+        };
+    }
+    // Priority 3: Check metadata
+    if (extendedTool.metadata) {
+        const hasMetadataAnnotations = extendedTool.metadata.readOnlyHint !== undefined ||
+            extendedTool.metadata.destructiveHint !== undefined;
+        if (hasMetadataAnnotations) {
+            return {
+                readOnlyHint: extendedTool.metadata.readOnlyHint,
+                destructiveHint: extendedTool.metadata.destructiveHint,
+                title: extendedTool.metadata.title || extendedTool.title,
+                description: tool.description,
+                idempotentHint: extendedTool.metadata.idempotentHint,
+                openWorldHint: extendedTool.metadata.openWorldHint,
+                source: "mcp",
+            };
+        }
+    }
+    return {
+        title: extendedTool.title,
+        description: tool.description,
+        source: "none",
+    };
+}
+/**
+ * Extract extended metadata from tool (Issue #54)
+ * Extracts rate limits, permissions, return schemas, and bulk operation support
+ */
+export function extractExtendedMetadata(tool) {
+    const extendedTool = tool;
+    const metadata = {};
+    // Rate limiting - check annotations, metadata, and direct props
+    const rateLimit = extendedTool.rateLimit ||
+        extendedTool.annotations?.rateLimit ||
+        extendedTool.metadata?.rateLimit;
+    if (rateLimit && typeof rateLimit === "object") {
+        metadata.rateLimit = {
+            windowMs: rateLimit.windowMs,
+            maxRequests: rateLimit.maxRequests,
+            requestsPerMinute: rateLimit.requestsPerMinute,
+            requestsPerSecond: rateLimit.requestsPerSecond,
+        };
+    }
+    // Permissions - check requiredPermission, permissions, scopes
+    const permissions = extendedTool.requiredPermission ||
+        extendedTool.permissions ||
+        extendedTool.annotations?.permissions ||
+        extendedTool.metadata?.requiredPermission ||
+        extendedTool.metadata?.permissions;
+    if (permissions) {
+        const required = Array.isArray(permissions) ? permissions : [permissions];
+        const scopes = extendedTool.scopes ||
+            extendedTool.annotations?.scopes ||
+            extendedTool.metadata?.scopes;
+        metadata.permissions = {
+            required: required.filter((p) => typeof p === "string"),
+            scopes: Array.isArray(scopes)
+                ? scopes.filter((s) => typeof s === "string")
+                : undefined,
+        };
+    }
+    // Return schema - check outputSchema (MCP 2025-06-18 spec)
+    if (extendedTool.outputSchema) {
+        metadata.returnSchema = {
+            hasSchema: true,
+            schema: extendedTool.outputSchema,
+        };
+    }
+    // Bulk operations - check metadata for batch support
+    const bulkSupport = extendedTool.supportsBulkOperations ||
+        extendedTool.annotations?.supportsBulkOperations ||
+        extendedTool.metadata?.supportsBulkOperations;
+    const maxBatchSize = extendedTool.metadata?.maxBatchSize;
+    if (bulkSupport !== undefined || maxBatchSize !== undefined) {
+        metadata.bulkOperations = {
+            supported: !!bulkSupport,
+            maxBatchSize: typeof maxBatchSize === "number" ? maxBatchSize : undefined,
+        };
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+/**
+ * Extract parameters from tool input schema
+ */
+export function extractToolParams(schema) {
+    if (!schema || typeof schema !== "object")
+        return [];
+    const s = schema;
+    if (!s.properties || typeof s.properties !== "object")
+        return [];
+    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    const properties = s.properties;
+    return Object.entries(properties).map(([name, prop]) => {
+        const param = {
+            name,
+            type: prop.type || "any",
+            required: required.has(name),
+        };
+        if (prop.description) {
+            param.description = prop.description;
+        }
+        return param;
+    });
+}
+/**
+ * Assess a single tool's annotations
+ */
+export function assessSingleTool(tool, compiledPatterns, persistenceContext) {
+    const issues = [];
+    const recommendations = [];
+    const annotations = extractAnnotations(tool);
+    const hasAnnotations = annotations.readOnlyHint !== undefined ||
+        annotations.destructiveHint !== undefined;
+    const inferredBehavior = inferBehavior(tool.name, tool.description, compiledPatterns, persistenceContext);
+    let alignmentStatus = "ALIGNED";
+    if (!hasAnnotations) {
+        issues.push("Missing tool annotations (readOnlyHint, destructiveHint)");
+        recommendations.push(`Add annotations to ${tool.name}: readOnlyHint=${inferredBehavior.expectedReadOnly}, destructiveHint=${inferredBehavior.expectedDestructive}`);
+        alignmentStatus = "UNKNOWN";
+    }
+    else {
+        // Check for high-confidence deception
+        const deception = detectAnnotationDeception(tool.name, {
+            readOnlyHint: annotations.readOnlyHint,
+            destructiveHint: annotations.destructiveHint,
+        });
+        if (deception) {
+            alignmentStatus = "MISALIGNED";
+            issues.push(`DECEPTIVE ANNOTATION: ${deception.reason}`);
+            recommendations.push(`CRITICAL: Fix deceptive ${deception.field} for ${tool.name} - tool name contains '${deception.matchedKeyword}' which contradicts the annotation`);
+            if (deception.field === "readOnlyHint") {
+                inferredBehavior.expectedReadOnly = false;
+                inferredBehavior.confidence = "high";
+                inferredBehavior.isAmbiguous = false;
+                inferredBehavior.reason = deception.reason;
+            }
+            else {
+                inferredBehavior.expectedDestructive = true;
+                inferredBehavior.confidence = "high";
+                inferredBehavior.isAmbiguous = false;
+                inferredBehavior.reason = deception.reason;
+            }
+        }
+        else {
+            // Check for misaligned annotations
+            const readOnlyMismatch = annotations.readOnlyHint !== undefined &&
+                annotations.readOnlyHint !== inferredBehavior.expectedReadOnly;
+            const destructiveMismatch = annotations.destructiveHint !== undefined &&
+                annotations.destructiveHint !== inferredBehavior.expectedDestructive;
+            if (readOnlyMismatch || destructiveMismatch) {
+                if (!inferredBehavior.isAmbiguous &&
+                    isActionableConfidence(inferredBehavior.confidence)) {
+                    alignmentStatus = "MISALIGNED";
+                    if (readOnlyMismatch) {
+                        issues.push(`Potentially misaligned readOnlyHint: set to ${annotations.readOnlyHint}, expected ${inferredBehavior.expectedReadOnly} based on tool name pattern`);
+                        recommendations.push(`Verify readOnlyHint for ${tool.name}: currently ${annotations.readOnlyHint}, tool name suggests ${inferredBehavior.expectedReadOnly}`);
+                    }
+                    if (destructiveMismatch) {
+                        issues.push(`Potentially misaligned destructiveHint: set to ${annotations.destructiveHint}, expected ${inferredBehavior.expectedDestructive} based on tool name pattern`);
+                        recommendations.push(`Verify destructiveHint for ${tool.name}: currently ${annotations.destructiveHint}, tool name suggests ${inferredBehavior.expectedDestructive}`);
+                    }
+                }
+            }
+        }
+    }
+    // Check for destructive tools without explicit hint
+    if (inferredBehavior.expectedDestructive &&
+        isActionableConfidence(inferredBehavior.confidence) &&
+        annotations.destructiveHint !== true) {
+        issues.push("Tool appears destructive but destructiveHint is not set to true");
+        recommendations.push(`Set destructiveHint=true for ${tool.name} - this tool appears to perform destructive operations`);
+        if (inferredBehavior.confidence === "high") {
+            alignmentStatus = "MISALIGNED";
+        }
+    }
+    // Scan for description poisoning
+    const descriptionPoisoning = scanDescriptionForPoisoning(tool);
+    if (descriptionPoisoning.detected) {
+        issues.push(`Tool description contains suspicious patterns: ${descriptionPoisoning.patterns.map((p) => p.name).join(", ")}`);
+        recommendations.push(`Review ${tool.name} description for potential prompt injection or hidden instructions`);
+    }
+    // Extract extended metadata (Issue #54)
+    const extendedMetadata = extractExtendedMetadata(tool);
+    return {
+        toolName: tool.name,
+        hasAnnotations,
+        annotations: hasAnnotations ? annotations : undefined,
+        annotationSource: annotations.source,
+        inferredBehavior,
+        alignmentStatus,
+        issues,
+        recommendations,
+        descriptionPoisoning,
+        extendedMetadata,
+    };
+}
+/**
+ * Determine overall status based on tool results
+ */
+export function determineAnnotationStatus(results, totalTools) {
+    if (totalTools === 0)
+        return "PASS";
+    const annotatedCount = results.filter((r) => r.hasAnnotations).length;
+    const poisonedCount = results.filter((r) => r.descriptionPoisoning?.detected === true).length;
+    if (poisonedCount > 0)
+        return "FAIL";
+    const misalignedCount = results.filter((r) => r.alignmentStatus === "MISALIGNED").length;
+    const destructiveWithoutHint = results.filter((r) => r.inferredBehavior?.expectedDestructive === true &&
+        r.inferredBehavior?.confidence === "high" &&
+        r.annotations?.destructiveHint !== true).length;
+    if (destructiveWithoutHint > 0)
+        return "FAIL";
+    if (misalignedCount > 0)
+        return "FAIL";
+    if (annotatedCount === totalTools)
+        return "PASS";
+    const annotationRate = annotatedCount / totalTools;
+    if (annotationRate >= 0.8)
+        return "NEED_MORE_INFO";
+    if (annotationRate < 0.5)
+        return "FAIL";
+    return "NEED_MORE_INFO";
+}
+/**
+ * Calculate metrics and alignment breakdown
+ */
+export function calculateMetrics(results, totalTools) {
+    const alignmentBreakdown = {
+        aligned: results.filter((r) => r.alignmentStatus === "ALIGNED").length,
+        misaligned: results.filter((r) => r.alignmentStatus === "MISALIGNED")
+            .length,
+        reviewRecommended: results.filter((r) => r.alignmentStatus === "REVIEW_RECOMMENDED").length,
+        unknown: results.filter((r) => r.alignmentStatus === "UNKNOWN").length,
+    };
+    const annotatedCount = results.filter((r) => r.hasAnnotations).length;
+    const metrics = {
+        coverage: totalTools > 0 ? (annotatedCount / totalTools) * 100 : 100,
+        consistency: totalTools > 0
+            ? ((totalTools - alignmentBreakdown.misaligned) / totalTools) * 100
+            : 100,
+        correctness: annotatedCount > 0
+            ? (alignmentBreakdown.aligned / annotatedCount) * 100
+            : 0,
+        reviewRequired: alignmentBreakdown.reviewRecommended,
+    };
+    return { metrics, alignmentBreakdown };
+}

package/lib/services/assessment/modules/annotations/ClaudeIntegration.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Claude Integration Module
+ * Handles Claude-enhanced tool behavior inference
+ *
+ * Extracted from ToolAnnotationAssessor.ts as part of Issue #105 refactoring.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ToolAnnotationResult } from "../../../../lib/assessmentTypes.js";
+import type { ClaudeCodeBridge } from "../../lib/claudeCodeBridge.js";
+import type { Logger } from "../../lib/logger.js";
+import type { EnhancedToolAnnotationResult } from "./types.js";
+export type { EnhancedToolAnnotationResult } from "./types.js";
+/**
+ * Enhance tool assessment with Claude inference
+ */
+export declare function enhanceWithClaudeInference(tool: Tool, baseResult: ToolAnnotationResult, claudeBridge: ClaudeCodeBridge | undefined, logger: Logger): Promise<EnhancedToolAnnotationResult>;
+/**
+ * Create pattern-based Claude inference fallback
+ * Used when Claude enhancement is not enabled
+ */
+export declare function createPatternBasedInference(baseResult: ToolAnnotationResult): EnhancedToolAnnotationResult;
+//# sourceMappingURL=ClaudeIntegration.d.ts.map

package/lib/services/assessment/modules/annotations/ClaudeIntegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClaudeIntegration.d.ts","sourceRoot":"","sources":["../../../../../src/services/assessment/modules/annotations/ClaudeIntegration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAG5D,YAAY,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAE5D;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,oBAAoB,EAChC,YAAY,EAAE,gBAAgB,GAAG,SAAS,EAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,4BAA4B,CAAC,CAoIvC;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,4BAA4B,CAwB9B"}

package/lib/services/assessment/modules/annotations/ClaudeIntegration.js

@@ -0,0 +1,139 @@
+/**
+ * Claude Integration Module
+ * Handles Claude-enhanced tool behavior inference
+ *
+ * Extracted from ToolAnnotationAssessor.ts as part of Issue #105 refactoring.
+ */
+/**
+ * Enhance tool assessment with Claude inference
+ */
+export async function enhanceWithClaudeInference(tool, baseResult, claudeBridge, logger) {
+    const inferredBehavior = baseResult.inferredBehavior ?? {
+        expectedReadOnly: false,
+        expectedDestructive: false,
+        reason: "No behavior inference available",
+    };
+    if (!claudeBridge) {
+        return {
+            ...baseResult,
+            claudeInference: {
+                expectedReadOnly: inferredBehavior.expectedReadOnly,
+                expectedDestructive: inferredBehavior.expectedDestructive,
+                confidence: 50,
+                reasoning: inferredBehavior.reason,
+                suggestedAnnotations: {
+                    readOnlyHint: inferredBehavior.expectedReadOnly,
+                    destructiveHint: inferredBehavior.expectedDestructive,
+                },
+                misalignmentDetected: baseResult.issues.some((i) => i.includes("misaligned")),
+                source: "pattern-based",
+            },
+        };
+    }
+    try {
+        const currentAnnotations = baseResult.annotations
+            ? {
+                readOnlyHint: baseResult.annotations.readOnlyHint,
+                destructiveHint: baseResult.annotations.destructiveHint,
+            }
+            : undefined;
+        const inference = await claudeBridge.inferToolBehavior(tool, currentAnnotations);
+        if (!inference) {
+            return {
+                ...baseResult,
+                claudeInference: {
+                    expectedReadOnly: inferredBehavior.expectedReadOnly,
+                    expectedDestructive: inferredBehavior.expectedDestructive,
+                    confidence: 0,
+                    reasoning: "Claude inference unavailable. Using pattern-based analysis.",
+                    suggestedAnnotations: {},
+                    misalignmentDetected: false,
+                    source: "pattern-based",
+                },
+            };
+        }
+        const updatedIssues = [...baseResult.issues];
+        const updatedRecommendations = [...baseResult.recommendations];
+        if (inference.misalignmentDetected && inference.confidence >= 70) {
+            const misalignmentMsg = inference.misalignmentDetails
+                ? `Claude analysis (${inference.confidence}% confidence): ${inference.misalignmentDetails}`
+                : `Claude analysis detected annotation misalignment with ${inference.confidence}% confidence`;
+            if (!updatedIssues.some((i) => i.includes("Claude analysis"))) {
+                updatedIssues.push(misalignmentMsg);
+            }
+            if (inference.suggestedAnnotations) {
+                const { readOnlyHint, destructiveHint, idempotentHint } = inference.suggestedAnnotations;
+                if (readOnlyHint !== undefined &&
+                    readOnlyHint !== baseResult.annotations?.readOnlyHint) {
+                    updatedRecommendations.push(`Claude suggests: Set readOnlyHint=${readOnlyHint} for ${tool.name}`);
+                }
+                if (destructiveHint !== undefined &&
+                    destructiveHint !== baseResult.annotations?.destructiveHint) {
+                    updatedRecommendations.push(`Claude suggests: Set destructiveHint=${destructiveHint} for ${tool.name}`);
+                }
+                if (idempotentHint !== undefined) {
+                    updatedRecommendations.push(`Claude suggests: Consider adding idempotentHint=${idempotentHint} for ${tool.name}`);
+                }
+            }
+        }
+        return {
+            ...baseResult,
+            issues: updatedIssues,
+            recommendations: updatedRecommendations,
+            claudeInference: {
+                expectedReadOnly: inference.expectedReadOnly,
+                expectedDestructive: inference.expectedDestructive,
+                confidence: inference.confidence,
+                reasoning: inference.reasoning,
+                suggestedAnnotations: inference.suggestedAnnotations,
+                misalignmentDetected: inference.misalignmentDetected,
+                misalignmentDetails: inference.misalignmentDetails,
+                source: "claude-inferred",
+            },
+        };
+    }
+    catch (error) {
+        logger.error(`Claude inference failed for ${tool.name}`, { error });
+        return {
+            ...baseResult,
+            claudeInference: {
+                expectedReadOnly: inferredBehavior.expectedReadOnly,
+                expectedDestructive: inferredBehavior.expectedDestructive,
+                confidence: 50,
+                reasoning: `Claude inference failed, using pattern-based: ${inferredBehavior.reason}`,
+                suggestedAnnotations: {
+                    readOnlyHint: inferredBehavior.expectedReadOnly,
+                    destructiveHint: inferredBehavior.expectedDestructive,
+                },
+                misalignmentDetected: baseResult.issues.some((i) => i.includes("misaligned")),
+                source: "pattern-based",
+            },
+        };
+    }
+}
+/**
+ * Create pattern-based Claude inference fallback
+ * Used when Claude enhancement is not enabled
+ */
+export function createPatternBasedInference(baseResult) {
+    const inferredBehavior = baseResult.inferredBehavior ?? {
+        expectedReadOnly: false,
+        expectedDestructive: false,
+        reason: "No behavior inference available",
+    };
+    return {
+        ...baseResult,
+        claudeInference: {
+            expectedReadOnly: inferredBehavior.expectedReadOnly,
+            expectedDestructive: inferredBehavior.expectedDestructive,
+            confidence: 50,
+            reasoning: inferredBehavior.reason,
+            suggestedAnnotations: {
+                readOnlyHint: inferredBehavior.expectedReadOnly,
+                destructiveHint: inferredBehavior.expectedDestructive,
+            },
+            misalignmentDetected: baseResult.issues.some((i) => i.includes("misaligned")),
+            source: "pattern-based",
+        },
+    };
+}

package/lib/services/assessment/modules/annotations/EventEmitter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Annotation Event Emitter Module
+ * Handles emitting annotation-related progress events during assessment
+ *
+ * Extracted from ToolAnnotationAssessor.ts as part of Issue #105 refactoring.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ToolAnnotationResult, AlignmentStatus, ToolParamProgress, ProgressCallback } from "../../../../lib/assessmentTypes.js";
+import type { EnhancedToolAnnotationResult } from "./types.js";
+/**
+ * Emit annotation-related progress events
+ */
+export declare function emitAnnotationEvents(onProgress: ProgressCallback | undefined, tool: Tool, result: EnhancedToolAnnotationResult): void;
+/**
+ * Emit mismatch event (misaligned or review_recommended)
+ */
+export declare function emitMismatchEvent(onProgress: ProgressCallback | undefined, tool: Tool, toolParams: ToolParamProgress[], toolAnnotations: {
+    title?: string;
+}, field: "readOnlyHint" | "destructiveHint", actual: boolean | undefined, expected: boolean, confidence: number, inferred: NonNullable<ToolAnnotationResult["inferredBehavior"]>, alignmentStatus: AlignmentStatus): void;
+//# sourceMappingURL=EventEmitter.d.ts.map

package/lib/services/assessment/modules/annotations/EventEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventEmitter.d.ts","sourceRoot":"","sources":["../../../../../src/services/assessment/modules/annotations/EventEmitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAE5D;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,4BAA4B,GACnC,IAAI,CAkFN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,iBAAiB,EAAE,EAC/B,eAAe,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACnC,KAAK,EAAE,cAAc,GAAG,iBAAiB,EACzC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,WAAW,CAAC,oBAAoB,CAAC,kBAAkB,CAAC,CAAC,EAC/D,eAAe,EAAE,eAAe,GAC/B,IAAI,CAkCN"}

package/lib/services/assessment/modules/annotations/EventEmitter.js

@@ -0,0 +1,100 @@
+/**
+ * Annotation Event Emitter Module
+ * Handles emitting annotation-related progress events during assessment
+ *
+ * Extracted from ToolAnnotationAssessor.ts as part of Issue #105 refactoring.
+ */
+import { isActionableConfidence } from "./AnnotationDeceptionDetector.js";
+import { extractAnnotations, extractToolParams } from "./AlignmentChecker.js";
+/**
+ * Emit annotation-related progress events
+ */
+export function emitAnnotationEvents(onProgress, tool, result) {
+    if (!onProgress || !result.inferredBehavior)
+        return;
+    const annotations = result.annotations;
+    const inferred = result.inferredBehavior;
+    const confidence = result.claudeInference?.confidence ?? 50;
+    const toolParams = extractToolParams(tool.inputSchema);
+    const toolAnnotations = extractAnnotations(tool);
+    // Emit missing annotation event
+    if (!result.hasAnnotations) {
+        onProgress({
+            type: "annotation_missing",
+            tool: tool.name,
+            title: toolAnnotations.title,
+            description: tool.description,
+            parameters: toolParams,
+            inferredBehavior: {
+                expectedReadOnly: inferred.expectedReadOnly,
+                expectedDestructive: inferred.expectedDestructive,
+                reason: inferred.reason,
+            },
+        });
+        return;
+    }
+    // Emit aligned event
+    if (result.alignmentStatus === "ALIGNED") {
+        onProgress({
+            type: "annotation_aligned",
+            tool: tool.name,
+            confidence: inferred.confidence ?? "medium",
+            annotations: {
+                readOnlyHint: annotations?.readOnlyHint,
+                destructiveHint: annotations?.destructiveHint,
+                openWorldHint: annotations?.openWorldHint,
+                idempotentHint: annotations?.idempotentHint,
+            },
+        });
+        return;
+    }
+    // Get alignment status with fallback to UNKNOWN if undefined
+    const alignmentStatus = result.alignmentStatus ?? "UNKNOWN";
+    // Check readOnlyHint mismatch
+    if (annotations?.readOnlyHint !== undefined &&
+        annotations.readOnlyHint !== inferred.expectedReadOnly) {
+        emitMismatchEvent(onProgress, tool, toolParams, toolAnnotations, "readOnlyHint", annotations.readOnlyHint, inferred.expectedReadOnly, confidence, inferred, alignmentStatus);
+    }
+    // Check destructiveHint mismatch
+    if (annotations?.destructiveHint !== undefined &&
+        annotations.destructiveHint !== inferred.expectedDestructive) {
+        emitMismatchEvent(onProgress, tool, toolParams, toolAnnotations, "destructiveHint", annotations.destructiveHint, inferred.expectedDestructive, confidence, inferred, alignmentStatus);
+    }
+}
+/**
+ * Emit mismatch event (misaligned or review_recommended)
+ */
+export function emitMismatchEvent(onProgress, tool, toolParams, toolAnnotations, field, actual, expected, confidence, inferred, alignmentStatus) {
+    if (!onProgress)
+        return;
+    if (alignmentStatus === "REVIEW_RECOMMENDED") {
+        onProgress({
+            type: "annotation_review_recommended",
+            tool: tool.name,
+            title: toolAnnotations.title,
+            description: tool.description,
+            parameters: toolParams,
+            field,
+            actual,
+            inferred: expected,
+            confidence: inferred.confidence,
+            isAmbiguous: inferred.isAmbiguous,
+            reason: inferred.reason,
+        });
+    }
+    else if (!inferred.isAmbiguous &&
+        isActionableConfidence(inferred.confidence)) {
+        onProgress({
+            type: "annotation_misaligned",
+            tool: tool.name,
+            title: toolAnnotations.title,
+            description: tool.description,
+            parameters: toolParams,
+            field,
+            actual,
+            expected,
+            confidence,
+            reason: `Tool has ${field}=${actual}, but ${inferred.reason}`,
+        });
+    }
+}