agentic-qe 3.10.3 → 3.10.5

package/dist/cli/commands/hooks-handlers/nesting-provenance.js

@@ -0,0 +1,46 @@
+/**
+ * Agentic QE v3 - Nested-Subagent Provenance Validation (ADR-101)
+ *
+ * Parses and validates the `--parent-agent-id` / `--depth` flags on
+ * `aqe hooks post-task`. Anthropic announced nested subagent support
+ * (depth=5) on 2026-06-09; recording which agent spawned a task and at
+ * what depth lets ReasoningBank segment patterns per hierarchy level —
+ * useful today for flat depth-1 spawns, and ready for deep chains the
+ * day the upstream `Task` denylist lifts.
+ */
+/** Agent identifiers: alphanum start, then alphanum / _ . : - , max 128 chars */
+const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+/** Defensive bound — well above Anthropic's announced depth=5 cap */
+export const MAX_NESTING_DEPTH = 32;
+/**
+ * Validate raw flag values. Both flags are optional and independent;
+ * depth=0 is a valid value (top-level) and must survive as 0, not be
+ * coerced to undefined.
+ */
+export function parseNestingProvenance(parentAgentIdRaw, depthRaw) {
+    const result = {};
+    if (parentAgentIdRaw !== undefined) {
+        if (!AGENT_ID_RE.test(parentAgentIdRaw)) {
+            return {
+                error: `Invalid --parent-agent-id "${parentAgentIdRaw}": must start with a letter or digit ` +
+                    `and contain only letters, digits, "_", ".", ":", "-" (max 128 chars)`,
+            };
+        }
+        result.parentAgentId = parentAgentIdRaw;
+    }
+    if (depthRaw !== undefined) {
+        const depth = typeof depthRaw === 'number' ? depthRaw : Number(depthRaw);
+        if (!Number.isInteger(depth)) {
+            return { error: `Invalid --depth "${depthRaw}": must be an integer` };
+        }
+        if (depth < 0) {
+            return { error: `Invalid --depth ${depth}: must be >= 0` };
+        }
+        if (depth > MAX_NESTING_DEPTH) {
+            return { error: `Invalid --depth ${depth}: must be <= ${MAX_NESTING_DEPTH}` };
+        }
+        result.depth = depth;
+    }
+    return result;
+}
+//# sourceMappingURL=nesting-provenance.js.map

package/dist/cli/commands/hooks-handlers/task-hooks.js

@@ -9,10 +9,12 @@ import chalk from 'chalk';
 import path from 'node:path';
 import { QE_HOOK_EVENTS } from '../../../learning/qe-hooks.js';
 import { findProjectRoot, getUnifiedMemory } from '../../../kernel/unified-memory.js';
+import { getNagualClient } from '../../../learning/nagual-client.js';
 import { applyHookBusyTimeout, getHooksSystem, createHybridBackendWithTimeout, incrementDreamExperience, persistTaskOutcome, updateHookRouterQValue, updateRoutingOutcomeQuality, printJson, printSuccess, } from './hooks-shared.js';
 import { ensureRoutingOutcomesAdr095Columns } from '../../../routing/routing-outcomes-migration.js';
 import { deriveTaskType } from '../../../learning/agent-routing.js';
 import { detectQEDomains } from '../../../learning/qe-patterns.js';
+import { parseNestingProvenance } from './nesting-provenance.js';
 // ============================================================================
 // Constants — task-bridge / routing-quality / q-learning
 // ============================================================================
@@ -32,6 +34,36 @@ const LOW_CONFIDENCE_THRESHOLD = 0.5;
 function hashDescription(description) {
     return createHash('sha256').update(description).digest('hex').slice(0, 16);
 }
+/**
+ * QE domains where nagual patterns add meaningful context.
+ * Skipped for trivial/short tasks to avoid latency with no benefit.
+ */
+const NAGUAL_SEARCH_DOMAINS = new Set([
+    'test-generation',
+    'coverage-analysis',
+    'defect-intelligence',
+    'security-compliance',
+    'quality-assessment',
+    'requirements-validation',
+]);
+const NAGUAL_SEARCH_MIN_DESCRIPTION_LENGTH = 80;
+/**
+ * Search nagual for relevant patterns when the task is complex enough to benefit.
+ * Returns empty array silently on any failure — always best-effort.
+ */
+async function fetchNagualContext(description, domain) {
+    if (!process.env['NAGUAL_URL'] && !process.env['NAGUAL_CLOUD_URL'] && !process.env['NAGUAL_CLOUD_KEY']) {
+        return [];
+    }
+    if (description.length < NAGUAL_SEARCH_MIN_DESCRIPTION_LENGTH) {
+        return [];
+    }
+    if (domain && !NAGUAL_SEARCH_DOMAINS.has(domain)) {
+        return [];
+    }
+    const client = getNagualClient();
+    return client.search(description.slice(0, 300), domain, 3);
+}
 /**
  * Register pre-task and post-task subcommands on the hooks command.
  */
@@ -63,6 +95,11 @@ export function registerTaskHooks(hooks) {
                 .slice(0, 5)
                 .map((p) => p?.id)
                 .filter((id) => typeof id === 'string');
+            // Nagual context: search cross-project knowledge hub for complex tasks
+            const nagualDomain = routing?.domains?.[0];
+            const nagualPatterns = options.description
+                ? await fetchNagualContext(String(options.description), nagualDomain)
+                : [];
             // Patches 090/100/160/300/320: signals derived from memory.db.
             // All best-effort: failures fall through to empty/default values.
             let historicalBest = null;
@@ -228,6 +265,14 @@ export function registerTaskHooks(hooks) {
                     lowConfidence,
                     // Bridge identifier so post-task can correlate (debug aid)
                     bridgeKey,
+                    // Nagual cross-project context
+                    nagualPatterns: nagualPatterns.map((p) => ({
+                        id: p.id,
+                        problem: p.problem,
+                        solution: p.solution.slice(0, 400),
+                        domain: p.domain,
+                        reward: p.reward,
+                    })),
                 });
             }
             else {
@@ -240,6 +285,12 @@ export function registerTaskHooks(hooks) {
                         console.log(chalk.yellow('  ⚠  Low confidence — consider providing more context'));
                     }
                 }
+                if (nagualPatterns.length > 0) {
+                    console.log(chalk.bold('\n📚 Nagual context (cross-project):'));
+                    for (const p of nagualPatterns) {
+                        console.log(chalk.dim(`  [${p.domain}] ${p.problem.slice(0, 80)} (reward: ${p.reward.toFixed(2)})`));
+                    }
+                }
             }
             return;
         }
@@ -261,10 +312,24 @@ export function registerTaskHooks(hooks) {
         .option('--agent <name>', 'Agent that executed the task')
         .option('--duration <ms>', 'Task duration in milliseconds')
         .option('-d, --description <desc>', 'Task description — fallback Q-state source when pre-task bridge is absent (issue #499)')
+        .option('--parent-agent-id <id>', 'Agent that spawned this task (ADR-101 nesting provenance)')
+        .option('--depth <n>', 'Nesting depth of this task, 0 = top-level (ADR-101)')
         .option('--json', 'Output as JSON')
         .action(async (options) => {
         try {
             const success = options.success === 'true' || options.success === true;
+            // ADR-101: validate nesting provenance before any persistence
+            const provenance = parseNestingProvenance(options.parentAgentId, options.depth);
+            if (provenance.error) {
+                if (options.json) {
+                    console.log(JSON.stringify({ success: false, error: provenance.error }));
+                }
+                else {
+                    console.error(chalk.red(`  ✗ ${provenance.error}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
             // Initialize hooks system and record learning outcome
             // BUG FIX: Must call getHooksSystem() FIRST to initialize, not check state.initialized
             let patternsLearned = 0;
@@ -294,11 +359,15 @@ export function registerTaskHooks(hooks) {
                     const effectiveTaskId = options.taskId || `hook-${Date.now()}`;
                     const agent = options.agent || 'unknown';
                     const durationMs = options.duration ? parseInt(options.duration, 10) : 0;
+                    // ADR-101: provenance rides in the feedback string so the
+                    // learning loop can segment patterns per hierarchy level
+                    const provenanceSuffix = (provenance.parentAgentId ? `, Parent: ${provenance.parentAgentId}` : '') +
+                        (provenance.depth !== undefined ? `, Depth: ${provenance.depth}` : '');
                     await reasoningBank.recordOutcome({
                         patternId: `task:${agent}:${effectiveTaskId}`,
                         success,
                         metrics: { executionTimeMs: durationMs },
-                        feedback: `Agent: ${agent}, Task: ${effectiveTaskId}`,
+                        feedback: `Agent: ${agent}, Task: ${effectiveTaskId}${provenanceSuffix}`,
                     });
                     // Stream B: full experience pipeline (captured_experiences,
                     // experience_applications + per-pattern fan-out, qe_trajectories
@@ -309,6 +378,8 @@ export function registerTaskHooks(hooks) {
                         agent,
                         durationMs,
                         success,
+                        parentAgentId: provenance.parentAgentId,
+                        depth: provenance.depth,
                     });
                     // Issue #460: when --agent arrives empty (Claude Code does not
                     // expose $TOOL_RESULT_agent_id in PostToolUse context), `agent`

package/dist/cli/commands/hooks-handlers/tool-loop-guardrail.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Agentic QE v3 - Tool-Loop Circuit Breaker (ADR-100)
+ *
+ * Detects consecutive failures of the same Bash command across hook
+ * invocations and breaks runaway retry loops: WARN at 3, BLOCK at 5.
+ * Advisory by default (the block is a strongly-worded recommendation in
+ * the hook output); `AQE_STRICT_TOOL_LOOP=1` upgrades the block to a
+ * PreToolUse deny.
+ *
+ * Mirrors the closed → open → half-open semantics of
+ * `src/coordination/circuit-breaker/domain-circuit-breaker.ts` (ADR-064),
+ * but persists state in a small JSON sidecar instead of process memory:
+ * every hook call is a fresh CLI process, so in-process state cannot see
+ * the previous invocation, and opening memory.db from pre-command would
+ * add DB-init latency to every Bash command. The sidecar is ephemeral
+ * guardrail state — safe to delete at any time, not a data store.
+ */
+export type ToolLoopVerdict = 'allow' | 'warn' | 'block';
+export interface ToolLoopCheck {
+    verdict: ToolLoopVerdict;
+    consecutiveFailures: number;
+    /** True when an open breaker is being given a probe attempt (half-open) */
+    halfOpen: boolean;
+    /** Human-readable guidance for warn/block verdicts */
+    hint?: string;
+}
+export interface ToolLoopGuardrailOptions {
+    /** Path of the JSON state sidecar */
+    statePath: string;
+    /** Consecutive failures before warning (default 3) */
+    warnThreshold?: number;
+    /** Consecutive failures before blocking (default 5) */
+    blockThreshold?: number;
+    /** An open breaker allows one probe attempt after this long (default 2 min) */
+    halfOpenAfterMs?: number;
+    /** Entries idle longer than this are pruned (default 30 min) */
+    staleAfterMs?: number;
+}
+export declare class ToolLoopGuardrail {
+    private readonly statePath;
+    private readonly warnThreshold;
+    private readonly blockThreshold;
+    private readonly halfOpenAfterMs;
+    private readonly staleAfterMs;
+    constructor(options: ToolLoopGuardrailOptions);
+    /**
+     * Normalize a command into a breaker key: whitespace-collapsed and
+     * length-capped so cosmetic differences don't split the failure count.
+     */
+    static signature(command: string): string;
+    /**
+     * Consult the breaker before a command runs (pre-command hook).
+     * Fail-open: any state-read problem yields 'allow'.
+     */
+    check(command: string, now?: number): ToolLoopCheck;
+    /**
+     * Record a command outcome (post-command hook). Success resets the
+     * breaker for that command; failure increments it. Fail-open on errors.
+     */
+    record(command: string, success: boolean, now?: number): void;
+    /** Whether strict mode upgrades the advisory block to a hook deny. */
+    static isStrict(env?: NodeJS.ProcessEnv): boolean;
+    private readState;
+    private writeState;
+}
+/**
+ * Guardrail bound to the project's `.agentic-qe/` directory — the shared
+ * instance used by the pre-command/post-command hooks.
+ */
+export declare function createProjectToolLoopGuardrail(projectRoot: string): ToolLoopGuardrail;
+//# sourceMappingURL=tool-loop-guardrail.d.ts.map

package/dist/cli/commands/hooks-handlers/tool-loop-guardrail.js

@@ -0,0 +1,142 @@
+/**
+ * Agentic QE v3 - Tool-Loop Circuit Breaker (ADR-100)
+ *
+ * Detects consecutive failures of the same Bash command across hook
+ * invocations and breaks runaway retry loops: WARN at 3, BLOCK at 5.
+ * Advisory by default (the block is a strongly-worded recommendation in
+ * the hook output); `AQE_STRICT_TOOL_LOOP=1` upgrades the block to a
+ * PreToolUse deny.
+ *
+ * Mirrors the closed → open → half-open semantics of
+ * `src/coordination/circuit-breaker/domain-circuit-breaker.ts` (ADR-064),
+ * but persists state in a small JSON sidecar instead of process memory:
+ * every hook call is a fresh CLI process, so in-process state cannot see
+ * the previous invocation, and opening memory.db from pre-command would
+ * add DB-init latency to every Bash command. The sidecar is ephemeral
+ * guardrail state — safe to delete at any time, not a data store.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class ToolLoopGuardrail {
+    statePath;
+    warnThreshold;
+    blockThreshold;
+    halfOpenAfterMs;
+    staleAfterMs;
+    constructor(options) {
+        this.statePath = options.statePath;
+        this.warnThreshold = options.warnThreshold ?? 3;
+        this.blockThreshold = options.blockThreshold ?? 5;
+        this.halfOpenAfterMs = options.halfOpenAfterMs ?? 120_000;
+        this.staleAfterMs = options.staleAfterMs ?? 30 * 60_000;
+    }
+    /**
+     * Normalize a command into a breaker key: whitespace-collapsed and
+     * length-capped so cosmetic differences don't split the failure count.
+     */
+    static signature(command) {
+        return command.trim().replace(/\s+/g, ' ').slice(0, 200);
+    }
+    /**
+     * Consult the breaker before a command runs (pre-command hook).
+     * Fail-open: any state-read problem yields 'allow'.
+     */
+    check(command, now = Date.now()) {
+        const sig = ToolLoopGuardrail.signature(command);
+        if (!sig) {
+            return { verdict: 'allow', consecutiveFailures: 0, halfOpen: false };
+        }
+        const entry = this.readState()[sig];
+        if (!entry || entry.consecutiveFailures < this.warnThreshold) {
+            return { verdict: 'allow', consecutiveFailures: entry?.consecutiveFailures ?? 0, halfOpen: false };
+        }
+        const failures = entry.consecutiveFailures;
+        if (failures >= this.blockThreshold) {
+            // Open breaker: allow a single probe once the half-open window elapses
+            if (now - entry.lastFailureAt >= this.halfOpenAfterMs) {
+                return {
+                    verdict: 'warn',
+                    consecutiveFailures: failures,
+                    halfOpen: true,
+                    hint: `This command has failed ${failures}x consecutively; allowing one probe attempt. ` +
+                        `If it fails again it will be flagged immediately.`,
+                };
+            }
+            return {
+                verdict: 'block',
+                consecutiveFailures: failures,
+                halfOpen: false,
+                hint: `The same command failed ${failures}x consecutively. Re-running it unchanged is ` +
+                    `unlikely to succeed — inspect the error output, change the approach, or fix the ` +
+                    `underlying problem first. (A successful run resets this breaker.)`,
+            };
+        }
+        return {
+            verdict: 'warn',
+            consecutiveFailures: failures,
+            halfOpen: false,
+            hint: `This command has failed ${failures}x consecutively — consider changing approach before retrying.`,
+        };
+    }
+    /**
+     * Record a command outcome (post-command hook). Success resets the
+     * breaker for that command; failure increments it. Fail-open on errors.
+     */
+    record(command, success, now = Date.now()) {
+        const sig = ToolLoopGuardrail.signature(command);
+        if (!sig)
+            return;
+        try {
+            const state = this.readState();
+            if (success) {
+                if (state[sig]) {
+                    delete state[sig];
+                    this.writeState(state, now);
+                }
+                return;
+            }
+            const entry = state[sig] ?? { consecutiveFailures: 0, lastFailureAt: now };
+            entry.consecutiveFailures += 1;
+            entry.lastFailureAt = now;
+            state[sig] = entry;
+            this.writeState(state, now);
+        }
+        catch {
+            /* fail-open: guardrail must never break the hook */
+        }
+    }
+    /** Whether strict mode upgrades the advisory block to a hook deny. */
+    static isStrict(env = process.env) {
+        return env.AQE_STRICT_TOOL_LOOP === '1' || env.AQE_STRICT_TOOL_LOOP === 'true';
+    }
+    readState() {
+        try {
+            const raw = fs.readFileSync(this.statePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            return typeof parsed === 'object' && parsed !== null ? parsed : {};
+        }
+        catch {
+            return {}; // missing or corrupt sidecar → clean slate
+        }
+    }
+    writeState(state, now) {
+        // Prune stale entries so the sidecar stays small
+        for (const [key, entry] of Object.entries(state)) {
+            if (now - entry.lastFailureAt > this.staleAfterMs) {
+                delete state[key];
+            }
+        }
+        fs.mkdirSync(path.dirname(this.statePath), { recursive: true });
+        fs.writeFileSync(this.statePath, JSON.stringify(state));
+    }
+}
+/**
+ * Guardrail bound to the project's `.agentic-qe/` directory — the shared
+ * instance used by the pre-command/post-command hooks.
+ */
+export function createProjectToolLoopGuardrail(projectRoot) {
+    return new ToolLoopGuardrail({
+        statePath: path.join(projectRoot, '.agentic-qe', 'tool-loop-state.json'),
+    });
+}
+//# sourceMappingURL=tool-loop-guardrail.js.map

package/dist/cli/index.js

@@ -120,6 +120,18 @@ async function autoInitialize() {
     context.persistentScheduler = createPersistentScheduler();
     context.queen = createQueenCoordinator(context.kernel, context.router, protocolExecutor, undefined);
     await context.queen.initialize();
+    // Bridge the CLI-initialized components into the MCP handlers' fleet state.
+    // The memory/agent/task/team/pipeline handlers are shared between the MCP
+    // server and the CLI and are guarded by isFleetInitialized(); without this
+    // bridge every CLI invocation failed with "Fleet not initialized" even
+    // after a successful auto-init (MCP-CLI parity).
+    const { adoptExternalFleet } = await import('../mcp/handlers/core-handlers.js');
+    adoptExternalFleet({
+        kernel: context.kernel,
+        queen: context.queen,
+        router: context.router,
+        workflowOrchestrator: context.workflowOrchestrator,
+    });
     context.initialized = true;
 }
 async function ensureInitializedStrict() {
@@ -241,6 +253,11 @@ registerLazyCommand(program, {
     description: 'Security scanning and URL validation',
     factory: () => import('./commands/security.js').then(m => m.createSecurityCommand(context, cleanupAndExit, ensureInitialized)),
 });
+registerLazyCommand(program, {
+    name: 'arena',
+    description: 'Competitive test-strategy tournaments (ADR-104)',
+    factory: () => import('./commands/arena.js').then(m => m.createArenaCommand(context, cleanupAndExit, ensureInitialized)),
+});
 registerLazyCommand(program, {
     name: 'code',
     description: 'Code intelligence analysis',