claude-flow 3.56.9 → 3.57.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js

@@ -11,9 +11,12 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
-import { join, resolve } from 'path';
+import { basename, dirname, join, resolve } from 'path';
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'crypto';
+import { getProjectCwd } from './types.js';
 import { validateIdentifier } from './validate-input.js';
+import { DEFAULT_SEARCH_THRESHOLD, nearMisses } from '../memory/search-defaults.js';
 // #1604: Align with memory-initializer.ts — single source of truth is .swarm/memory.db
 const MEMORY_DIR = '.swarm';
 const LEGACY_MEMORY_FILE = 'store.json';
@@ -145,7 +148,24 @@ function resolveProjectMemoryDir(claudeProjectsDir, projectPathOverride) {
         sources.push(projectPathOverride);
     }
     else {
-        sources.push(process.cwd());
+        const project = getProjectCwd();
+        sources.push(project);
+        // Claude Code shares auto-memory across linked Git worktrees under the
+        // main checkout's project slug. Preserve the direct-path match first,
+        // then try the common Git directory's parent. Explicit overrides above
+        // remain authoritative, and non-Git projects need no Git dependency.
+        try {
+            const commonDir = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+                cwd: project,
+                encoding: 'utf-8',
+                timeout: 1000,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (basename(commonDir) === '.git')
+                sources.push(dirname(resolve(project, commonDir)));
+        }
+        catch { /* Git unavailable or not a repository: use the project path */ }
     }
     for (const source of sources) {
         // Candidate 1: legacy POSIX hash — what shipped before #1883
@@ -231,6 +251,19 @@ async function getMemoryFunctions() {
         checkMemoryInitialization,
     };
 }
+/**
+ * Path of the CLI's own store (.swarm/memory.db or CLAUDE_FLOW_DB_PATH), or
+ * undefined when the memory module cannot say (#4148). Never throws.
+ */
+async function resolveCliStorePath() {
+    try {
+        const mod = await import('../memory/memory-initializer.js');
+        return typeof mod.resolveDbPath === 'function' ? mod.resolveDbPath() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * #2922: every `backend:` field in this file's tool responses used to be the
  * hardcoded literal `'sql.js + HNSW'` regardless of which search path was
@@ -538,7 +571,7 @@ export const memoryTools = [
                 query: { type: 'string', description: 'Search query (semantic similarity)' },
                 namespace: { type: 'string', description: 'Namespace to search (default: all namespaces — omit to search across every namespace)' },
                 limit: { type: 'number', description: 'Maximum results (default: 10)' },
-                threshold: { type: 'number', description: 'Minimum raw retrieval relevance 0-1 for candidate admission, applied per query before SmartRetrieval ranking; not a floor on rankingScore (default: 0.3)' },
+                threshold: { type: 'number', description: 'Minimum raw retrieval relevance 0-1 for candidate admission, applied per query before SmartRetrieval ranking; not a floor on rankingScore (default: 0.2; calibrated for the bundled embedding model, pass 0 to see every match)' },
                 smart: { type: 'boolean', description: 'Enable SmartRetrieval — query expansion, RRF fusion, recency boost, MMR diversity; preserves raw similarity and adds rankingScore (default: false)' },
                 provenance_filter: {
                     type: 'array',
@@ -567,7 +600,8 @@ export const memoryTools = [
             // in the search layer actually fires.
             const namespace = input.namespace;
             const limit = input.limit ?? 10;
-            const threshold = input.threshold ?? 0.3;
+            const threshold = input.threshold ?? DEFAULT_SEARCH_THRESHOLD;
+            const thresholdWasDefault = input.threshold === undefined || input.threshold === null;
             validateMemoryInput(undefined, undefined, query, namespace);
             const startTime = performance.now();
             try {
@@ -638,10 +672,14 @@ export const memoryTools = [
                                 provenanceType: r.provenanceType,
                             };
                         });
+                        const smartNearMisses = results.length === 0 && thresholdWasDefault
+                            ? await nearMisses(searchEntries, { query, namespace, provenanceFilter })
+                            : undefined;
                         return {
                             query,
                             results,
                             total: results.length,
+                            ...(smartNearMisses ?? {}),
                             searchTime: `${duration.toFixed(2)}ms`,
                             backend: 'SmartRetrieval (RRF + MMR + Recency)',
                             stats: smartResult.stats,
@@ -685,10 +723,14 @@ export const memoryTools = [
                         provenanceType: r.provenanceType,
                     };
                 });
+                const nearMissInfo = results.length === 0 && thresholdWasDefault
+                    ? await nearMisses(searchEntries, { query, namespace, provenanceFilter })
+                    : undefined;
                 return {
                     query,
                     results,
                     total: results.length,
+                    ...(nearMissInfo ?? {}),
                     searchTime: `${duration.toFixed(2)}ms`,
                     backend: 'HNSW + sql.js',
                     ...(smartFallbackReason ? { smartFallback: smartFallbackReason } : {}),
@@ -1043,6 +1085,7 @@ export const memoryTools = [
             }
             let imported = 0;
             let skipped = 0;
+            const importErrors = [];
             // #1791.8 — Claude Code's `~/.claude/projects/` accumulates historical
             // project_id directories (truncated forms, sandbox cwds, renamed
             // workspaces) that all contain copies of the same memory files. The
@@ -1082,7 +1125,7 @@ export const memoryTools = [
                         // #1884 — sanitize key so memory_delete can later remove it. Without
                         // this, dangerous chars from frontmatter `name` strand the key.
                         const key = sanitizeMemoryKey(`claude:${memFile.project}:${name}`);
-                        const stored = await storeEntry({ key, value: body, namespace: ns, generateEmbeddingFlag: true });
+                        const stored = await storeEntry({ key, value: body, namespace: ns, generateEmbeddingFlag: true, upsert: true });
                         if (!stored.success)
                             throw new Error(stored.error || `Failed to store ${key}`);
                         imported++;
@@ -1097,15 +1140,19 @@ export const memoryTools = [
                             // #1884 — sanitize so any dangerous chars in the heading don't
                             // produce keys memory_delete will reject.
                             const key = sanitizeMemoryKey(`claude:${memFile.project}:${name}:${sectionTitle.slice(0, 50)}`);
-                            const stored = await storeEntry({ key, value: sectionBody, namespace: ns, generateEmbeddingFlag: true });
+                            const stored = await storeEntry({ key, value: sectionBody, namespace: ns, generateEmbeddingFlag: true, upsert: true });
                             if (!stored.success)
                                 throw new Error(stored.error || `Failed to store ${key}`);
                             imported++;
                         }
                     }
                 }
-                catch {
+                catch (err) {
                     skipped++;
+                    // Say why a file was skipped instead of returning a bare failure (#4197).
+                    if (importErrors.length < 5) {
+                        importErrors.push(`${memFile.path}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
             }
             // AUDIT #3: report the embedding backend truthfully — a hash-fallback
@@ -1124,6 +1171,7 @@ export const memoryTools = [
                 skipped,
                 duplicatesSkipped,
                 excludedByPattern,
+                ...(importErrors.length > 0 ? { errors: importErrors } : {}),
                 files: memoryFiles.length,
                 projects: projects.size,
                 namespace: ns,
@@ -1497,25 +1545,50 @@ export const memoryTools = [
                 if (!v.valid)
                     throw new Error(v.error);
             }
-            // #2073: pass includeContent so the value field carries the actual
-            // entry body. Without this, `value` is always null because listEntries
-            // strips content by default (callers pay for the JSON parse only when
-            // they need it).
-            // A successful export must cover the whole reported store. Read all
-            // pages before touching an existing snapshot, including on read failure.
-            const entries = [];
-            let total;
-            do {
-                const page = await listEntries({ limit: 10000, offset: entries.length, namespace, includeContent: true });
-                if (!page.success)
-                    return { error: page.error || 'Could not read memory for export' };
-                total ??= page.total;
-                if (page.entries.length === 0 && entries.length < total) {
-                    return { error: `Incomplete memory export: read ${entries.length} of ${total} entries` };
+            const readStore = async (dbPath) => {
+                const out = [];
+                let total;
+                do {
+                    const page = await listEntries({ limit: 10000, offset: out.length, namespace, includeContent: true, ...(dbPath ? { dbPath } : {}) });
+                    if (!page.success)
+                        return { error: page.error || 'Could not read memory for export' };
+                    total ??= page.total;
+                    if (page.entries.length === 0 && out.length < total) {
+                        return { error: `Incomplete memory export: read ${out.length} of ${total} entries` };
+                    }
+                    out.push(...page.entries);
+                } while (out.length < total);
+                return { entries: out };
+            };
+            const primary = await readStore();
+            if ('error' in primary)
+                return { error: primary.error };
+            // #4148: the default reader is the AgentDB bridge, but the CLI's own store
+            // (.swarm/memory.db, possibly encrypted) can hold rows the bridge never
+            // sees, so an export silently covered one store and reported success. Read
+            // the CLI store too and merge, newest copy of a (namespace, key) winning.
+            const warnings = [];
+            const stores = [{ store: 'default', entries: primary.entries.length }];
+            const merged = new Map();
+            const keep = (e) => {
+                const id = `${e.namespace}\u0000${e.key}`;
+                const have = merged.get(id);
+                if (!have || String(e.updatedAt) > String(have.updatedAt))
+                    merged.set(id, e);
+            };
+            primary.entries.forEach(keep);
+            const cliStore = await resolveCliStorePath();
+            if (cliStore && existsSync(cliStore)) {
+                const secondary = await readStore(cliStore);
+                if ('error' in secondary) {
+                    warnings.push(`Could not read the CLI store ${cliStore} (${secondary.error}); the export covers the AgentDB store only.`);
                 }
-                entries.push(...page.entries);
-            } while (entries.length < total);
-            const all = { entries };
+                else {
+                    stores.push({ store: cliStore, entries: secondary.entries.length });
+                    secondary.entries.forEach(keep);
+                }
+            }
+            const all = { entries: [...merged.values()] };
             const payload = {
                 schema: 'ruflo-memory-export/v1',
                 exportedAt: new Date().toISOString(),
@@ -1542,6 +1615,8 @@ export const memoryTools = [
                 outputPath,
                 format: input.format || 'json',
                 exported: { entries: all.entries.length, vectors: vectorsWithEmb, patterns: 0 },
+                stores,
+                ...(warnings.length ? { warnings } : {}),
                 fileSize: `${Buffer.byteLength(JSON.stringify(payload))}B`,
                 note: input.format === 'csv' ? 'CSV not implemented yet — wrote JSON' : undefined,
             };

package/v3/@claude-flow/cli/dist/src/mcp-tools/metaharness-tools.js

@@ -399,7 +399,7 @@ export const metaharnessTools = [
     },
     // ───────────────────────────────────────────────────────────────────────
     // ADR-153 — @metaharness/darwin integration (3 tools).
-    // Backed by the separate `@metaharness/darwin@~0.10.2` npm package, NOT
+    // Backed by the separate `@metaharness/darwin@~0.12.0` npm package, NOT
     // the umbrella `metaharness`. Plugin scripts shell out via _darwin.mjs.
     // Same {success, data, degraded, exitCode} contract.
     // ───────────────────────────────────────────────────────────────────────

package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js

@@ -452,8 +452,24 @@ export const neuralTools = [
                     patternsStored++;
                 }
             }
+            // #4156: nothing stored means nothing was trained. Reporting success and "ready" made
+            // callers (the neural-train skill) believe the pattern store had been filled.
+            if (patternsStored === 0) {
+                model.status = 'untrained';
+                model.accuracy = 0;
+                saveNeuralStore(store);
+                return {
+                    success: false,
+                    status: 'empty',
+                    modelId,
+                    type: modelType,
+                    patternsStored: 0,
+                    totalPatterns: Object.keys(store.patterns).length,
+                    error: 'neural_train stored nothing: pass `data` (an array of strings or {text, label} entries). It does not read trajectories, SONA or the ReasoningBank: those (hooks_intelligence_*) are a separate store that neural_predict and neural_patterns do not see.',
+                };
+            }
             model.status = 'ready';
-            model.accuracy = patternsStored > 0 ? 1.0 : 0; // accuracy = data stored, not simulated
+            model.accuracy = 1.0; // accuracy = data stored, not simulated
             model.trainedAt = new Date().toISOString();
             saveNeuralStore(store);
             return {
@@ -484,6 +500,7 @@ export const neuralTools = [
                 modelId: { type: 'string', description: 'Model ID to use' },
                 input: { type: 'string', description: 'Input text or data' },
                 topK: { type: 'number', description: 'Number of top predictions' },
+                minSimilarity: { type: 'number', description: 'Minimum cosine similarity for a stored pattern to count as a match (default 0.5). A softmax over a single candidate is always 1.0, so without a floor any input matched the only stored pattern with confidence 1' },
             },
             required: ['input'],
         },
@@ -502,6 +519,7 @@ export const neuralTools = [
             const modelId = input.modelId;
             const inputText = input.input;
             const topK = input.topK || 3;
+            const minSimilarity = typeof input.minSimilarity === 'number' ? input.minSimilarity : 0.5;
             // Find model or use default
             const model = modelId ? store.models[modelId] : Object.values(store.models).find(m => m.status === 'ready');
             if (model && model.status !== 'ready') {
@@ -519,9 +537,10 @@ export const neuralTools = [
             // to 1, and we surface enough metadata to trust the result.
             const storedPatterns = Object.values(store.patterns);
             let predictions;
+            let bestSimilarity = null;
             if (storedPatterns.length > 0) {
                 // Step 1: k-NN with cosine
-                const scored = storedPatterns
+                let scored = storedPatterns
                     .map(p => {
                     const sim = cosineSimilarity(embedding, p.embedding);
                     return {
@@ -530,8 +549,10 @@ export const neuralTools = [
                         cosineSimilarity: sim,
                     };
                 })
-                    .sort((a, b) => b.cosineSimilarity - a.cosineSimilarity)
-                    .slice(0, topK);
+                    .sort((a, b) => b.cosineSimilarity - a.cosineSimilarity);
+                bestSimilarity = scored[0]?.cosineSimilarity ?? null;
+                // #4156: only patterns that reach the similarity floor are candidates.
+                scored = scored.filter((c) => c.cosineSimilarity >= minSimilarity).slice(0, topK);
                 // Step 2: temperature-softmax over the top-K so confidence sums to 1.
                 // Temperature 0.1 sharpens differences between similar candidates.
                 const tau = 0.1;
@@ -569,8 +590,11 @@ export const neuralTools = [
                 embedding: embedding.slice(0, 8), // Preview of embedding
                 embeddingDims: embedding.length,
                 latency,
+                ...(bestSimilarity !== null ? { bestSimilarity: Number(bestSimilarity.toFixed(4)), minSimilarity } : {}),
                 ...(storedPatterns.length === 0 ? {
                     _note: 'No patterns stored. Train with neural_train(modelType, trainingData) before predicting.',
+                } : predictions.length === 0 ? {
+                    _note: `No stored pattern reached the similarity floor (best ${bestSimilarity === null ? 'n/a' : bestSimilarity.toFixed(3)}, floor ${minSimilarity}); pass minSimilarity to lower it.`,
                 } : {}),
             };
         },
@@ -884,9 +908,6 @@ export const neuralTools = [
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
-            // Resolve provider so embeddingProvider in the result matches the old
-            // eager-init reporting.
-            await ensureEmbeddings();
             const store = loadNeuralStore();
             const method = input.method || 'quantize';
             const targetReduction = input.targetSize || 0.5;
@@ -895,38 +916,25 @@ export const neuralTools = [
                 return { success: false, error: 'No patterns to compress. Train patterns first with neural_train.' };
             }
             const beforeCount = patterns.length;
-            const beforeSize = patterns.reduce((s, p) => s + (p.embedding?.length || 0) * 4, 0); // Float32 = 4 bytes
             if (method === 'quantize') {
-                try {
-                    const { quantizeInt8, getQuantizationStats } = await import('../memory/memory-initializer.js');
-                    let totalCompressed = 0;
-                    for (const pattern of patterns) {
-                        if (pattern.embedding && pattern.embedding.length > 0) {
-                            const stats = getQuantizationStats(pattern.embedding);
-                            const quantized = quantizeInt8(pattern.embedding);
-                            // Store quantized metadata (keep original embedding for search)
-                            pattern._quantized = {
-                                scale: quantized.scale,
-                                zeroPoint: quantized.zeroPoint,
-                                compressionRatio: stats.compressionRatio,
-                            };
-                            totalCompressed++;
-                        }
-                    }
-                    saveNeuralStore(store);
-                    return {
-                        success: true, _real: true, method,
-                        embeddingProvider: embeddingServiceName,
-                        patternsCompressed: totalCompressed,
-                        compressionRatio: '3.92x (Int8)',
-                        beforeBytes: beforeSize,
-                        afterBytes: Math.round(beforeSize / 3.92),
-                    };
-                }
-                catch {
-                    return { success: false, error: 'Quantization requires memory-initializer. Run `memory init` first.' };
-                }
+                // Neural-store readers consume `embedding` as a full-precision number[]
+                // (search, prediction, deduplication, and optimization). The former
+                // implementation discarded the Int8 vector, persisted only metadata,
+                // and reported a calculated 3.92x reduction. Refuse until the store has
+                // a persisted representation with a reader-side decode contract.
+                const storedBytes = readFileSync(getNeuralPath()).byteLength;
+                return {
+                    success: false,
+                    error: 'Quantized embeddings are not persisted: neural-store readers require full-precision embedding arrays.',
+                    method,
+                    patternsCompressed: 0,
+                    beforeBytes: storedBytes,
+                    afterBytes: storedBytes,
+                    compressionRatio: '1.00x (unchanged JSON storage)',
+                };
             }
+            // Resolve provider only for operations that actually use embeddings.
+            await ensureEmbeddings();
             if (method === 'prune') {
                 // Prune patterns with low usage count below threshold (targetReduction as min usage)
                 const threshold = targetReduction;
@@ -1112,24 +1120,10 @@ export const neuralTools = [
                 if (duplicatesRemoved > 0)
                     actions.push(`Removed ${duplicatesRemoved} near-duplicate patterns`);
             }
-            // memory / balanced: quantize large embeddings
+            // memory / balanced: report the unsupported persisted representation
+            // instead of attaching metadata for a discarded Int8 vector.
             if (target === 'memory' || target === 'balanced') {
-                try {
-                    const { quantizeInt8, getQuantizationStats } = await import('../memory/memory-initializer.js');
-                    for (const p of Object.values(store.patterns)) {
-                        if (p.embedding && p.embedding.length > 0 && !p._quantized) {
-                            const stats = getQuantizationStats(p.embedding);
-                            const q = quantizeInt8(p.embedding);
-                            p._quantized = { scale: q.scale, zeroPoint: q.zeroPoint, compressionRatio: stats.compressionRatio };
-                            patternsQuantized++;
-                        }
-                    }
-                    if (patternsQuantized > 0)
-                        actions.push(`Quantized ${patternsQuantized} pattern embeddings (Int8, ~3.92x)`);
-                }
-                catch {
-                    actions.push('Quantization skipped (memory-initializer not available)');
-                }
+                actions.push('Quantization skipped: neural-store readers require persisted full-precision embedding arrays.');
             }
             // accuracy / balanced: prune low-usage, zero-embedding patterns
             if (target === 'accuracy' || target === 'balanced') {

package/v3/@claude-flow/cli/dist/src/mcp-tools/policy-tools.js

@@ -24,9 +24,11 @@ export const policyTools = [
         category: 'security',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                full: { type: 'boolean', description: 'Also replay the archived receipts to verify the complete historical ledger, not just the retained hot tail (#3164)' },
+            },
         },
-        handler: async (_input, context) => {
+        handler: async (input, context) => {
             const root = typeof context?.projectRoot === 'string' ? context.projectRoot : process.cwd();
             const state = loadPolicyState(root);
             return {
@@ -39,7 +41,7 @@ export const policyTools = [
                     approvals: state.approvals.length,
                     receipts: state.receipts.length,
                 },
-                ledger: await verifyPolicyLedger(root),
+                ledger: await verifyPolicyLedger(root, { full: input.full === true }),
             };
         },
     },

package/v3/@claude-flow/cli/dist/src/mcp-tools/ruvllm-tools.js

@@ -43,7 +43,13 @@ export const ruvllmWasmTools = [
                     nativeBackend = {
                         available: iStats._ruvllmBackend === 'active',
                         coordinator: iStats._ruvllmBackend || 'unavailable',
+                        // `trajectories` is the in-process SonaCoordinator buffer — it is
+                        // 0 in any process that did not itself record (e.g. this MCP
+                        // server while the daemon / hook processes do the recording).
                         trajectories: iStats._ruvllmTrajectories || 0,
+                        // Project-persisted total across all processes
+                        // (.claude-flow/neural/stats.json).
+                        trajectoriesRecorded: iStats.trajectoriesRecorded || 0,
                         contrastiveTrainer: sStats._contrastiveTrainer !== 'unavailable' ? 'active' : 'unavailable',
                         trainingBackend: iStats._trainingBackend || 'unknown',
                     };

package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.js

@@ -12,6 +12,7 @@
 import { validateText, validateIdentifier } from './validate-input.js';
 import { autoInstallPackage } from './auto-install.js';
 import { createRequire } from 'module';
+import { findKnownMiss, recordKnownMiss } from './aidefence-known-misses.js';
 // Create require for resolving module paths
 const require = createRequire(import.meta.url);
 // Lazy-loaded AIDefence instance
@@ -152,7 +153,8 @@ const aidefenceScanTool = {
                     piiPresent = !!defender.hasPII(input);
                 }
                 catch { /* hasPII unavailable */ }
-                const threatDetected = result.threat || piiPresent;
+                const knownMiss = findKnownMiss(input);
+                const threatDetected = result.threat || piiPresent || !!knownMiss;
                 wrapperStats.quickScanCalls++;
                 if (threatDetected)
                     wrapperStats.quickScanThreats++;
@@ -164,24 +166,29 @@ const aidefenceScanTool = {
                                 threatDetected,
                                 confidence: result.confidence,
                                 piiDetected: piiPresent,
-                                promptInjectionDetected: result.threat,
+                                promptInjectionDetected: result.threat || !!knownMiss,
+                                ...(knownMiss ? { knownMiss: { threatType: knownMiss.threatType, reportedAt: knownMiss.reportedAt } } : {}),
                                 mode: 'quick',
                             }, null, 2),
                         }],
                 };
             }
             const result = await defender.detect(input);
+            const knownMiss = findKnownMiss(input);
             return {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
-                            safe: result.safe,
-                            threats: result.threats.map(t => ({
-                                type: t.type,
-                                severity: t.severity,
-                                confidence: t.confidence,
-                                description: t.description,
-                            })),
+                            safe: result.safe && !knownMiss,
+                            threats: [
+                                ...result.threats.map(t => ({
+                                    type: t.type,
+                                    severity: t.severity,
+                                    confidence: t.confidence,
+                                    description: t.description,
+                                })),
+                                ...(knownMiss ? [{ type: knownMiss.threatType, severity: 'high', confidence: 1, description: 'Matches an input previously reported as a missed threat (aidefence_learn)' }] : []),
+                            ],
                             piiFound: result.piiFound,
                             detectionTimeMs: result.detectionTimeMs,
                         }, null, 2),
@@ -398,11 +405,33 @@ const aidefenceLearnTool = {
             const defender = await getAIDefence();
             // Re-detect to get result for learning
             const result = await defender.detect(input);
-            // Learn from detection
-            await defender.learnFromDetection(input, result, {
-                wasAccurate,
-                userVerdict: verdict,
-            });
+            // A false negative (wasAccurate=false, nothing detected) gives
+            // learnFromDetection() no threat to store, so record the miss itself.
+            const falseNegative = !wasAccurate && result.threats.length === 0;
+            const missType = threatType || 'prompt_injection';
+            let learned = result.threats.length;
+            let newlyRecorded = false;
+            if (falseNegative) {
+                newlyRecorded = recordKnownMiss(input, missType);
+                if (newlyRecorded) {
+                    const synthetic = {
+                        ...result,
+                        safe: false,
+                        threats: [{
+                                type: missType,
+                                severity: 'high',
+                                confidence: 1,
+                                pattern: 'user-reported-miss',
+                                description: verdict || 'Reported by user as a missed threat',
+                            }],
+                    };
+                    await defender.learnFromDetection(input, synthetic, { wasAccurate, userVerdict: verdict });
+                }
+                learned = 1;
+            }
+            else {
+                await defender.learnFromDetection(input, result, { wasAccurate, userVerdict: verdict });
+            }
             // Record mitigation if provided
             if (threatType && mitigationStrategy && mitigationSuccess !== undefined) {
                 await defender.recordMitigation(threatType, mitigationStrategy, mitigationSuccess);
@@ -412,7 +441,14 @@ const aidefenceLearnTool = {
                         type: 'text',
                         text: JSON.stringify({
                             success: true,
-                            message: 'Feedback recorded for pattern learning',
+                            message: falseNegative
+                                ? (newlyRecorded
+                                    ? 'Missed threat recorded: this exact input (normalised for case/whitespace) will now be flagged by aidefence_scan and aidefence_is_safe. Detection is pattern-based and does not generalise from it.'
+                                    : 'This input was already recorded as a missed threat')
+                                : (learned === 0
+                                    ? 'Feedback noted, but no threat was detected so no pattern was learned. To teach a missed threat, pass wasAccurate=false.'
+                                    : 'Feedback recorded for pattern learning'),
+                            learned,
                             learnedFrom: {
                                 input: input.slice(0, 50) + (input.length > 50 ? '...' : ''),
                                 wasAccurate,
@@ -468,7 +504,8 @@ const aidefenceIsSafeTool = {
                 piiPresent = !!defender.hasPII(input);
             }
             catch { /* hasPII unavailable */ }
-            const safe = promptSafe && !piiPresent;
+            const knownMiss = findKnownMiss(input);
+            const safe = promptSafe && !piiPresent && !knownMiss;
             wrapperStats.isSafeCalls++;
             if (!safe)
                 wrapperStats.isSafeUnsafeVerdicts++;
@@ -477,8 +514,9 @@ const aidefenceIsSafeTool = {
                         type: 'text',
                         text: JSON.stringify({
                             safe,
-                            promptSafe,
+                            promptSafe: promptSafe && !knownMiss,
                             piiPresent,
+                            ...(knownMiss ? { knownMiss: { threatType: knownMiss.threatType, reportedAt: knownMiss.reportedAt } } : {}),
                         }, null, 2),
                     }],
             };