dual-brain 0.2.30 → 0.3.0

package/dist/src/wave-planner.js

@@ -0,0 +1,281 @@
+// Wave Planner — Layer 2 cognitive loop
+// Takes HEAD's deliberation output and produces structured wave-based execution plans.
+const TIER_COST = {
+    search: { tokens: 5000, time: '~10s' },
+    execute: { tokens: 20000, time: '~45s' },
+    think: { tokens: 15000, time: '~30s' },
+    review: { tokens: 10000, time: '~20s' },
+};
+let waveCounter = 0;
+function nextWaveId() { return `w-${Date.now().toString(36)}-${++waveCounter}`; }
+/** Plan waves from HEAD's deliberation output. */
+export function planWaves(deliberation, context = {}) {
+    const { situation = {}, uncertainties = [], result = {} } = deliberation;
+    const { files = [], priorDebriefs = [], diagnosticPatterns = [] } = context;
+    const depth = result.depth || 'light';
+    const blockers = uncertainties.filter((u) => u.confidence < 0.3);
+    const hasFragile = situation.risk === 'high' || situation.risk === 'critical';
+    const largeScope = situation.scope === 'large';
+    const priorBlockers = priorDebriefs.filter((d) => d.blockers?.length);
+    const waves = [];
+    const contingencies = [];
+    // Determine wave structure based on depth
+    if (depth === 'reflexive' || depth === 'light') {
+        waves.push(makeSingleWave(result, situation, files));
+    }
+    else if (depth === 'full') {
+        if (blockers.length) {
+            waves.push(makeReconWave(blockers, situation, files, priorBlockers));
+        }
+        waves.push(makeImplementWave(result, situation, files, largeScope, waves));
+        if (hasFragile) {
+            waves.push(makeVerifyWave(situation, files, waves));
+        }
+    }
+    else if (depth === 'deep') {
+        // Always start with recon for deep
+        waves.push(makeReconWave(blockers.length ? blockers : uncertainties, situation, files, priorBlockers));
+        // Plan wave
+        waves.push({
+            id: nextWaveId(),
+            phase: 'synthesize',
+            agents: [{
+                    tier: 'think',
+                    objective: `Synthesize recon findings into implementation plan for: ${result.action || situation.taskShape || 'task'}`,
+                    scope: files.slice(0, 10),
+                }],
+            dependsOn: [waves[0].id],
+            gateCondition: 'recon wave completed without escalation',
+            parallel: false,
+        });
+        // Implement wave
+        waves.push(makeImplementWave(result, situation, files, largeScope, waves));
+        // Verify wave
+        waves.push(makeVerifyWave(situation, files, waves));
+    }
+    // Force recon-first if blockers exist and first wave isn't recon
+    if (blockers.length && waves.length && waves[0].phase !== 'recon') {
+        const reconWave = makeReconWave(blockers, situation, files, priorBlockers);
+        waves.forEach(w => { if (!w.dependsOn.length)
+            w.dependsOn.push(reconWave.id); });
+        waves.unshift(reconWave);
+    }
+    // Build contingencies
+    if (largeScope) {
+        contingencies.push({
+            trigger: 'if wave 1 finds scope is larger than expected',
+            response: 'add-wave',
+            details: 'Split implementation into additional parallel waves by file group',
+        });
+    }
+    if (hasFragile) {
+        contingencies.push({
+            trigger: 'if implementation wave introduces regressions',
+            response: 'retry-different',
+            details: 'Re-approach with smaller incremental changes',
+        });
+    }
+    if (blockers.length) {
+        contingencies.push({
+            trigger: 'if recon cannot resolve uncertainty',
+            response: 'escalate',
+            details: 'Ask user for clarification before proceeding',
+        });
+    }
+    const agentCount = waves.reduce((n, w) => n + w.agents.length, 0);
+    const dominantTier = agentCount <= 1 ? (waves[0]?.agents[0]?.tier || 'search')
+        : waves.flatMap((w) => w.agents.map((a) => a.tier))
+            .sort((a, b) => (TIER_COST[b]?.tokens ?? 0) - (TIER_COST[a]?.tokens ?? 0))[0];
+    return {
+        waves,
+        rationale: buildRationale(depth, blockers, hasFragile, largeScope),
+        estimatedCost: { waves: waves.length, agents: agentCount, tier: dominantTier },
+        contingencies,
+    };
+}
+/** Decide if the remaining plan is still valid after a wave debrief. */
+export function shouldReplan(currentPlan, newDebrief) {
+    if (!newDebrief)
+        return false;
+    if (newDebrief.scopeChange === 'larger' || newDebrief.scopeChange === 'different')
+        return true;
+    if (newDebrief.pivotReason)
+        return true;
+    if (newDebrief.confidence !== undefined && newDebrief.confidence < 0.4)
+        return true;
+    // Check if blockers intersect with upcoming wave objectives
+    const blockersList = newDebrief.blockers;
+    if (blockersList?.length) {
+        const planWaves = currentPlan.waves;
+        const remaining = (planWaves ?? []).filter((w) => !w.completed);
+        for (const w of remaining) {
+            for (const agent of w.agents) {
+                for (const blocker of blockersList) {
+                    const bLower = (typeof blocker === 'string' ? blocker : blocker.description || '').toLowerCase();
+                    if (bLower && agent.objective.toLowerCase().includes(bLower.split(' ')[0]))
+                        return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+/** Produce a new plan incorporating what was learned. Preserves completed waves. */
+export function replan(currentPlan, waveSummary, originalDeliberation) {
+    const planWavesArr = (currentPlan.waves ?? []);
+    const completed = planWavesArr.filter((w) => w.completed);
+    const context = {
+        files: waveSummary.filesDiscovered || [],
+        priorDebriefs: [waveSummary],
+        diagnosticPatterns: waveSummary.patterns || [],
+    };
+    // Merge learning into deliberation
+    const updated = { ...originalDeliberation };
+    if (waveSummary.scopeChange === 'larger') {
+        updated.situation = { ...updated.situation, scope: 'large' };
+    }
+    if (waveSummary.confidence !== undefined) {
+        updated.result = { ...updated.result, confidence: waveSummary.confidence };
+    }
+    if (waveSummary.newUncertainties) {
+        updated.uncertainties = [
+            ...(updated.uncertainties || []),
+            ...waveSummary.newUncertainties,
+        ];
+    }
+    const newPlan = planWaves(updated, context);
+    // Preserve completed waves at the front
+    newPlan.waves = [...completed, ...newPlan.waves];
+    newPlan.rationale = `Replanned after wave debrief: ${waveSummary.pivotReason || waveSummary.scopeChange || 'confidence drop'}. ${newPlan.rationale}`;
+    return newPlan;
+}
+/** Rough cost estimate for a single wave. */
+export function estimateWaveCost(wave) {
+    let tokens = 0;
+    for (const agent of wave.agents) {
+        tokens += TIER_COST[agent.tier]?.tokens || 10000;
+    }
+    // Time: parallel agents overlap, sequential add up
+    const times = wave.agents.map((a) => parseInt(TIER_COST[a.tier]?.time) || 20);
+    const seconds = wave.parallel ? Math.max(...times) : times.reduce((s, t) => s + t, 0);
+    return { tokens, time: `~${seconds}s` };
+}
+function makeSingleWave(result, situation, files) {
+    const tier = mapActionToTier(result.action);
+    return {
+        id: nextWaveId(),
+        phase: tier === 'search' ? 'recon' : 'implement',
+        agents: [{
+                tier,
+                objective: situation.explicitAsk || situation.raw || (typeof result.action === 'string' ? result.action : result.action?.mode) || 'execute task',
+                scope: files.slice(0, 5),
+            }],
+        dependsOn: [],
+        parallel: false,
+    };
+}
+function makeReconWave(uncertainties, situation, files, priorBlockers) {
+    const avoidApproaches = priorBlockers.flatMap((d) => d.blockers?.map((b) => typeof b === 'string' ? b : b.approach) || []);
+    const agents = uncertainties.slice(0, 3).map((u) => {
+        const spec = {
+            tier: 'search',
+            objective: `Resolve uncertainty: ${u.claim || u.description || 'unknown'}`,
+            scope: files.slice(0, 5),
+        };
+        if (u.wouldChangeIf) {
+            spec.conditionalPivot = { if: u.wouldChangeIf, then: 'report finding and stop' };
+        }
+        return spec;
+    });
+    // If no uncertainties provided, add a general recon agent
+    if (!agents.length) {
+        agents.push({
+            tier: 'search',
+            objective: `Explore scope and structure for: ${situation.taskShape || 'task'}`,
+            scope: files.slice(0, 5),
+        });
+    }
+    // Annotate agents to avoid prior failed approaches
+    if (avoidApproaches.length) {
+        for (const agent of agents) {
+            agent.objective += ` (avoid: ${avoidApproaches.join(', ')})`;
+        }
+    }
+    return {
+        id: nextWaveId(),
+        phase: 'recon',
+        agents,
+        dependsOn: [],
+        gateCondition: undefined,
+        parallel: agents.length > 1,
+    };
+}
+function makeImplementWave(result, situation, files, largeScope, existingWaves) {
+    const dependsOn = existingWaves.length ? [existingWaves[existingWaves.length - 1].id] : [];
+    const agents = [];
+    if (largeScope && files.length > 3) {
+        // Split into parallel agents by file group
+        const groupSize = Math.ceil(files.length / 3);
+        for (let i = 0; i < files.length; i += groupSize) {
+            agents.push({
+                tier: 'execute',
+                objective: result.action || `Implement changes in file group ${Math.floor(i / groupSize) + 1}`,
+                scope: files.slice(i, i + groupSize),
+            });
+        }
+    }
+    else {
+        agents.push({
+            tier: 'execute',
+            objective: result.action || situation.taskShape || 'implement changes',
+            scope: files.slice(0, 10),
+        });
+    }
+    return {
+        id: nextWaveId(),
+        phase: 'implement',
+        agents,
+        dependsOn,
+        gateCondition: existingWaves.length ? 'prior wave completed successfully' : undefined,
+        parallel: agents.length > 1,
+    };
+}
+function makeVerifyWave(situation, files, existingWaves) {
+    const dependsOn = existingWaves.length ? [existingWaves[existingWaves.length - 1].id] : [];
+    return {
+        id: nextWaveId(),
+        phase: 'verify',
+        agents: [{
+                tier: 'review',
+                objective: `Verify changes are correct and safe${situation.risk === 'critical' ? ' — critical risk area' : ''}`,
+                scope: files.slice(0, 10),
+            }],
+        dependsOn,
+        gateCondition: 'implementation wave completed',
+        parallel: false,
+    };
+}
+function mapActionToTier(action) {
+    if (!action)
+        return 'execute';
+    const actionObj = action;
+    const a = (typeof action === 'string' ? action : `${actionObj.type || ''} ${actionObj.mode || ''}`).toLowerCase();
+    if (a.includes('search') || a.includes('find') || a.includes('look') || a.includes('explore'))
+        return 'search';
+    if (a.includes('review') || a.includes('check') || a.includes('verify'))
+        return 'review';
+    if (a.includes('think') || a.includes('plan') || a.includes('design') || a.includes('architect'))
+        return 'think';
+    return 'execute';
+}
+function buildRationale(depth, blockers, hasFragile, largeScope) {
+    const parts = [`Depth: ${depth}.`];
+    if (blockers.length)
+        parts.push(`${blockers.length} blocker(s) require recon first.`);
+    if (hasFragile)
+        parts.push('High-risk area — verification wave added.');
+    if (largeScope)
+        parts.push('Large scope — parallel agents where possible.');
+    return parts.join(' ');
+}
+//# sourceMappingURL=wave-planner.js.map

package/dist/src/wave-planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave-planner.js","sourceRoot":"","sources":["../../src/wave-planner.ts"],"names":[],"mappings":"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"}

package/hooks/head-guard.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# head-guard.sh — DEPRECATED. Replaced by head-guard.mjs.
+#
+# This file is kept for reference only. It never worked correctly because it
+# reads CLAUDE_TOOL_NAME from the environment, but Claude Code delivers tool
+# info via stdin JSON, not environment variables.
+#
+# The replacement (head-guard.mjs) reads stdin JSON, detects HEAD vs subagent
+# via `agent_id`, and returns the correct permissionDecision block format.
+#
+# Do not use this file. See hooks/head-guard.mjs instead.
+
+BLOCK_MSG='[dual-brain] HEAD cannot use this tool directly. Dispatch via: dual-brain go "task description"'
+
+# ── 1. Role check ────────────────────────────────────────────────────────────
+# Only enforce when the session has been explicitly marked as the HEAD agent.
+# If the env var is unset we allow everything (backward compat for non-dual-brain usage).
+
+if [[ -z "${DUAL_BRAIN_ROLE}" ]]; then
+    exit 0
+fi
+
+if [[ "${DUAL_BRAIN_ROLE}" != "head" ]]; then
+    # Work-agent session — no restrictions.
+    exit 0
+fi
+
+# ── 2. Tool name check ───────────────────────────────────────────────────────
+TOOL="${CLAUDE_TOOL_NAME:-}"
+
+# Block direct file-editing tools and Bash unconditionally for HEAD.
+# HEAD should use Read tool for reading and Agent (via dual-brain go) for all other work.
+case "${TOOL}" in
+    Edit|Write|NotebookEdit|Bash)
+        echo "${BLOCK_MSG}" >&2
+        exit 2
+        ;;
+esac
+
+# ── 3. Default: allow ────────────────────────────────────────────────────────
+exit 0

package/hooks/task-classifier.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * task-classifier.mjs — Analyze work descriptions and return model + effort + mode config.
+ *
+ * Uses model-registry capabilities to make informed routing decisions:
+ * - Which model (per provider) handles this task best
+ * - What effort/reasoning level to use
+ * - Whether to enable extended thinking, fast mode, extended context, web search
+ * - How to dispatch (Claude Agent vs Codex exec)
+ *
+ * Exports: classifyTask, selectModelEffort, INTENTS
+ * CLI:     node hooks/task-classifier.mjs "description" [--files a,b] [--budget-pressure 0.8]
+ */
+
+import { classifyRisk, extractPaths } from './risk-classifier.mjs';
+import {
+  MODEL_CAPABILITIES, getCapabilities, getDispatchConfig,
+  recommendEffort, shouldUseExtendedContext, shouldUseFastMode,
+  getBestModelFor,
+} from './model-registry.mjs';
+
+// ─── Intent definitions ───────────────────────────────────────────────────────
+
+const INTENTS = {
+  search:       /\b(grep|find|locate|where is|where are|list|explore|read|look up|look for|check|what is|show me|display)\b/i,
+  explain:      /\b(explain|walk me through|what does|how does|describe|summarize|understand|clarify)\b/i,
+  compare:      /\b(compare|contrast|difference|versus|vs\.?|trade.?off|which is better|pros and cons|benchmark|performance)\b/i,
+  document:     /\b(document|docs?|readme|jsdoc|typedoc|api docs|write docs|add docs|update docs)\b/i,
+  format:       /\b(format|lint|prettier|style|indent|whitespace|typo|typos|comment[s]?|reformat)\b/i,
+  planning:     /\b(plan|roadmap|strategy|prioritize|break down|decompose|prioritise)\b/i,
+  architecture: /\b(design|architect|architecture|propose|how should we|system design|system architecture)\b/i,
+  security:     /\b(auth|credential|secret|token|password|encrypt|permission[s]?|vulnerability|vulnerabilities|CVE|oauth|jwt|api.?key)\b/i,
+  review:       /\b(review|audit|check for issues|evaluate|assess|inspect code|code review)\b/i,
+  debug:        /\b(debug|investigate|why (is|does|isn't|doesn't)|trace|diagnose|figure out|broken|not working|failing|regression)\b/i,
+  test:         /\b(test[s]?|spec[s]?|add test|fix test|test coverage|unit test|e2e|integration test|jest|vitest|mocha)\b/i,
+  refactor:     /\b(refactor|restructure|reorganize|reorganise|extract|split|consolidate|clean up|cleanup|dedupe|dedup)\b/i,
+  edit:         /\b(fix|add|update|modify|change|rename|move|replace|write|implement|create|remove|delete|insert)\b/i,
+};
+
+const INTENT_PRIORITY = [
+  'security', 'architecture', 'planning', 'compare', 'review',
+  'debug', 'refactor', 'test', 'explain', 'document', 'format', 'search', 'edit',
+];
+
+// ─── Risk keyword detection (description-level) ──────────────────────────────
+
+const RISK_KEYWORDS = [
+  { level: 'critical', regex: /\b(auth|secret|credential|token|password|encrypt|certificate|oauth|jwt|api.?key|vulnerability|CVE)\b/i },
+  { level: 'high',     regex: /\b(billing|payment|migration|deploy|ci.?cd|security|permission|policy|schema|openapi|swagger|production|prod)\b/i },
+  { level: 'medium',   regex: /\b(test|spec|config|shared|util|lib|integration|public.?api)\b/i },
+  { level: 'low',      regex: /\b(readme|docs?|comment|format|lint|changelog|typo|whitespace)\b/i },
+];
+
+const LEVEL_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
+
+function detectKeywordRisk(description) {
+  for (const { level, regex } of RISK_KEYWORDS) {
+    if (regex.test(description)) return level;
+  }
+  return 'low';
+}
+
+function higherRisk(a, b) {
+  return LEVEL_ORDER[a] >= LEVEL_ORDER[b] ? a : b;
+}
+
+// ─── classifyTask ─────────────────────────────────────────────────────────────
+
+function classifyTask(description, options = {}) {
+  const { files = [], priorFailures = 0 } = options;
+
+  // 1. Intent detection
+  let intent = 'edit';
+  for (const key of INTENT_PRIORITY) {
+    if (INTENTS[key].test(description)) {
+      intent = key;
+      break;
+    }
+  }
+
+  // 2. Risk detection
+  const allPaths = [...files, ...extractPaths(description)];
+  const pathRisk = allPaths.length > 0 ? classifyRisk(allPaths).level : 'low';
+  const keywordRisk = detectKeywordRisk(description);
+  const risk = higherRisk(pathRisk, keywordRisk);
+
+  // 3. File count
+  const fileCount = files.length;
+
+  // 4. Complexity detection
+  let complexity;
+  const isAmbiguous = description.length > 120 || /\b(and also|as well as|plus|additionally|also)\b/i.test(description);
+
+  if (priorFailures >= 2 || intent === 'architecture' || risk === 'critical' || fileCount >= 6 || isAmbiguous && risk === 'critical') {
+    complexity = 'complex';
+  } else if (fileCount >= 3 || intent === 'refactor' || intent === 'debug' || risk === 'high' || isAmbiguous) {
+    complexity = 'moderate';
+  } else if (fileCount <= 2 && (risk === 'low' || risk === 'medium')) {
+    if (intent === 'format' || fileCount <= 1 && risk === 'low') {
+      complexity = 'trivial';
+    } else {
+      complexity = 'simple';
+    }
+  } else {
+    complexity = 'moderate';
+  }
+
+  // 5. Effort selection
+  const baseEffort = { trivial: 'low', simple: 'medium', moderate: 'high', complex: 'high' }[complexity];
+  const effortOrder = ['low', 'medium', 'high', 'xhigh'];
+
+  function bumpEffort(e, n = 1) {
+    return effortOrder[Math.min(effortOrder.indexOf(e) + n, effortOrder.length - 1)];
+  }
+
+  let effort = baseEffort;
+
+  if (risk === 'critical' && LEVEL_ORDER[effort] < LEVEL_ORDER['high']) effort = 'high';
+
+  if (priorFailures >= 2) {
+    effort = 'xhigh';
+  } else if (priorFailures === 1) {
+    effort = bumpEffort(effort, 1);
+  }
+
+  if (intent === 'format' || intent === 'search') {
+    if (LEVEL_ORDER[effort] > LEVEL_ORDER['medium']) effort = 'medium';
+  }
+  if ((intent === 'architecture' || intent === 'security') && LEVEL_ORDER[effort] < LEVEL_ORDER['high']) {
+    effort = 'high';
+  }
+
+  // 6. Reason
+  const reasons = [];
+  if (fileCount > 0) reasons.push(`${fileCount} file(s)`);
+  if (risk !== 'low') reasons.push(`${risk} risk`);
+  if (priorFailures > 0) reasons.push(`${priorFailures} prior failure(s)`);
+  reasons.push(`intent=${intent}, complexity=${complexity}`);
+  const reason = reasons.join('; ');
+
+  return { intent, risk, complexity, fileCount, effort, reason };
+}
+
+// ─── selectModelEffort ────────────────────────────────────────────────────────
+
+function selectModelEffort(taskProfile, options = {}) {
+  const { budgetPressure = 0, userBudgetTier = '$100', isIterating = false, estimatedTokens = 0 } = options;
+  const { intent, risk, effort, complexity } = taskProfile;
+
+  // ── Intent classification for routing ──
+  const thinkIntents = ['architecture', 'security', 'review', 'planning', 'compare'];
+  const searchIntents = ['search', 'format', 'explain'];
+  const lightIntents = ['document', 'explain', 'format', 'search'];
+
+  const needsOpus = thinkIntents.includes(intent)
+    || risk === 'critical'
+    || effort === 'xhigh';
+
+  const needsHaiku = searchIntents.includes(intent) && effort === 'low';
+
+  let claudeModel = needsOpus ? 'opus' : needsHaiku ? 'haiku' : 'sonnet';
+
+  // ── Claude effort (from registry, null-safe for haiku) ──
+  const caps = getCapabilities(claudeModel);
+  let claudeEffort = caps?.reasoning?.effortLevels
+    ? (recommendEffort(claudeModel, complexity, risk) || effort)
+    : null;
+
+  // ── Claude modes ──
+  const claudeModes = {
+    extendedThinking: caps?.reasoning?.extendedThinking
+      && (complexity === 'moderate' || complexity === 'complex')
+      && !lightIntents.includes(intent),
+    fastMode: shouldUseFastMode(claudeModel, isIterating),
+    extendedContext: shouldUseExtendedContext(claudeModel, estimatedTokens),
+    ultrathink: claudeModel === 'opus'
+      && (risk === 'critical' || (complexity === 'complex' && thinkIntents.includes(intent))),
+  };
+
+  // ── OpenAI model selection (all models reachable) ──
+  let openaiModel;
+  if (needsOpus) {
+    openaiModel = 'gpt-5.5';
+  } else if (searchIntents.includes(intent) && effort === 'low') {
+    openaiModel = 'gpt-4.1-mini';
+  } else if (['edit', 'test', 'document'].includes(intent) && ['simple', 'trivial'].includes(complexity)) {
+    openaiModel = 'gpt-4.1';
+  } else if (intent === 'explain' && complexity !== 'trivial') {
+    openaiModel = 'gpt-5.2';
+  } else if (['edit', 'document'].includes(intent) && complexity === 'moderate') {
+    openaiModel = 'gpt-5.3-codex';
+  } else if (intent === 'test' && complexity === 'moderate') {
+    openaiModel = 'gpt-5.4-mini';
+  } else if (['refactor', 'debug'].includes(intent)) {
+    openaiModel = complexity === 'complex' ? 'gpt-5.4' : 'gpt-5.3-codex';
+  } else {
+    openaiModel = 'gpt-5.4';
+  }
+
+  // ── OpenAI effort (from registry) ──
+  let openaiEffort = recommendEffort(openaiModel, complexity, risk) || effort;
+
+  // ── OpenAI modes ──
+  const openaiCaps = getCapabilities(openaiModel);
+  const openaiModes = {
+    webSearch: openaiCaps?.modes?.webSearch ?? false,
+    sandbox: openaiCaps?.modes?.sandbox?.[
+      thinkIntents.includes(intent) ? 'think' : searchIntents.includes(intent) ? 'search' : 'execute'
+    ] ?? 'danger-full-access',
+  };
+
+  // ── Outcome learning override ──
+  // If we have enough empirical data, let it influence model selection
+  const empiricalClaude = getBestModelFor(intent, 'claude', { minSamples: 5 });
+  if (empiricalClaude && empiricalClaude.successRate !== null && empiricalClaude.successRate > 0.8) {
+    const caps = getCapabilities(empiricalClaude.model);
+    if (caps && !caps.avoidFor?.includes(intent)) {
+      claudeModel = empiricalClaude.model;
+    }
+  }
+
+  const empiricalOpenai = getBestModelFor(intent, 'openai', { minSamples: 5 });
+  if (empiricalOpenai && empiricalOpenai.successRate !== null && empiricalOpenai.successRate > 0.8) {
+    const caps = getCapabilities(empiricalOpenai.model);
+    if (caps && !caps.avoidFor?.includes(intent)) {
+      openaiModel = empiricalOpenai.model;
+    }
+  }
+
+  // ── Budget pressure adjustments ──
+  const reasons = [];
+  const isHighStakes = risk === 'critical' || risk === 'high';
+  const openaiModelRank = [
+    'gpt-4.1-mini', 'gpt-4.1', 'gpt-5.2', 'gpt-5.4-mini',
+    'gpt-5.3-codex', 'gpt-5.3-codex-spark', 'gpt-5.4', 'gpt-5.5',
+  ];
+
+  if (budgetPressure > 0.9 && !isHighStakes) {
+    claudeModel = claudeModel === 'opus' ? 'sonnet' : 'haiku';
+    const oaiIdx = openaiModelRank.indexOf(openaiModel);
+    openaiModel = openaiModelRank[Math.max(0, oaiIdx - 2)] || 'gpt-4.1-mini';
+    claudeModes.fastMode = false;
+    claudeModes.extendedContext = false;
+    claudeModes.extendedThinking = false;
+    reasons.push('near limit, aggressive downgrade for non-critical task');
+  } else if (budgetPressure > 0.7 && !isHighStakes) {
+    claudeModel = claudeModel === 'opus' ? 'sonnet' : claudeModel === 'sonnet' ? 'haiku' : 'haiku';
+    const oaiIdx = openaiModelRank.indexOf(openaiModel);
+    openaiModel = openaiModelRank[Math.max(0, oaiIdx - 1)] || 'gpt-4.1-mini';
+    claudeModes.fastMode = false;
+    reasons.push('downgraded due to budget pressure');
+  }
+
+  // Recalculate efforts after potential model change
+  const newCaps = getCapabilities(claudeModel);
+  claudeEffort = newCaps?.reasoning?.effortLevels
+    ? (recommendEffort(claudeModel, complexity, risk) || effort)
+    : null;
+  openaiEffort = recommendEffort(openaiModel, complexity, risk) || effort;
+
+  // ── Preferred provider (think→claude, isolated execute→openai) ──
+  const preferred = thinkIntents.includes(intent) ? 'claude' : 'openai';
+
+  // ── Dual-brain recommendation ──
+  const dualBrain = risk === 'critical'
+    || (thinkIntents.includes(intent) && (complexity === 'complex' || complexity === 'moderate'))
+    || intent === 'security'
+    || (intent === 'review' && risk !== 'low')
+    || (intent === 'refactor' && risk === 'critical');
+
+  if (reasons.length === 0) {
+    reasons.push(`${claudeModel}/${openaiModel} matched to ${intent} @ ${complexity} complexity`);
+  }
+  if (empiricalClaude?.successRate !== null) reasons.push(`claude empirical: ${empiricalClaude.model} ${Math.round(empiricalClaude.successRate * 100)}%`);
+  if (empiricalOpenai?.successRate !== null) reasons.push(`openai empirical: ${empiricalOpenai.model} ${Math.round(empiricalOpenai.successRate * 100)}%`);
+
+  return {
+    claude: {
+      model: claudeModel,
+      effort: claudeEffort,
+      modes: claudeModes,
+      dispatch: getDispatchConfig(claudeModel),
+    },
+    openai: {
+      model: openaiModel,
+      effort: openaiEffort,
+      modes: openaiModes,
+      dispatch: getDispatchConfig(openaiModel),
+    },
+    preferred,
+    dualBrain,
+    reason: reasons.join('; '),
+  };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
+  const args = process.argv.slice(2);
+  const description = args.find(a => !a.startsWith('--')) || '';
+  const filesArg = args.find(a => a.startsWith('--files=')) || args[args.indexOf('--files') + 1];
+  const budgetArg = args.find(a => a.startsWith('--budget-pressure=')) || args[args.indexOf('--budget-pressure') + 1];
+  const failuresArg = args.find(a => a.startsWith('--failures=')) || args[args.indexOf('--failures') + 1];
+
+  const files = (filesArg && !filesArg.startsWith('--'))
+    ? filesArg.replace(/^--files=/, '').split(',').map(f => f.trim())
+    : [];
+
+  const budgetPressure = budgetArg
+    ? parseFloat(budgetArg.replace(/^--budget-pressure=/, ''))
+    : 0;
+
+  const priorFailures = failuresArg
+    ? parseInt(failuresArg.replace(/^--failures=/, ''), 10)
+    : 0;
+
+  if (!description) {
+    console.error('Usage: node hooks/task-classifier.mjs "task description" [--files a,b] [--budget-pressure 0.8] [--failures 1]');
+    process.exit(1);
+  }
+
+  const profile = classifyTask(description, { files, priorFailures });
+  const selection = selectModelEffort(profile, { budgetPressure });
+
+  console.log(JSON.stringify({ profile, selection }, null, 2));
+}
+
+export { classifyTask, selectModelEffort, INTENTS };