claude-flow 3.17.0 → 3.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.17.0",
+  "version": "3.18.1",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",
@@ -98,12 +98,18 @@
     "qs": ">=6.15.2",
     "protobufjs": ">=8.2.0",
     "uuid": ">=14.0.0",
-    "@opentelemetry/core": "1.25.1",
-    "@opentelemetry/resources": "1.25.1",
-    "@opentelemetry/sdk-trace-base": "1.25.1",
-    "@opentelemetry/sdk-node": ">=0.218.0",
+    "@opentelemetry/core": ">=2.8.0",
+    "@opentelemetry/resources": ">=2.8.0",
+    "@opentelemetry/sdk-trace-base": ">=2.8.0",
+    "@opentelemetry/sdk-node": ">=0.220.0",
     "@opentelemetry/auto-instrumentations-node": ">=0.75.0",
-    "@opentelemetry/exporter-prometheus": ">=0.217.0",
+    "@opentelemetry/exporter-prometheus": ">=0.220.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": ">=0.220.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.220.0",
+    "@opentelemetry/exporter-trace-otlp-proto": ">=0.220.0",
+    "@opentelemetry/otlp-exporter-base": ">=0.220.0",
+    "@opentelemetry/otlp-grpc-exporter-base": ">=0.220.0",
+    "@opentelemetry/otlp-transformer": ">=0.220.0",
     "axios": ">=1.13.2",
     "fast-uri": ">=3.1.0",
     "vite": ">=8.0.16",

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

@@ -451,17 +451,27 @@ const statusCommand = {
                     },
                     {
                         component: 'Contrastive Trainer',
-                        status: stats._contrastiveTrainer && stats._contrastiveTrainer !== 'unavailable' ? output.success('Active') : output.dim('Unavailable'),
-                        details: stats._contrastiveTrainer && stats._contrastiveTrainer !== 'unavailable'
+                        // #2549 — three states: live session (object with counts),
+                        // 'available' (module resolves, no in-process session — the
+                        // normal case for a read-only status process), 'unavailable'
+                        // (module genuinely does not resolve).
+                        status: typeof stats._contrastiveTrainer === 'object'
+                            ? output.success('Active')
+                            : stats._contrastiveTrainer === 'available'
+                                ? output.success('Available')
+                                : output.dim('Unavailable'),
+                        details: typeof stats._contrastiveTrainer === 'object'
                             ? `${stats._contrastiveTrainer.triplets ?? 0} triplets, ${stats._contrastiveTrainer.agents ?? 0} agents`
-                            : 'Install @ruvector/ruvllm',
+                            : stats._contrastiveTrainer === 'available'
+                                ? 'ready — trains in-process on demand'
+                                : 'Install @ruvector/ruvllm',
                     },
                     {
                         component: 'Training Pipeline',
-                        status: stats._trainingBackend === 'ruvllm' ? output.success('Active') : output.dim(stats._trainingBackend || 'Unavailable'),
+                        status: stats._trainingBackend === 'ruvllm' ? output.success('Available') : output.dim(stats._trainingBackend || 'Unavailable'),
                         details: stats._trainingBackend === 'ruvllm'
-                            ? 'ruvllm checkpoints enabled'
-                            : 'JS fallback (no checkpoints)',
+                            ? 'native @ruvector/ruvllm pipeline'
+                            : 'JS fallback',
                     },
                     await (async () => {
                         try {

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

@@ -33,6 +33,21 @@ function validateScore(value, defaultVal) {
         return defaultVal;
     return Math.max(0, Math.min(1, value));
 }
+/**
+ * Validate an optional ISO-8601 timestamp param (temporal validity fields).
+ * Returns { value } when absent or valid, { error } when present but unparseable.
+ */
+function validateIsoTimestamp(value, name) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'string' || value.length === 0 || value.length > 64) {
+        return { error: `${name} must be a non-empty ISO-8601 timestamp string (max 64 chars)` };
+    }
+    if (Number.isNaN(Date.parse(value))) {
+        return { error: `${name} is not a parseable ISO-8601 timestamp: ${value.substring(0, 64)}` };
+    }
+    return { value };
+}
 function sanitizeError(error) {
     if (error instanceof Error) {
         // Strip filesystem paths from error messages
@@ -616,6 +631,18 @@ export const agentdbHierarchicalStore = {
                 enum: ['working', 'episodic', 'semantic'],
                 default: 'working',
             },
+            validFrom: {
+                type: 'string',
+                description: 'Optional ISO-8601 timestamp from which this fact is valid (temporal validity — Zep/Graphiti-style). Omit for always-valid.',
+            },
+            validUntil: {
+                type: 'string',
+                description: 'Optional ISO-8601 timestamp after which this fact is no longer valid. Expired facts are hidden from recall unless includeExpired=true.',
+            },
+            supersedes: {
+                type: 'string',
+                description: 'Optional id (or key) of an existing entry this fact supersedes. The old entry is INVALIDATED (stamped validUntil=now + supersededBy=<new id>), not deleted — it stays auditable via recall includeExpired=true.',
+            },
         },
         required: ['key', 'value'],
     },
@@ -642,8 +669,26 @@ export const agentdbHierarchicalStore = {
             if (!['working', 'episodic', 'semantic'].includes(tier)) {
                 return { success: false, error: `Invalid tier: ${tier}. Must be working, episodic, or semantic` };
             }
+            // Temporal validity fields (all optional, backward compatible)
+            const validFrom = validateIsoTimestamp(params.validFrom, 'validFrom');
+            if (validFrom.error)
+                return { success: false, error: validFrom.error };
+            const validUntil = validateIsoTimestamp(params.validUntil, 'validUntil');
+            if (validUntil.error)
+                return { success: false, error: validUntil.error };
+            const supersedes = params.supersedes !== undefined
+                ? validateString(params.supersedes, 'supersedes', 1000)
+                : undefined;
+            if (params.supersedes !== undefined && !supersedes) {
+                return { success: false, error: 'supersedes must be a non-empty string (entry id or key, max 1KB)' };
+            }
             const bridge = await getBridge();
-            const result = await bridge.bridgeHierarchicalStore({ key, value, tier });
+            const result = await bridge.bridgeHierarchicalStore({
+                key, value, tier,
+                validFrom: validFrom.value,
+                validUntil: validUntil.value,
+                supersedes: supersedes ?? undefined,
+            });
             return result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };
         }
         catch (error) {
@@ -661,6 +706,11 @@ export const agentdbHierarchicalRecall = {
             query: { type: 'string', description: 'Recall query' },
             tier: { type: 'string', description: 'Filter by tier (working, episodic, semantic)' },
             topK: { type: 'number', description: 'Number of results (default: 5)' },
+            includeExpired: {
+                type: 'boolean',
+                description: 'Include temporally-invalid entries (superseded, expired, or not-yet-valid). Audit escape hatch — default false.',
+                default: false,
+            },
         },
         required: ['query'],
     },
@@ -686,6 +736,7 @@ export const agentdbHierarchicalRecall = {
                 query,
                 tier: tier ?? undefined,
                 topK: validatePositiveInt(params.topK, 5, MAX_TOP_K),
+                includeExpired: params.includeExpired === true,
             });
             return result ?? { results: [], error: 'AgentDB bridge not available. Use memory_search instead.' };
         }

package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-session-tools.d.ts

@@ -12,7 +12,11 @@
  *     (for trajectory hooks + RVF), and the bridged `memory` namespace (for
  *     AgentDB index). They do not inline a replay engine; replay
  *     enumerates trajectory steps and returns them for the caller to dispatch.
- *   - Pinned to ruvector@0.2.25 to match `ruflo-ruvector` ADR-0001.
+ *   - ruvector resolution is local-first: if a locally installed `ruvector`
+ *     package is found (the CLI already depends on ruvector@0.2.27), its bin
+ *     is spawned directly with `node`; otherwise we fall back to
+ *     `npx -y ruvector@0.2.27`. The previous 0.2.25 pin forced cold npx
+ *     downloads of a *second* ruvector version — 4 per browser session.
  *   - Best-effort: missing dependencies (no `ruvector`, no `agent-browser`,
  *     no AgentDB controller) degrade gracefully with a structured error
  *     rather than a process crash.

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

@@ -12,13 +12,21 @@
  *     (for trajectory hooks + RVF), and the bridged `memory` namespace (for
  *     AgentDB index). They do not inline a replay engine; replay
  *     enumerates trajectory steps and returns them for the caller to dispatch.
- *   - Pinned to ruvector@0.2.25 to match `ruflo-ruvector` ADR-0001.
+ *   - ruvector resolution is local-first: if a locally installed `ruvector`
+ *     package is found (the CLI already depends on ruvector@0.2.27), its bin
+ *     is spawned directly with `node`; otherwise we fall back to
+ *     `npx -y ruvector@0.2.27`. The previous 0.2.25 pin forced cold npx
+ *     downloads of a *second* ruvector version — 4 per browser session.
  *   - Best-effort: missing dependencies (no `ruvector`, no `agent-browser`,
  *     no AgentDB controller) degrade gracefully with a structured error
  *     rather than a process crash.
  */
 import { validateIdentifier, validateText } from './validate-input.js';
-const RUVECTOR_PIN = 'ruvector@0.2.25';
+// Pin matches the version in this package's own dependency tree so the npx
+// fallback never downloads a second ruvector. Subcommand surface verified
+// against ruvector@0.2.27 --help: `rvf create/compact/status/derive/segments`
+// and `hooks trajectory-begin/step/end` all exist with the flags used below.
+const RUVECTOR_PIN = 'ruvector@0.2.27';
 const RVF_DIR_DEFAULT = '.ruflo/browser-sessions';
 async function shell(cmd, args, opts = {}) {
     const { execFile } = await import('node:child_process');
@@ -41,6 +49,57 @@ async function shell(cmd, args, opts = {}) {
         };
     }
 }
+/**
+ * Resolve the locally installed ruvector CLI (memoized). Returns the absolute
+ * path to its bin script, or null when ruvector is not installed locally.
+ * Spawning `node <bin>` directly avoids the ~2-8s cold `npx -y ruvector@…`
+ * download that previously hit every ruvector shell-out (4 per session).
+ */
+let ruvectorCliPromise = null;
+function resolveLocalRuvectorCli() {
+    if (ruvectorCliPromise)
+        return ruvectorCliPromise;
+    ruvectorCliPromise = (async () => {
+        try {
+            const { createRequire } = await import('node:module');
+            const path = await import('node:path');
+            const { readFile } = await import('node:fs/promises');
+            const req = createRequire(import.meta.url);
+            const entry = req.resolve('ruvector');
+            // Walk up from the resolved entry to the package root (package.json
+            // itself may not be exported, so we can't require.resolve it directly).
+            let dir = path.dirname(entry);
+            for (let i = 0; i < 6; i++) {
+                try {
+                    const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf-8'));
+                    if (pkg.name === 'ruvector') {
+                        const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.ruvector;
+                        return bin ? path.join(dir, bin) : null;
+                    }
+                }
+                catch {
+                    // no package.json at this level — keep walking
+                }
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        catch {
+            // ruvector not installed locally
+        }
+        return null;
+    })();
+    return ruvectorCliPromise;
+}
+/** Run a ruvector CLI command: local install first, npx pin as fallback. */
+async function ruvector(args, opts = {}) {
+    const cli = await resolveLocalRuvectorCli();
+    if (cli)
+        return shell(process.execPath, [cli, ...args], opts);
+    return shell('npx', ['-y', RUVECTOR_PIN, ...args], opts);
+}
 async function ensureSessionsDir() {
     const { mkdir } = await import('node:fs/promises');
     const path = await import('node:path');
@@ -110,11 +169,21 @@ export const browserSessionTools = [
             //
             // 384 matches the MiniLM-L6 default used elsewhere in the
             // toolchain (ONNX embedder + AgentDB vector indexes).
-            const rvf = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'create', rvfPath, '--dimension', '384'], { timeout: 60000 });
+            const rvf = await ruvector(['rvf', 'create', rvfPath, '--dimension', '384'], { timeout: 60000 });
             if (!rvf.success)
                 return fail('rvf create failed', { detail: rvf.error, stderr: rvf.stderr, sessionId, rvfPath });
-            // 2. trajectory-begin
-            const tb = await shell('npx', ['-y', RUVECTOR_PIN, 'hooks', 'trajectory-begin', '--session-id', sessionId, '--task', input.task]);
+            // 2. trajectory-begin.
+            // Flag names verified against ruvector 0.2.25 AND 0.2.27 --help:
+            // trajectory-begin takes `-c/--context` + `-a/--agent` — the
+            // `--session-id`/`--task` flags previously passed here were never
+            // valid on either version (commander exited with "unknown option"),
+            // so every trajectory call failed. Same bug class as the #2015
+            // `rvf create --kind` fix documented above. The session id is folded
+            // into the context string since ruvector tracks a single current
+            // trajectory per project.
+            const tb = await ruvector(['hooks', 'trajectory-begin',
+                '--context', `${sessionId}: ${input.task}`,
+                '--agent', 'browser-session']);
             if (!tb.success)
                 return fail('trajectory-begin failed', { detail: tb.error, stderr: tb.stderr, sessionId, rvfPath });
             // 3. browser_open via agent-browser
@@ -125,11 +194,11 @@ export const browserSessionTools = [
                     return fail('browser open failed', { detail: npxBo.error, stderr: npxBo.stderr, sessionId, rvfPath });
                 }
             }
-            // 4. log the open as the first trajectory step
-            await shell('npx', ['-y', RUVECTOR_PIN, 'hooks', 'trajectory-step',
-                '--session-id', sessionId,
-                '--action', 'browser_open',
-                '--args', JSON.stringify({ url: input.url }),
+            // 4. log the open as the first trajectory step.
+            // trajectory-step takes `--action`/`--result` only (no --session-id /
+            // --args on 0.2.25 or 0.2.27) — args are folded into the action string.
+            await ruvector(['hooks', 'trajectory-step',
+                '--action', `browser_open ${JSON.stringify({ url: input.url })}`,
                 '--result', 'ok']);
             return ok({
                 sessionId,
@@ -167,14 +236,19 @@ export const browserSessionTools = [
             const verdict = input.verdict;
             if (!['pass', 'fail', 'partial'].includes(verdict))
                 return fail(`invalid verdict: ${verdict}`);
-            // 1. trajectory-end
-            const te = await shell('npx', ['-y', RUVECTOR_PIN, 'hooks', 'trajectory-end',
-                '--session-id', input.session,
-                '--verdict', verdict]);
+            // 1. trajectory-end.
+            // trajectory-end takes `--success` + `--quality <0-1>` (no
+            // --session-id / --verdict on 0.2.25 or 0.2.27) — the verdict maps to
+            // quality: pass=1 (+ --success), partial=0.5, fail=0.
+            const teArgs = ['hooks', 'trajectory-end',
+                '--quality', verdict === 'pass' ? '1' : verdict === 'partial' ? '0.5' : '0'];
+            if (verdict === 'pass')
+                teArgs.push('--success');
+            const te = await ruvector(teArgs);
             if (!te.success)
                 return fail('trajectory-end failed', { detail: te.error, stderr: te.stderr });
             // 2. rvf compact
-            const compact = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'compact', input.rvf_path]);
+            const compact = await ruvector(['rvf', 'compact', input.rvf_path]);
             if (!compact.success)
                 return fail('rvf compact failed', { detail: compact.error, stderr: compact.stderr });
             // 3. AgentDB index — best-effort via memory store (claude-flow bridges)
@@ -224,7 +298,7 @@ export const browserSessionTools = [
             if (!vS.valid)
                 return fail(vS.error || 'invalid session');
             // 1. Verify RVF container exists
-            const status = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'status', input.rvf_path]);
+            const status = await ruvector(['rvf', 'status', input.rvf_path]);
             if (!status.success)
                 return fail('rvf status failed', { detail: status.error, stderr: status.stderr });
             // 2. Derive child container if requested
@@ -236,13 +310,13 @@ export const browserSessionTools = [
                 const dir = path.dirname(input.rvf_path);
                 replayId = `${input.session}-replay-${Date.now()}`;
                 replayPath = path.join(dir, `${replayId}.rvf`);
-                const dr = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'derive', input.rvf_path, replayPath]);
+                const dr = await ruvector(['rvf', 'derive', input.rvf_path, replayPath]);
                 if (!dr.success)
                     return fail('rvf derive failed', { detail: dr.error, stderr: dr.stderr });
             }
             // 3. Surface the trajectory steps from the segments listing — the caller is
             //    expected to read trajectory.ndjson from the RVF container and dispatch.
-            const segments = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'segments', input.rvf_path]);
+            const segments = await ruvector(['rvf', 'segments', input.rvf_path]);
             return ok({
                 sourceSession: input.session,
                 sourceRvfPath: input.rvf_path,

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.d.ts

@@ -48,6 +48,7 @@ export declare const hooksWorkerDetect: MCPTool;
 export declare const hooksModelRoute: MCPTool;
 export declare const hooksModelOutcome: MCPTool;
 export declare const hooksModelStats: MCPTool;
+export declare const hooksModelVerify: MCPTool;
 export declare const hooksCodemod: MCPTool;
 export declare const hooksWorkerCancel: MCPTool;
 export declare const hooksTeammateIdle: MCPTool;

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

@@ -2384,12 +2384,14 @@ export const hooksTrajectoryStart = {
         properties: {
             task: { type: 'string', description: 'Task description' },
             agent: { type: 'string', description: 'Agent type' },
+            sessionId: { type: 'string', description: 'Session id for the execution-state tree (default: CLAUDE_FLOW_SESSION_ID or "default")' },
         },
         required: ['task'],
     },
     handler: async (params) => {
         const task = params.task;
         const agent = params.agent || 'coder';
+        const sessionId = params.sessionId || process.env.CLAUDE_FLOW_SESSION_ID || 'default';
         {
             const v = validateText(task, 'task');
             if (!v.valid)
@@ -2400,6 +2402,11 @@ export const hooksTrajectoryStart = {
             if (!v.valid)
                 return { success: false, error: v.error };
         }
+        if (params.sessionId) {
+            const v = validateIdentifier(params.sessionId, 'sessionId');
+            if (!v.valid)
+                return { success: false, error: v.error };
+        }
         const trajectoryId = `traj-${Date.now()}-${Math.random().toString(36).substring(7)}`;
         const startedAt = new Date().toISOString();
         // Create real trajectory entry in memory
@@ -2411,6 +2418,13 @@ export const hooksTrajectoryStart = {
             startedAt,
         };
         activeTrajectories.set(trajectoryId, trajectory);
+        // MAGE-style execution-state-tree mirror (prototype, ruvector/trajectory-tree.ts).
+        // Non-fatal by design — the semantic trajectory path below is untouched.
+        try {
+            const { getTrajectoryTree } = await import('../ruvector/trajectory-tree.js');
+            getTrajectoryTree().openTrajectory({ sessionId, trajectoryId, task, agent });
+        }
+        catch { /* prototype path — never blocks trajectory recording */ }
         // Persist pending trajectory to disk so it survives MCP restarts
         const storeFn = await getRealStoreFunction();
         if (storeFn) {
@@ -2479,6 +2493,12 @@ export const hooksTrajectoryStep = {
                 timestamp,
             });
         }
+        // MAGE-style execution-state-tree mirror (prototype, non-fatal)
+        try {
+            const { getTrajectoryTree } = await import('../ruvector/trajectory-tree.js');
+            getTrajectoryTree().appendStep({ trajectoryId, stepId, action, quality });
+        }
+        catch { /* prototype path — never blocks step recording */ }
         // ADR-130 Phase 3: fire-and-forget causal edge write
         // trajectory context node → step node (relation: "trajectory-caused")
         if (result) {
@@ -2563,6 +2583,12 @@ export const hooksTrajectoryEnd = {
             // Remove from active trajectories
             activeTrajectories.delete(trajectoryId);
         }
+        // MAGE-style execution-state-tree mirror (prototype, non-fatal)
+        try {
+            const { getTrajectoryTree } = await import('../ruvector/trajectory-tree.js');
+            getTrajectoryTree().closeTrajectory({ trajectoryId, success });
+        }
+        catch { /* prototype path — never blocks trajectory finalization */ }
         // SONA Learning - process trajectory outcome for routing optimization
         let sonaResult = {
             learned: false, patternKey: '', confidence: 0
@@ -2866,6 +2892,9 @@ export const hooksPatternSearch = {
             topK: { type: 'number', description: 'Number of results' },
             minConfidence: { type: 'number', description: 'Minimum similarity threshold (0-1)' },
             namespace: { type: 'string', description: 'Namespace to search (default: pattern)' },
+            strategy: { type: 'string', enum: ['semantic', 'state-tree'], description: 'Retrieval strategy. Default "semantic" (unchanged behavior). "state-tree" returns the MAGE-style root→current execution-state path for a session instead of embedding search (prototype).' },
+            sessionId: { type: 'string', description: 'Session id for strategy="state-tree" (default: CLAUDE_FLOW_SESSION_ID or "default")' },
+            depth: { type: 'number', description: 'For strategy="state-tree": max path nodes returned, counted from the current node upward' },
         },
         required: ['query'],
     },
@@ -2874,6 +2903,7 @@ export const hooksPatternSearch = {
         const topK = params.topK || 5;
         const minConfidence = params.minConfidence || 0.3;
         const namespace = params.namespace || 'pattern';
+        const strategy = params.strategy || 'semantic';
         {
             const v = validateText(query, 'query');
             if (!v.valid)
@@ -2884,6 +2914,44 @@ export const hooksPatternSearch = {
             if (!v.valid)
                 return { success: false, error: v.error };
         }
+        // Opt-in MAGE-style positional retrieval (prototype). Default stays the
+        // semantic vector path below — zero behavior change unless requested.
+        if (strategy === 'state-tree') {
+            const sessionId = params.sessionId || process.env.CLAUDE_FLOW_SESSION_ID || 'default';
+            if (params.sessionId) {
+                const v = validateIdentifier(params.sessionId, 'sessionId');
+                if (!v.valid)
+                    return { success: false, error: v.error };
+            }
+            try {
+                const { getTrajectoryTree } = await import('../ruvector/trajectory-tree.js');
+                const recall = getTrajectoryTree().recallPath({
+                    sessionId,
+                    depth: typeof params.depth === 'number' ? params.depth : undefined,
+                    siblingWindow: topK,
+                });
+                return {
+                    query,
+                    strategy: 'state-tree',
+                    backend: 'state-tree',
+                    sessionId: recall.sessionId,
+                    currentId: recall.currentId,
+                    path: recall.path,
+                    siblings: recall.siblings,
+                    note: 'Positional root→current execution-state path (no embedding search). Prototype — see ruvector/trajectory-tree.ts limitations.',
+                };
+            }
+            catch (error) {
+                return {
+                    query,
+                    strategy: 'state-tree',
+                    backend: 'state-tree-unavailable',
+                    path: [],
+                    siblings: [],
+                    error: String(error),
+                };
+            }
+        }
         // Phase 3: Try ReasoningBank search via bridge first
         try {
             const bridge = await import('../memory/memory-bridge.js');
@@ -4293,6 +4361,68 @@ export const hooksModelStats = {
         };
     },
 };
+// Model verify — confidence-gated tier escalation (post-generation).
+// The heuristics live in ruvector/output-verifier.ts; this wrapper adds the
+// MCP surface and feeds the verdict into the SAME learning stream that
+// hooks_model-outcome uses (ModelRouter.recordOutcome → Thompson priors), so
+// the router learns from escalations. A dedicated tool (rather than a
+// "verify mode" on hooks_model-outcome) was chosen because outcome recording
+// is a terminal write while verify is a MID-LOOP decision point that returns
+// a verdict the agent acts on — overloading outcome would conflate the two
+// and break the route → generate → verify → (escalate) → outcome sequence.
+export const hooksModelVerify = {
+    name: 'hooks_model-verify',
+    description: 'Verify a generated output with CHEAP structural signals ($0, no LLM call) and get an escalation verdict — the post-generation half of confidence-gated tier routing (route → generate → verify → escalate on failure). Checks: empty/truncated output, refusal patterns, degenerate repetition, and real syntax parsing for code/JSON tasks (TypeScript compiler / JSON.parse). Returns {confident, reasons[], suggestedTier, suggestedModel, escalate}. By default the verdict is recorded into the model-routing learning stream (success when confident, escalated when not) so the bandit learns which task shapes the cheap tier fails on. Use when you just generated with the tier hooks_model-route picked and must decide accept-vs-escalate BEFORE acting on the output; accepting cheap-tier output unverified is wrong because structurally unusable results (refusals, truncation, unparseable code) silently propagate downstream, and pre-generation routing alone cannot catch them. Not a semantic-quality judge — it only catches structurally unusable outputs.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string', description: 'The task the output was generated for' },
+            output: { type: 'string', description: 'The generated output to verify' },
+            model: { type: 'string', enum: ['haiku', 'sonnet', 'opus'], description: 'Model that produced the output (drives the escalation ladder; default haiku)' },
+            tierUsed: { type: 'number', enum: [1, 2, 3], description: 'Tier that produced the output; derived from model when absent' },
+            taskKind: { type: 'string', enum: ['code', 'json', 'text', 'auto'], description: 'Force the task kind; default auto-detect' },
+            record: { type: 'boolean', description: 'Record the verdict into the routing learning stream (default true; requires model)' },
+        },
+        required: ['task', 'output'],
+    },
+    handler: async (params) => {
+        const task = params.task;
+        const output = params.output;
+        const model = params.model;
+        {
+            const v = validateText(task, 'task');
+            if (!v.valid)
+                return { success: false, error: v.error };
+        }
+        if (typeof output !== 'string')
+            return { success: false, error: 'output must be a string' };
+        const { verifyAndEscalate } = await import('../ruvector/output-verifier.js');
+        const verdict = await verifyAndEscalate({
+            task,
+            output,
+            model,
+            tierUsed: params.tierUsed,
+            taskKind: params.taskKind,
+        });
+        // Feed the verdict into the existing outcome/learning stream (same path
+        // as hooks_model-outcome) so escalations update the Thompson priors.
+        let recorded = false;
+        if (params.record !== false && model) {
+            const router = await getModelRouterInstance();
+            if (router) {
+                router.recordOutcome(task, model, verdict.confident ? 'success' : 'escalated');
+                recorded = true;
+            }
+        }
+        return {
+            ...verdict,
+            model: model ?? 'haiku',
+            recorded,
+            recordedOutcome: recorded ? (verdict.confident ? 'success' : 'escalated') : null,
+            timestamp: new Date().toISOString(),
+        };
+    },
+};
 // Supported source extensions for codemods.
 const CODEMOD_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts']);
 const CODEMOD_MAX_FILES = 2000;
@@ -4686,6 +4816,7 @@ export const hooksTools = [
     hooksModelRoute,
     hooksModelOutcome,
     hooksModelStats,
+    hooksModelVerify,
     // Deterministic Tier-1 codemod execution (ADR-143)
     hooksCodemod,
 ];