agentic-qe 3.14.1 → 3.14.3

package/dist/mcp/handlers/domain-handler-configs.d.ts

@@ -8,7 +8,10 @@
  */
 import { DomainHandlerConfig } from './handler-factory';
 import { TestGenerateParams, TestGenerateResult, TestExecuteParams, CoverageAnalyzeParams, CoverageAnalyzeResult, QualityAssessParams, SecurityScanParams, ContractValidateParams, AccessibilityTestParams, ChaosTestParams } from '../types';
+import type { SecurityScanEvidence } from '../../domains/security-compliance/scan-evidence.js';
+import type { SecurityCoverage } from '../../domains/security-compliance/interfaces.js';
 import { type RiskDecision } from '../../contracts/verdicts.js';
+import type { EvaluatedQualityCheck } from '../../domains/quality-assessment/quality-evidence.js';
 export interface TestExecuteResult {
     taskId: string;
     status: string;
@@ -27,7 +30,10 @@ export interface TestExecuteResult {
 export interface QualityAssessResult {
     taskId: string;
     status: string;
-    qualityScore: number;
+    /** Static analysis score; omitted for measured gates, which have no aggregate score. */
+    qualityScore?: number;
+    /** Canonical measured checks, present when runGate is true. */
+    checks?: EvaluatedQualityCheck[];
     passed: boolean;
     metrics: Record<string, number>;
     recommendations: string[];
@@ -45,9 +51,24 @@ export interface SecurityScanResult {
     medium: number;
     low: number;
     topVulnerabilities: unknown[];
+    findings?: unknown[];
     recommendations: string[];
     duration: number;
     savedFiles?: string[];
+    informational?: number;
+    evidence?: SecurityScanEvidence;
+    limitations?: readonly string[];
+    coverage?: SecurityCoverage;
+    filesScanned?: number;
+    jstsFilesScanned?: number;
+    otherFilesScanned?: number;
+    deepAnalysisPerformed?: boolean;
+    analysisDepth?: string;
+    scanTypes?: {
+        sast: boolean;
+        dast: boolean;
+    };
+    note?: string;
 }
 export interface ContractValidateResult {
     taskId: string;

package/dist/mcp/handlers/domain-handler-configs.js

@@ -406,14 +406,19 @@ export const qualityAssessConfig = {
     priority: 'p0',
     defaultTimeout: 180000,
     buildTaskDescription: (params) => `Assess quality with ${params.runGate ? 'quality gate' : 'metrics analysis'}`,
-    mapToPayload: (params, routingResult) => ({
-        runGate: params.runGate || false,
-        threshold: params.threshold || 80,
-        metrics: params.metrics || ['coverage', 'complexity', 'maintainability'],
-        routingTier: routingResult?.decision.tier,
-        useAgentBooster: routingResult?.useAgentBooster,
-        compiledContext: routingResult?.compiledContext,
-    }),
+    mapToPayload: (params, routingResult) => {
+        if (params.runGate !== undefined && typeof params.runGate !== 'boolean') {
+            throw new Error('runGate must be a boolean.');
+        }
+        return {
+            runGate: params.runGate ?? false,
+            threshold: params.threshold || 80,
+            metrics: params.metrics || ['coverage', 'complexity', 'maintainability'],
+            routingTier: routingResult?.decision.tier,
+            useAgentBooster: routingResult?.useAgentBooster,
+            compiledContext: routingResult?.compiledContext,
+        };
+    },
     mapToResult: (taskId, data, duration, savedFiles) => {
         // ADR-103: attach a schema-validated RiskDecision envelope at the MCP
         // boundary (additive — existing fields unchanged). Omit rather than
@@ -426,7 +431,8 @@ export const qualityAssessConfig = {
         return {
             taskId,
             status: 'completed',
-            qualityScore: data.qualityScore || 0,
+            ...(typeof data.qualityScore === 'number' ? { qualityScore: data.qualityScore } : {}),
+            ...(Array.isArray(data.checks) ? { checks: data.checks } : {}),
             passed: data.passed || false,
             metrics: data.metrics || {},
             recommendations: data.recommendations || [],
@@ -452,25 +458,50 @@ export const securityScanConfig = {
             scanTypes.push('DAST');
         return `Security scan (${scanTypes.join(', ')}) for ${params.target || 'project'}`;
     },
-    mapToPayload: (params, routingResult) => ({
-        sast: params.sast !== false,
-        dast: params.dast || false,
-        compliance: params.compliance || [],
-        target: params.target || '.',
-        routingTier: routingResult?.decision.tier,
-        useAgentBooster: routingResult?.useAgentBooster,
-        compiledContext: routingResult?.compiledContext,
-    }),
+    mapToPayload: (params, routingResult) => {
+        for (const name of ['sast', 'dast']) {
+            if (params[name] !== undefined && typeof params[name] !== 'boolean') {
+                throw new Error(`${name} must be a boolean`);
+            }
+        }
+        return {
+            sast: params.sast !== false,
+            dast: params.dast || false,
+            compliance: params.compliance || [],
+            target: params.target || '.',
+            targetUrl: params.targetUrl,
+            routingTier: routingResult?.decision.tier,
+            useAgentBooster: routingResult?.useAgentBooster,
+            compiledContext: routingResult?.compiledContext,
+        };
+    },
     mapToResult: (taskId, data, duration, savedFiles) => ({
         taskId,
-        status: 'completed',
+        // Legacy task results without receipts cannot establish scan completeness.
+        status: data.evidence?.completeness === 'complete' ? 'completed'
+            : data.evidence?.completeness === 'partial' ? 'partial'
+                : data.evidence ? 'unavailable' : 'unverified',
         vulnerabilities: data.vulnerabilities || 0,
         critical: data.critical || 0,
         high: data.high || 0,
         medium: data.medium || 0,
         low: data.low || 0,
+        informational: data.informational || 0,
         topVulnerabilities: data.topVulnerabilities || [],
+        findings: data.findings,
         recommendations: data.recommendations || [],
+        evidence: data.evidence,
+        limitations: data.limitations || ['Execution receipts unavailable; scan completeness is unverified.'],
+        ...(data.evidence ? {
+            filesScanned: data.filesScanned,
+            jstsFilesScanned: data.jstsFilesScanned,
+            otherFilesScanned: data.otherFilesScanned,
+            coverage: data.coverage,
+        } : {}),
+        deepAnalysisPerformed: Boolean(data.evidence && data.deepAnalysisPerformed === true),
+        analysisDepth: data.analysisDepth,
+        scanTypes: data.scanTypes,
+        note: data.note,
         duration,
         savedFiles,
     }),

package/dist/mcp/handlers/domain-handlers.d.ts

@@ -35,12 +35,13 @@ export declare function resetTaskExecutor(): void;
  */
 export declare const handleTestGenerate: (params: TestGenerateParams) => Promise<ToolResult<TestGenerateResult>>;
 /**
- * Handle test execution tasks
+ * Handle test execution tasks using a nonempty list of concrete file paths.
+ * Expand glob patterns before calling; the task handler rejects them.
  *
  * @example
  * ```typescript
  * const result = await handleTestExecute({
- *   testFiles: ['tests/unit/*.test.ts'],
+ *   testFiles: ['tests/unit/auth.test.ts', 'tests/unit/session.test.ts'],
  *   parallel: true,
  *   parallelism: 4,
  * });
@@ -61,14 +62,15 @@ export declare const handleTestExecute: (params: TestExecuteParams) => Promise<T
  */
 export declare const handleCoverageAnalyze: (params: CoverageAnalyzeParams) => Promise<ToolResult<CoverageAnalyzeResult>>;
 /**
- * Handle quality assessment tasks
+ * Handle quality assessment tasks. With runGate:true, require fresh canonical
+ * evidence and return individual measured checks, without a static aggregate
+ * score. Missing, stale, or malformed evidence returns an error. threshold and
+ * metrics customize analysis-only requests; gate thresholds match the CLI.
  *
  * @example
  * ```typescript
  * const result = await handleQualityAssess({
  *   runGate: true,
- *   threshold: 80,
- *   metrics: ['coverage', 'complexity'],
  * });
  * ```
  */

package/dist/mcp/handlers/domain-handlers.js

@@ -42,12 +42,13 @@ export function resetTaskExecutor() {
  */
 export const handleTestGenerate = createDomainHandler(testGenerateConfig);
 /**
- * Handle test execution tasks
+ * Handle test execution tasks using a nonempty list of concrete file paths.
+ * Expand glob patterns before calling; the task handler rejects them.
  *
  * @example
  * ```typescript
  * const result = await handleTestExecute({
- *   testFiles: ['tests/unit/*.test.ts'],
+ *   testFiles: ['tests/unit/auth.test.ts', 'tests/unit/session.test.ts'],
  *   parallel: true,
  *   parallelism: 4,
  * });
@@ -68,14 +69,15 @@ export const handleTestExecute = createDomainHandler(testExecuteConfig);
  */
 export const handleCoverageAnalyze = createDomainHandler(coverageAnalyzeConfig);
 /**
- * Handle quality assessment tasks
+ * Handle quality assessment tasks. With runGate:true, require fresh canonical
+ * evidence and return individual measured checks, without a static aggregate
+ * score. Missing, stale, or malformed evidence returns an error. threshold and
+ * metrics customize analysis-only requests; gate thresholds match the CLI.
  *
  * @example
  * ```typescript
  * const result = await handleQualityAssess({
  *   runGate: true,
- *   threshold: 80,
- *   metrics: ['coverage', 'complexity'],
  * });
  * ```
  */

package/dist/mcp/index.d.ts

@@ -3,6 +3,7 @@
  * Model Context Protocol server and tools
  */
 export * from './types';
+export { CONSERVATIVE_TOOL_ANNOTATIONS, BUILT_IN_TOOL_NAMES, BUILT_IN_TOOL_SAFETY_INVENTORY, getBuiltInToolAnnotations, getBuiltInToolSafetyInventory, resolveToolAnnotations, type ResolvedToolAnnotations, } from './tool-annotations';
 export { ToolRegistry, createToolRegistry } from './tool-registry';
 export { getConnectionPool, initializeConnectionPool, shutdownConnectionPool, createConnectionPool, type PoolConnection, type ConnectionMetrics, type ConnectionPoolConfig, type PoolStats, DEFAULT_POOL_CONFIG, } from './connection-pool';
 export { getLoadBalancer, resetLoadBalancer, createLoadBalancer, type AgentLoadInfo, type LoadBalancingStrategy, type LoadBalancerConfig, type LoadBalancerStats, DEFAULT_LOAD_BALANCER_CONFIG, } from './load-balancer';

package/dist/mcp/index.js

@@ -4,6 +4,7 @@
  */
 // Types
 export * from './types.js';
+export { CONSERVATIVE_TOOL_ANNOTATIONS, BUILT_IN_TOOL_NAMES, BUILT_IN_TOOL_SAFETY_INVENTORY, getBuiltInToolAnnotations, getBuiltInToolSafetyInventory, resolveToolAnnotations, } from './tool-annotations.js';
 // Tool Registry (O(1) hash-indexed lookup via Map)
 export { ToolRegistry, createToolRegistry } from './tool-registry.js';
 // Connection Pool (ADR-039)

package/dist/mcp/protocol-server.js

@@ -7,6 +7,7 @@
  */
 import { createStdioTransport, JSON_RPC_ERRORS, isJsonRpcCodedError, McpError, } from './transport/index.js';
 import { createToolRegistry } from './tool-registry.js';
+import { resolveToolAnnotations } from './tool-annotations.js';
 import { MiddlewareChain } from './middleware/middleware-chain.js';
 import { createMicrocompactMiddleware } from './middleware/microcompact.js';
 import { SessionStore } from './services/session-store.js';
@@ -374,6 +375,7 @@ export class MCPProtocolServer {
         const tools = Array.from(this.tools.values()).map((entry) => ({
             name: entry.definition.name,
             description: entry.definition.description,
+            annotations: entry.definition.annotations,
             inputSchema: this.buildInputSchema(entry.definition),
         }));
         return { tools };
@@ -432,7 +434,10 @@ export class MCPProtocolServer {
             // the same output, so we can short-circuit repeated calls with an O(1)
             // fingerprint lookup. Tools without isConcurrencySafe (writes, scans,
             // executions) always re-run.
-            const cacheable = tool.definition.isConcurrencySafe === true;
+            // Explicit quality gates depend on current measured evidence and its age,
+            // not just arguments. A cached approval can outlive or contradict evidence.
+            const measuredQualityGate = name === 'quality_assess' && processedCtx.params?.runGate === true;
+            const cacheable = tool.definition.isConcurrencySafe === true && !measuredQualityGate;
             let cacheFingerprint = null;
             if (cacheable && process.env.AQE_SESSION_CACHE !== 'off') {
                 try {
@@ -819,7 +824,7 @@ export class MCPProtocolServer {
                 description: 'Execute test files in parallel with automatic retry on flaky failures. Example: test_execute_parallel({ testFiles: ["tests/auth.test.ts"], parallel: true })',
                 category: 'domain',
                 parameters: [
-                    { name: 'testFiles', type: 'array', description: 'Test files to execute' },
+                    { name: 'testFiles', type: 'array', description: 'Nonempty list of concrete test file paths (relative to the project working directory or absolute). Expand glob patterns before calling; glob patterns are rejected.' },
                     { name: 'parallel', type: 'boolean', description: 'Enable parallel execution', default: true },
                 ],
             },
@@ -847,7 +852,7 @@ export class MCPProtocolServer {
                 category: 'domain',
                 isConcurrencySafe: true,
                 parameters: [
-                    { name: 'runGate', type: 'boolean', description: 'Run quality gate evaluation', default: false },
+                    { name: 'runGate', type: 'boolean', description: 'Evaluate all seven canonical measured quality checks; requires complete, valid evidence from the last 24 hours. Returns individual checks, not a static aggregate score.', default: false },
                 ],
             },
             handler: (params) => handleQualityAssess(params),
@@ -856,12 +861,13 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'security_scan_comprehensive',
-                description: 'Run SAST and/or DAST security scans with vulnerability classification. Example: security_scan_comprehensive({ target: "src/", sast: true })',
+                description: 'Run security scans with execution evidence and explicit coverage limitations. Complete means the declared required scope ran, not that all vulnerabilities are absent. Example: security_scan_comprehensive({ target: "src/", sast: true })',
                 category: 'domain',
                 parameters: [
                     { name: 'sast', type: 'boolean', description: 'Run SAST scan', default: true },
                     { name: 'dast', type: 'boolean', description: 'Run DAST scan', default: false },
-                    { name: 'target', type: 'string', description: 'Target to scan' },
+                    { name: 'target', type: 'string', description: 'Source file or directory for SAST' },
+                    { name: 'targetUrl', type: 'string', description: 'URL for a requested DAST scan' },
                 ],
             },
             handler: (params) => handleSecurityScan(params),
@@ -1446,8 +1452,15 @@ export class MCPProtocolServer {
         console.error(`[MCP] Registered ${this.tools.size} tools (${bridgedCount} via QE bridge)`);
     }
     registerTool(entry) {
-        this.tools.set(entry.definition.name, entry);
-        this.registry.register(entry.definition, entry.handler);
+        const normalizedEntry = {
+            ...entry,
+            definition: {
+                ...entry.definition,
+                annotations: resolveToolAnnotations(entry.definition.name, entry.definition.annotations),
+            },
+        };
+        this.tools.set(normalizedEntry.definition.name, normalizedEntry);
+        this.registry.register(normalizedEntry.definition, normalizedEntry.handler);
     }
     buildInputSchema(definition) {
         const properties = {};

package/dist/mcp/qe-tool-bridge.js

@@ -72,6 +72,7 @@ export function registerMissingQETools(registerFn) {
                 name: tool.name,
                 description: tool.description,
                 category: 'domain',
+                annotations: tool.annotations,
                 parameters: schemaToParameters(tool),
             },
             handler: async (params) => {

package/dist/mcp/tool-annotations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP tool safety annotations and the built-in safety inventory.
+ *
+ * The inventory is deliberately conservative. A tool is marked read-only
+ * only when its registered operation is an observation/query with no write or
+ * execution path. Every other built-in receives the MCP-safe fallback: it may
+ * be destructive, is not assumed idempotent, and may interact with the world.
+ * These values guide clients but never replace authorization, sandbox, or
+ * policy enforcement.
+ */
+import type { ToolAnnotations } from './types';
+export type ResolvedToolAnnotations = Required<Pick<ToolAnnotations, 'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>> & Pick<ToolAnnotations, 'title'>;
+export interface BuiltInToolSafetyDisposition {
+    annotations: ResolvedToolAnnotations;
+    reason: string;
+}
+export declare const CONSERVATIVE_TOOL_ANNOTATIONS: ResolvedToolAnnotations;
+/** Complete deterministic inventory of names advertised by both MCP paths. */
+export declare const BUILT_IN_TOOL_NAMES: readonly string[];
+export declare const BUILT_IN_TOOL_SAFETY_INVENTORY: Readonly<Record<string, BuiltInToolSafetyDisposition>>;
+/** Resolve explicit metadata over inventory metadata over conservative defaults. */
+export declare function resolveToolAnnotations(name: string, annotations?: ToolAnnotations): ResolvedToolAnnotations;
+export declare function getBuiltInToolAnnotations(): Readonly<Record<string, ToolAnnotations>>;
+export declare function getBuiltInToolSafetyInventory(): Readonly<Record<string, BuiltInToolSafetyDisposition>>;
+//# sourceMappingURL=tool-annotations.d.ts.map

package/dist/mcp/tool-annotations.js

@@ -0,0 +1,75 @@
+/**
+ * MCP tool safety annotations and the built-in safety inventory.
+ *
+ * The inventory is deliberately conservative. A tool is marked read-only
+ * only when its registered operation is an observation/query with no write or
+ * execution path. Every other built-in receives the MCP-safe fallback: it may
+ * be destructive, is not assumed idempotent, and may interact with the world.
+ * These values guide clients but never replace authorization, sandbox, or
+ * policy enforcement.
+ */
+export const CONSERVATIVE_TOOL_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+});
+const HARD_CODED_TOOL_NAMES = [
+    'accessibility_test', 'advisor_consult', 'agent_complete', 'agent_list',
+    'agent_metrics', 'agent_spawn', 'agent_status', 'aqe_health', 'chaos_test',
+    'code_index', 'contract_validate', 'coverage_analyze_sublinear',
+    'cross_phase_cleanup', 'cross_phase_query', 'cross_phase_stats',
+    'cross_phase_store', 'defect_predict', 'fleet_health', 'fleet_init',
+    'fleet_status', 'format_signals', 'infra_healing_feed_output',
+    'infra_healing_recover', 'infra_healing_status', 'memory_delete',
+    'memory_query', 'memory_retrieve', 'memory_share', 'memory_store',
+    'memory_usage', 'migration_check', 'migration_promote', 'migration_status',
+    'model_route', 'phase_end', 'phase_start', 'pipeline_list', 'pipeline_load',
+    'pipeline_run', 'pipeline_validate', 'quality_assess',
+    'requirements_validate', 'routing_economics', 'routing_metrics',
+    'security_scan_comprehensive', 'session_cache_stats', 'task_cancel',
+    'task_list', 'task_orchestrate', 'task_status', 'task_submit',
+    'team_broadcast', 'team_health', 'team_list', 'team_message', 'team_rebalance',
+    'team_scale', 'test_execute_parallel', 'test_generate_enhanced',
+    'validation_pipeline',
+];
+// QE tools not duplicated by the hard-coded protocol registrations.
+const BRIDGED_TOOL_NAMES = [
+    'qe/analysis/token_usage', 'qe/code/c4',
+    'qe/coherence/audit', 'qe/coherence/check', 'qe/coherence/collapse',
+    'qe/coherence/consensus', 'qe/coverage/gaps',
+    'qe/embeddings/compare', 'qe/embeddings/generate', 'qe/embeddings/search',
+    'qe/embeddings/stats', 'qe/embeddings/store',
+    'qe/learning/dream', 'qe/learning/optimize',
+    'qe/mincut/health', 'qe/mincut/analyze', 'qe/mincut/strengthen',
+    'qe/planning/goap_execute', 'qe/planning/goap_plan', 'qe/planning/goap_status',
+    'qe/quality/gate', 'qe/qx/analyze', 'qe/requirements/quality-criteria',
+    'qe/security/url-validate', 'qe/tests/load', 'qe/tests/schedule',
+    'qe/visual/compare', 'qe/workflows/browser-load',
+];
+/** Complete deterministic inventory of names advertised by both MCP paths. */
+export const BUILT_IN_TOOL_NAMES = Object.freeze([...HARD_CODED_TOOL_NAMES, ...BRIDGED_TOOL_NAMES].sort());
+function conservativeDisposition() {
+    return {
+        annotations: CONSERVATIVE_TOOL_ANNOTATIONS,
+        reason: 'No narrow side-effect-free guarantee is recorded for this built-in; retain conservative policy defaults.',
+    };
+}
+export const BUILT_IN_TOOL_SAFETY_INVENTORY = Object.freeze(Object.fromEntries(BUILT_IN_TOOL_NAMES.map((name) => [name, conservativeDisposition()])));
+/** Resolve explicit metadata over inventory metadata over conservative defaults. */
+export function resolveToolAnnotations(name, annotations) {
+    const reviewedDisposition = BUILT_IN_TOOL_SAFETY_INVENTORY[name];
+    return Object.freeze({
+        ...(reviewedDisposition?.annotations ?? CONSERVATIVE_TOOL_ANNOTATIONS),
+        // Dynamic and plugin-supplied names cannot self-assert optimistic hints.
+        // Add the name to the reviewed inventory before accepting overrides.
+        ...(reviewedDisposition ? annotations : undefined),
+    });
+}
+export function getBuiltInToolAnnotations() {
+    return Object.fromEntries(Object.entries(BUILT_IN_TOOL_SAFETY_INVENTORY).map(([name, disposition]) => [name, disposition.annotations]));
+}
+export function getBuiltInToolSafetyInventory() {
+    return BUILT_IN_TOOL_SAFETY_INVENTORY;
+}
+//# sourceMappingURL=tool-annotations.js.map

package/dist/mcp/tool-registry.js

@@ -6,6 +6,7 @@
  */
 import { v4 as uuidv4 } from 'uuid';
 import { ALL_DOMAINS } from '../shared/types/index.js';
+import { resolveToolAnnotations } from './tool-annotations.js';
 import { sanitizeInput } from './security/cve-prevention.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { BatchToolExecutor } from './middleware/batch-executor.js';
@@ -234,32 +235,36 @@ export class ToolRegistry {
      * Register a tool
      */
     register(definition, handler) {
-        const existing = this.tools.get(definition.name);
+        const normalizedDefinition = {
+            ...definition,
+            annotations: resolveToolAnnotations(definition.name, definition.annotations),
+        };
+        const existing = this.tools.get(normalizedDefinition.name);
         if (existing) {
             // Update existing tool
-            existing.definition = definition;
+            existing.definition = normalizedDefinition;
             existing.handler = handler;
             return;
         }
         // Register new tool
         const tool = {
-            definition,
+            definition: normalizedDefinition,
             handler,
-            loaded: !definition.lazyLoad,
+            loaded: !normalizedDefinition.lazyLoad,
             loadCount: 0,
         };
-        this.tools.set(definition.name, tool);
+        this.tools.set(normalizedDefinition.name, tool);
         this.stats.totalTools++;
         // Track by category
-        this.categoryTools.get(definition.category)?.add(definition.name);
-        this.stats.byCategory[definition.category]++;
+        this.categoryTools.get(normalizedDefinition.category)?.add(normalizedDefinition.name);
+        this.stats.byCategory[normalizedDefinition.category]++;
         // Track by domain if specified
-        if (definition.domain) {
-            this.domainTools.get(definition.domain)?.add(definition.name);
-            this.stats.byDomain[definition.domain] =
-                (this.stats.byDomain[definition.domain] || 0) + 1;
+        if (normalizedDefinition.domain) {
+            this.domainTools.get(normalizedDefinition.domain)?.add(normalizedDefinition.name);
+            this.stats.byDomain[normalizedDefinition.domain] =
+                (this.stats.byDomain[normalizedDefinition.domain] || 0) + 1;
         }
-        if (!definition.lazyLoad) {
+        if (!normalizedDefinition.lazyLoad) {
             this.stats.loadedTools++;
         }
     }

package/dist/mcp/tools/base.d.ts

@@ -5,7 +5,7 @@
  * All domain tools extend this base class.
  */
 import { DomainName } from '../../shared/types';
-import { ToolResult, ToolResultMetadata } from '../types';
+import { ToolAnnotations, ToolResult, ToolResultMetadata } from '../types';
 import { MemoryBackend } from '../../kernel/interfaces';
 /**
  * Database-free mode: when AQE_MEMORY_BACKEND=memory, the MCP server keeps all
@@ -114,6 +114,7 @@ export interface MCPToolConfig {
     schema: MCPToolSchema;
     streaming?: boolean;
     timeout?: number;
+    annotations?: ToolAnnotations;
 }
 /**
  * Streaming callback for long-running operations
@@ -279,6 +280,11 @@ export declare abstract class MCPToolBase<TParams extends Record<string, unknown
      * Get tool description
      */
     get description(): string;
+    /**
+     * Return the complete, conservative safety metadata for this tool.
+     * Missing hints must never be interpreted as permission to skip policy.
+     */
+    get annotations(): ToolAnnotations;
     /**
      * Get domain this tool belongs to
      */

package/dist/mcp/tools/base.js

@@ -5,6 +5,7 @@
  * All domain tools extend this base class.
  */
 import { v4 as uuidv4 } from 'uuid';
+import { resolveToolAnnotations } from '../tool-annotations.js';
 import { HybridMemoryBackend } from '../../kernel/hybrid-backend.js';
 import { InMemoryBackend } from '../../kernel/memory-backend.js';
 import { findProjectRoot } from '../../kernel/unified-memory.js';
@@ -457,6 +458,13 @@ export class MCPToolBase {
     get description() {
         return this.config.description;
     }
+    /**
+     * Return the complete, conservative safety metadata for this tool.
+     * Missing hints must never be interpreted as permission to skip policy.
+     */
+    get annotations() {
+        return resolveToolAnnotations(this.name, this.config.annotations);
+    }
     /**
      * Get domain this tool belongs to
      */

package/dist/mcp/tools/registry.d.ts

@@ -6,6 +6,7 @@
  */
 import { MCPToolBase } from './base';
 import { ToolRegistry } from '../tool-registry';
+import type { ToolAnnotations } from '../types';
 export declare const QE_TOOL_NAMES: {
     readonly QX_ANALYZE: "qe/qx/analyze";
     readonly TEST_SCHEDULE: "qe/tests/schedule";
@@ -80,6 +81,7 @@ export declare function getToolsByDomain(domain: string): MCPToolBase[];
 export declare function getToolDefinition(tool: MCPToolBase): {
     name: string;
     description: string;
+    annotations: ToolAnnotations;
     inputSchema: Record<string, unknown>;
 };
 /**
@@ -88,6 +90,7 @@ export declare function getToolDefinition(tool: MCPToolBase): {
 export declare function getAllToolDefinitions(): Array<{
     name: string;
     description: string;
+    annotations: ToolAnnotations;
     inputSchema: Record<string, unknown>;
 }>;
 /**

package/dist/mcp/tools/registry.js

@@ -216,6 +216,7 @@ export function getToolDefinition(tool) {
     return {
         name: tool.name,
         description: tool.description,
+        annotations: tool.annotations,
         inputSchema: {
             ...schema,
             type: schema.type || 'object',

package/dist/mcp/types.d.ts

@@ -15,6 +15,20 @@ export interface ToolParameter {
     default?: unknown;
     enum?: string[];
 }
+/**
+ * Optional safety metadata advertised by an MCP tool.
+ *
+ * These hints help clients make better presentation and confirmation
+ * decisions. They are advisory only: authorization, sandboxing, and policy
+ * checks remain authoritative for every invocation.
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 /**
  * MCP tool definition
  */
@@ -26,6 +40,7 @@ export interface ToolDefinition {
     domain?: DomainName;
     lazyLoad?: boolean;
     isConcurrencySafe?: boolean;
+    annotations?: ToolAnnotations;
 }
 /**
  * Tool categories for organization and lazy loading
@@ -161,6 +176,9 @@ export interface TestGenerateParams {
  * Test execution parameters
  */
 export interface TestExecuteParams {
+    /** Concrete test file paths for test_execute_parallel; provide a nonempty list.
+     * Expand glob patterns before calling. The task handler does not expand them.
+     */
     testFiles?: string[];
     testSuites?: string[];
     parallel?: boolean;
@@ -196,6 +214,8 @@ export interface SecurityScanParams {
     dast?: boolean;
     compliance?: string[];
     target?: string;
+    /** URL for explicitly requested dynamic scanning. */
+    targetUrl?: string;
 }
 /**
  * Contract validation parameters

package/dist/shared/llm/router/hybrid-router.d.ts

@@ -113,6 +113,8 @@ export declare class HybridRouter {
      * Clear decision cache
      */
     clearCache(): void;
+    /** Select an explicitly pinned model without rules, shared cache, or fallback. */
+    private selectStrict;
     /**
      * Manual selection - use preferredProvider or default
      */
@@ -133,6 +135,8 @@ export declare class HybridRouter {
      * Execute request with fallback chain
      */
     private executeWithFallback;
+    /** Compare identity independently of the API transport hosting the model. */
+    private isSameModel;
     /**
      * Create a routing decision with proper model ID normalization (ADR-043)
      */