dual-brain 6.0.1 → 6.1.1

package/bin/dual-brain.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // dual-brain — CLI entry point. Commands: init, go, status, remember, forget
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 
 import {
-  ensureProfile, loadProfile, runOnboarding,
+  ensureProfile, loadProfile, saveProfile, runOnboarding,
   rememberPreference, forgetPreference, getActivePreferences,
   getAvailableProviders, isSoloBrain, getHeadModel,
 } from '../src/profile.mjs';
@@ -15,11 +15,18 @@ import {
 import { detectTask } from '../src/detect.mjs';
 
 import {
-  decideRoute, getAvailableModels, estimateBudgetPressure,
+  decideRoute, getAvailableModels,
 } from '../src/decide.mjs';
 
+import {
+  getHealth, markHot, markHealthy, remainingCooldownMinutes, getSessionStats,
+} from '../src/health.mjs';
+
 import { dispatch, detectRuntime, dispatchDualBrain } from '../src/dispatch.mjs';
 
+import { loadRepoCache } from '../src/repo.mjs';
+import { loadSession, saveSession, formatSessionCard } from '../src/session.mjs';
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -30,6 +37,7 @@ function readVersion() {
 }
 function flag(args, name) { const i = args.indexOf(name); return i !== -1 ? (args[i + 1] ?? true) : null; }
 function err(msg) { process.stderr.write(`Error: ${msg}\n`); process.exit(1); }
+function vtrace(msg) { process.stderr.write(`[verbose] ${msg}\n`); }
 
 function printHelp() {
   console.log(`
@@ -41,20 +49,47 @@ Commands:
   go "task description"     Detect → decide → dispatch a task
     --dry-run               Show routing decision without executing
     --files a.mjs,b.mjs     Provide file context for risk classification
-  status                    Provider health, budget pressure, available models
+    --verbose, -v           Print routing trace (intent, risk, health, model selection)
+  status                    Provider health, session stats, available models
+    --verbose, -v           Also print profile file path and raw profile object
+  hot <provider>            Manually mark all model classes for provider as hot
+  cool <provider>           Manually clear hot state for a provider
   remember "preference"     Save a project-scoped preference
   forget "preference"       Remove a preference by fuzzy match
 
 Options:
   --version                 Print version
   --help                    Show this help
+  --verbose, -v             Enable verbose routing trace output (stderr)
 `.trim());
 }
 
+// ─── Card command (default) ──────────────────────────────────────────────────
+
+async function cmdCard() {
+  const cwd = process.cwd();
+  const { homedir } = await import('node:os');
+  const globalPath  = join(homedir(), '.config', 'dual-brain', 'profile.json');
+  const projectPath = join(cwd, '.dualbrain', 'profile.json');
+
+  if (!existsSync(projectPath) && !existsSync(globalPath)) {
+    console.log('Welcome to dual-brain! Let\'s set up your profile.\n');
+    await cmdInit();
+    return;
+  }
+
+  const repo    = loadRepoCache(cwd);
+  const session = loadSession(cwd);
+  const health  = getHealth(cwd);
+  const card    = formatSessionCard(session, repo, health);
+  console.log(card);
+}
+
 // ─── Commands ─────────────────────────────────────────────────────────────────
 
 async function cmdInit() {
   const profile = await runOnboarding({ interactive: true });
+  saveProfile(profile, { cwd: process.cwd() });
   const rt = await detectRuntime();
   const providers = getAvailableProviders(profile);
   const providerSummary = providers.length
@@ -65,14 +100,15 @@ async function cmdInit() {
 
 async function cmdGo(args) {
   const dryRun  = args.includes('--dry-run');
+  const verbose = args.includes('--verbose') || args.includes('-v');
   const filesRaw = flag(args, '--files');
   const files   = filesRaw && typeof filesRaw === 'string'
     ? filesRaw.split(',').map(f => f.trim()).filter(Boolean)
     : [];
 
   // prompt is the first non-flag argument (or value after --dry-run which is boolean)
-  const prompt = args.find(a => !a.startsWith('--') && a !== (filesRaw ?? ''));
-  if (!prompt) err('Usage: dual-brain go "task description" [--dry-run] [--files a,b]');
+  const prompt = args.find(a => !a.startsWith('--') && !a.startsWith('-') && a !== (filesRaw ?? ''));
+  if (!prompt) err('Usage: dual-brain go "task description" [--dry-run] [--files a,b] [--verbose]');
 
   const cwd     = process.cwd();
   const profile = await ensureProfile(cwd);
@@ -81,8 +117,44 @@ async function cmdGo(args) {
   // Print the one-sentence classification
   console.log(detection.explanation);
 
+  // Verbose: emit detection trace before routing decision
+  if (verbose) {
+    vtrace(`Intent: ${detection.intent} | Risk: ${detection.risk} | Complexity: ${detection.complexity} | Effort: ${detection.effort ?? 'n/a'}`);
+    vtrace(`Tier: ${detection.tier} | Files: ${detection.fileCount ?? files.length} | Requires write: ${detection.requiresWrite}`);
+  }
+
+  // Verbose: emit provider health scores before dispatch
+  if (verbose) {
+    const providers = getAvailableProviders(profile);
+    const { states } = getHealth(cwd);
+    const providerScores = ['claude', 'openai'].map(name => {
+      const enabled = providers.some(p => p.name === name);
+      if (!enabled) return `${name}=unavailable`;
+      // Find any state entry for this provider
+      const statuses = Object.entries(states)
+        .filter(([k]) => k.startsWith(`${name}:`))
+        .map(([, v]) => v.status);
+      const worst = statuses.includes('hot') ? 'hot'
+        : statuses.includes('probing') ? 'probing'
+        : statuses.includes('degraded') ? 'degraded'
+        : 'healthy';
+      return `${name}=${worst}`;
+    }).join(' ');
+    vtrace(`Provider health: ${providerScores}`);
+  }
+
   const decision = decideRoute({ profile, detection, cwd });
 
+  // Verbose: emit model selection and dual-brain rationale
+  if (verbose) {
+    const modelLabel = decision.effort ? `${decision.model} (${decision.effort})` : decision.model;
+    const modelStatus = getAvailableModels(profile)[decision.provider]?.includes(decision.model)
+      ? 'available, matches tier'
+      : 'selected';
+    vtrace(`Model selection: ${modelLabel} (${modelStatus})`);
+    vtrace(`Dual-brain: ${decision.dualBrain ? 'yes' : 'no'} (${isSoloBrain(profile) ? 'solo provider' : 'dual provider'}, ${detection.risk} risk)`);
+  }
+
   // Print routing table
   console.log(`  provider   : ${decision.provider}`);
   console.log(`  model      : ${decision.model}${decision.effort ? ' (' + decision.effort + ')' : ''}`);
@@ -102,38 +174,85 @@ async function cmdGo(args) {
     console.log(`\nConsensus: ${result.consensus}`);
     if (result.claude?.summary) console.log(`Claude : ${result.claude.summary}`);
     if (result.openai?.summary) console.log(`OpenAI : ${result.openai.summary}`);
+    // Save session state
+    saveSession({
+      objective:    prompt,
+      branch:       null,
+      filesChanged: files,
+      commandsRun:  [`dual-brain go "${prompt}"`],
+      lastResult:   { status: 'success', summary: result.consensus || 'dual-brain complete' },
+      provider:     decision.provider,
+      nextAction:   null,
+    }, cwd);
   } else {
     result = await dispatch({ decision, prompt, files, cwd });
     const statusLine = result.status === 'completed' ? 'Done' : `Failed (exit ${result.exitCode})`;
     console.log(`\n${statusLine} in ${(result.durationMs / 1000).toFixed(1)}s`);
     if (result.summary) console.log(result.summary);
     if (result.error)   process.stderr.write(`${result.error}\n`);
-    if (result.status !== 'completed') process.exit(1); }
+    // Save session state regardless of success/failure
+    saveSession({
+      objective:    prompt,
+      branch:       null,
+      filesChanged: files,
+      commandsRun:  [`dual-brain go "${prompt}"`],
+      lastResult:   {
+        status:  result.status === 'completed' ? 'success' : 'failure',
+        summary: result.summary || (result.status === 'completed' ? 'completed' : `exit ${result.exitCode}`),
+      },
+      provider:     decision.provider,
+      nextAction:   null,
+    }, cwd);
+    if (result.status !== 'completed') process.exit(1);
+  }
 }
 
-async function cmdStatus() {
+async function cmdStatus(args = []) {
+  const verbose = args.includes('--verbose') || args.includes('-v');
   const cwd     = process.cwd();
   const profile = loadProfile(cwd);
   const rt      = await detectRuntime();
   const providers = getAvailableProviders(profile);
-  const pressure  = estimateBudgetPressure(profile, cwd);
   const available = getAvailableModels(profile);
   const prefs     = getActivePreferences(cwd);
+  const { states } = getHealth(cwd);
+  const sessionStats = getSessionStats(cwd);
 
   console.log('=== Dual-Brain Status ===\n');
 
-  // Providers
+  // Providers + health
   console.log('Providers:');
   if (providers.length === 0) {
     console.log('  (none configured — run: dual-brain init)');
   } else {
     for (const p of providers) {
       const label = p.name === 'claude' ? 'Claude' : 'OpenAI';
-      const pct   = Math.round((pressure[p.name] ?? 0) * 100);
-      console.log(`  ${label}  plan=${p.plan}  budget=${pct}% used`);
+      // Collect all model-class states for this provider
+      const provStates = Object.entries(states)
+        .filter(([k]) => k.startsWith(`${p.name}:`));
+      const sess = sessionStats[p.name] ?? { calls: 0, tokens: 0 };
+
+      if (provStates.length === 0) {
+        console.log(`  ${label}  plan=${p.plan}  status=healthy  calls=${sess.calls}  tokens=${sess.tokens}`);
+      } else {
+        for (const [k, st] of provStates) {
+          const modelClass = k.split(':').slice(1).join(':');
+          let statusStr = st.status;
+          if (st.status === 'hot') {
+            const remaining = remainingCooldownMinutes(p.name, modelClass, cwd);
+            statusStr = remaining > 0 ? `hot (retry in ${remaining}m)` : 'hot (cooling)';
+          }
+          console.log(`  ${label}  plan=${p.plan}  model=${modelClass}  status=${statusStr}  calls=${sess.calls}  tokens=${sess.tokens}`);
+        }
+      }
     }
   }
 
+  // Session totals
+  const totalCalls  = Object.values(sessionStats).reduce((s, v) => s + v.calls, 0);
+  const totalTokens = Object.values(sessionStats).reduce((s, v) => s + v.tokens, 0);
+  console.log(`\nSession: ${totalCalls} dispatch${totalCalls !== 1 ? 'es' : ''}, ${totalTokens} tokens observed`);
+
   // Models
   console.log('\nAvailable models:');
   if (available.claude.length) console.log(`  Claude : ${available.claude.join(', ')}`);
@@ -154,20 +273,117 @@ async function cmdStatus() {
   console.log(`\nPreferences: ${prefs.length ? '' : '(none)'}`);
   for (const p of prefs) console.log(`  [${p.scope}] ${p.text}`);
 
+  // Verbose: profile file path and raw object
+  if (verbose) {
+    const { homedir } = await import('node:os');
+    const globalPath  = join(homedir(), '.config', 'dual-brain', 'profile.json');
+    const projectPath = join(cwd, '.dualbrain', 'profile.json');
+    const { existsSync } = await import('node:fs');
+    const loadedFrom = existsSync(projectPath) ? projectPath : existsSync(globalPath) ? globalPath : '(defaults)';
+    vtrace(`Profile file: ${loadedFrom}`);
+    vtrace(`Raw profile:\n${JSON.stringify(profile, null, 2)}`);
+  }
+
+  // Enforcement health check
+  console.log('\nEnforcement:');
+  try {
+    const { readFileSync: rfs, existsSync: exs } = await import('node:fs');
+    const settingsFile = join(cwd, '.claude', 'settings.json');
+    if (!exs(settingsFile)) {
+      console.log('  NOT INSTALLED — run: dual-brain install');
+    } else {
+      const settings = JSON.parse(rfs(settingsFile, 'utf8'));
+      const preToolUse = settings?.hooks?.PreToolUse ?? [];
+      const guardCmd  = 'bash .claude/hooks/head-guard.sh';
+      const tierCmd   = 'node .claude/hooks/enforce-tier.mjs';
+      const hasEdit   = preToolUse.some(e => e.matcher === 'Edit'   && e.hooks?.some(h => h.command === guardCmd));
+      const hasWrite  = preToolUse.some(e => e.matcher === 'Write'  && e.hooks?.some(h => h.command === guardCmd));
+      const hasBash   = preToolUse.some(e => e.matcher === 'Bash'   && e.hooks?.some(h => h.command === guardCmd));
+      const hasAgent  = preToolUse.some(e => e.matcher === 'Agent'  && e.hooks?.some(h => h.command === tierCmd));
+      const activeCount = [hasEdit, hasWrite, hasBash, hasAgent].filter(Boolean).length;
+      if (activeCount === 4) {
+        console.log(`  active (${activeCount} guards: Edit, Write, Bash, Agent)`);
+      } else {
+        const missing = [
+          !hasEdit  && 'Edit',
+          !hasWrite && 'Write',
+          !hasBash  && 'Bash',
+          !hasAgent && 'Agent',
+        ].filter(Boolean);
+        console.log(`  PARTIAL — missing guards: ${missing.join(', ')} — run: dual-brain install`);
+      }
+    }
+  } catch {
+    console.log('  unknown (could not read .claude/settings.json)');
+  }
+
   // Update check
   try {
     const localVer  = readVersion();
     const remoteVer = execSync('npm view dual-brain version 2>/dev/null', { timeout: 5000 }).toString().trim();
-    if (remoteVer && remoteVer !== localVer) {
-      console.log(`\nUpdate available: npm i -g dual-brain@latest  (${localVer} → ${remoteVer})`);
+    if (remoteVer) {
+      const localParts  = localVer.split('.').map(Number);
+      const remoteParts = remoteVer.split('.').map(Number);
+      const updateAvailable =
+        remoteParts[0] > localParts[0]
+        || (remoteParts[0] === localParts[0] && remoteParts[1] > localParts[1])
+        || (remoteParts[0] === localParts[0] && remoteParts[1] === localParts[1] && remoteParts[2] > localParts[2]);
+      if (updateAvailable) {
+        console.log(`\nUpdate available: npm i -g dual-brain@latest  (${localVer} → ${remoteVer})`);
+      }
     }
   } catch { /* network unavailable — skip */ }
 }
 
+// ─── cmdHot / cmdCool ─────────────────────────────────────────────────────────
+
+const PROVIDER_MODEL_CLASSES = {
+  claude: ['haiku', 'sonnet', 'opus'],
+  openai: ['o4-mini', 'o3', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-5.4', 'gpt-5.5'],
+};
+
+function cmdHot(providerArg) {
+  if (!providerArg) err('Usage: dual-brain hot <provider>  (claude | openai)');
+  const provider = providerArg.toLowerCase();
+  const classes  = PROVIDER_MODEL_CLASSES[provider];
+  if (!classes)  err(`Unknown provider: ${provider}. Use "claude" or "openai".`);
+  const cwd = process.cwd();
+  for (const mc of classes) markHot(provider, mc, cwd);
+  console.log(`Marked ${classes.length} model classes as hot for ${provider}.`);
+}
+
+function cmdCool(providerArg) {
+  if (!providerArg) err('Usage: dual-brain cool <provider>  (claude | openai)');
+  const provider = providerArg.toLowerCase();
+  const classes  = PROVIDER_MODEL_CLASSES[provider];
+  if (!classes)  err(`Unknown provider: ${provider}. Use "claude" or "openai".`);
+  const cwd = process.cwd();
+  for (const mc of classes) markHealthy(provider, mc, cwd);
+  console.log(`Cleared hot state for all ${provider} model classes.`);
+}
+
 async function cmdInstall() {
+  const cwd = process.cwd();
+
+  // Run the main install.mjs (orchestrator config, all hooks, CLAUDE.md, etc.)
   const { spawnSync } = await import('child_process');
-  const result = spawnSync('node', [join(__dirname, '..', 'install.mjs')], { stdio: 'inherit', cwd: process.cwd() });
-  process.exit(result.status || 0);
+  const result = spawnSync('node', [join(__dirname, '..', 'install.mjs')], { stdio: 'inherit', cwd });
+  if (result.status !== 0) { process.exit(result.status || 1); }
+
+  // Additionally merge enforcement hooks into .claude/settings.json
+  const { installHooks } = await import('../src/install-hooks.mjs');
+  const { installed, skipped } = installHooks(cwd);
+
+  if (installed.length > 0) {
+    console.log(`\nEnforcement hooks installed (${installed.length}):`);
+    for (const item of installed) console.log(`  + ${item}`);
+  }
+  if (skipped.length > 0) {
+    console.log(`Enforcement hooks already present (${skipped.length}):`);
+    for (const item of skipped) console.log(`  = ${item}`);
+  }
+
+  process.exit(0);
 }
 
 function cmdRemember(text) {
@@ -188,13 +404,16 @@ async function main() {
   const args = process.argv.slice(2);
   const cmd  = args[0];
 
-  if (!cmd || cmd === '--help' || cmd === '-h') { printHelp(); return; }
+  if (cmd === '--help' || cmd === '-h') { printHelp(); return; }
+  if (!cmd) { await cmdCard(); return; }
   if (cmd === '--version' || cmd === '-v')      { console.log(readVersion()); return; }
 
   if (cmd === 'init')     { await cmdInit(); return; }
   if (cmd === 'install')  { await cmdInstall(); return; }
   if (cmd === 'go')       { await cmdGo(args.slice(1)); return; }
-  if (cmd === 'status')   { await cmdStatus(); return; }
+  if (cmd === 'status')   { await cmdStatus(args.slice(1)); return; }
+  if (cmd === 'hot')      { cmdHot(args[1]); return; }
+  if (cmd === 'cool')     { cmdCool(args[1]); return; }
   if (cmd === 'remember') { cmdRemember(args[1]); return; }
   if (cmd === 'forget')   { cmdForget(args[1]); return; }
 

package/hooks/head-guard.sh

@@ -8,6 +8,8 @@
 # Exit 0  → allow
 # Exit 2  → block  (stderr message is shown to Claude)
 
+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).
@@ -24,80 +26,14 @@ fi
 # ── 2. Tool name check ───────────────────────────────────────────────────────
 TOOL="${CLAUDE_TOOL_NAME:-}"
 
-# Block direct file-editing tools unconditionally for HEAD.
+# 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)
-        echo "HEAD cannot implement directly. Use: node hooks/dispatch.mjs --task \"description\"" >&2
+    Edit|Write|NotebookEdit|Bash)
+        echo "${BLOCK_MSG}" >&2
         exit 2
         ;;
 esac
 
-# ── 3. Bash content check ────────────────────────────────────────────────────
-# For Bash calls, read stdin JSON and extract the "command" field, then scan for
-# write-side shell patterns. Pure bash + standard POSIX utilities — no node
-# startup, no network.
-
-if [[ "${TOOL}" == "Bash" ]]; then
-    # Read the full JSON input from stdin.
-    INPUT="$(cat)"
-
-    # Extract the value of "command" from the JSON.
-    # Strategy: grep for the key+value pair, then strip key prefix with sed.
-    # Handles normal ASCII command strings (not escaped unicode — acceptable for a guard).
-    CMD="$(printf '%s' "${INPUT}" \
-        | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
-        | head -1 \
-        | sed 's/^"command"[[:space:]]*:[[:space:]]*"//;s/"$//')"
-
-    # If we couldn't extract a command (unusual JSON shape), allow through.
-    if [[ -z "${CMD}" ]]; then
-        exit 0
-    fi
-
-    # ── Blocked patterns ─────────────────────────────────────────────────────
-
-    # sed with in-place flag (-i or combined flags like -ni)
-    if printf '%s' "${CMD}" | grep -qE '(^|[[:space:];|&])sed[[:space:]].*-[a-zA-Z]*i'; then
-        echo "HEAD cannot implement directly (sed -i). Use: node hooks/dispatch.mjs --task \"description\"" >&2
-        exit 2
-    fi
-
-    # Redirect-write: cat > file, echo > file, printf > file (single > only, not >>)
-    if printf '%s' "${CMD}" | grep -qE '(cat|echo|printf)[^|]*>[^>]'; then
-        echo "HEAD cannot implement directly (redirect write). Use: node hooks/dispatch.mjs --task \"description\"" >&2
-        exit 2
-    fi
-
-    # tee writing to a file path (tee /path or tee ./path or tee filename)
-    if printf '%s' "${CMD}" | grep -qE '(^|[[:space:];|&])tee[[:space:]]+[^-]'; then
-        echo "HEAD cannot implement directly (tee). Use: node hooks/dispatch.mjs --task \"description\"" >&2
-        exit 2
-    fi
-
-    # patch command
-    if printf '%s' "${CMD}" | grep -qE '(^|[[:space:];|&])patch[[:space:]]'; then
-        echo "HEAD cannot implement directly (patch). Use: node hooks/dispatch.mjs --task \"description\"" >&2
-        exit 2
-    fi
-
-    # mv / cp where the destination looks like a source code file
-    if printf '%s' "${CMD}" | grep -qE '(^|[[:space:];|&])(mv|cp)[[:space:]].*\.(js|mjs|cjs|ts|tsx|py|sh|json|yaml|yml|toml|rb|go|rs|java|c|cpp|h|css|html|sql)([[:space:]]|$)'; then
-        echo "HEAD cannot implement directly (mv/cp to source file). Use: node hooks/dispatch.mjs --task \"description\"" >&2
-        exit 2
-    fi
-
-    # rm on source files
-    if printf '%s' "${CMD}" | grep -qE '(^|[[:space:];|&])rm[[:space:]].*\.(js|mjs|cjs|ts|tsx|py|sh|json|yaml|yml|toml|rb|go|rs|java|c|cpp|h|css|html|sql)([[:space:]]|$)'; then
-        echo "HEAD cannot implement directly (rm on source file). Use: node hooks/dispatch.mjs --task \"description\"" >&2
-        exit 2
-    fi
-
-    # Explicitly allowed (read-only) patterns — documented here for clarity.
-    # The checks above are specific enough that these don't need explicit allow rules,
-    # but listing them makes the intent clear:
-    #   grep, find, cat <file (no redirect), git status/log/diff/show,
-    #   node --check, ls, wc, head, tail, jq (read), curl (read), etc.
-fi
-
-# ── 4. Default: allow ────────────────────────────────────────────────────────
+# ── 3. Default: allow ────────────────────────────────────────────────────────
 exit 0

package/install.mjs

@@ -744,39 +744,50 @@ function generateSettings(workspace) {
   let existing = {};
   try { existing = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch {}
 
-  const hooks = {
-    PreToolUse: [
-      {
-        matcher: 'Agent',
-        hooks: [{ type: 'command', command: 'node .claude/hooks/enforce-tier.mjs' }],
-      },
-    ],
-    PostToolUse: [
-      {
-        matcher: '',
-        hooks: [{ type: 'command', command: 'node .claude/hooks/cost-logger.mjs' }],
-      },
-      {
-        matcher: '',
-        hooks: [{ type: 'command', command: 'node .claude/hooks/auto-update-wrapper.mjs' }],
-      },
-    ],
-  };
+  const HEAD_GUARD_CMD = 'bash .claude/hooks/head-guard.sh';
+  const ENFORCE_TIER_CMD = 'node .claude/hooks/enforce-tier.mjs';
+
+  // All dual-brain PreToolUse hooks we manage
+  const DESIRED_PRE = [
+    { matcher: 'Edit',         command: HEAD_GUARD_CMD },
+    { matcher: 'Write',        command: HEAD_GUARD_CMD },
+    { matcher: 'NotebookEdit', command: HEAD_GUARD_CMD },
+    { matcher: 'Bash',         command: HEAD_GUARD_CMD },
+    { matcher: 'Agent',        command: ENFORCE_TIER_CMD },
+  ];
 
   const DUAL_BRAIN_CMDS = [
-    'node .claude/hooks/enforce-tier.mjs',
+    HEAD_GUARD_CMD,
+    ENFORCE_TIER_CMD,
     'node .claude/hooks/cost-logger.mjs',
     'node .claude/hooks/auto-update-wrapper.mjs',
   ];
 
-  const merged = { ...(existing.hooks || {}) };
-  for (const [event, entries] of Object.entries(hooks)) {
-    const existingEntries = (merged[event] || []).filter(e =>
-      !e.hooks?.some(h => DUAL_BRAIN_CMDS.includes(h.command))
-    );
-    merged[event] = [...existingEntries, ...entries];
+  // Build merged PreToolUse: keep user entries that aren't ours, then add ours
+  const existingPre = (existing.hooks?.PreToolUse || []).filter(e =>
+    !e.hooks?.some(h => DUAL_BRAIN_CMDS.includes(h.command))
+  );
+  const mergedPre = [...existingPre];
+  for (const { matcher, command } of DESIRED_PRE) {
+    mergedPre.push({ matcher, hooks: [{ type: 'command', command }] });
   }
 
+  // Build merged PostToolUse
+  const postHooks = [
+    { matcher: '', hooks: [{ type: 'command', command: 'node .claude/hooks/cost-logger.mjs' }] },
+    { matcher: '', hooks: [{ type: 'command', command: 'node .claude/hooks/auto-update-wrapper.mjs' }] },
+  ];
+  const existingPost = (existing.hooks?.PostToolUse || []).filter(e =>
+    !e.hooks?.some(h => DUAL_BRAIN_CMDS.includes(h.command))
+  );
+  const mergedPost = [...existingPost, ...postHooks];
+
+  const merged = {
+    ...(existing.hooks || {}),
+    PreToolUse: mergedPre,
+    PostToolUse: mergedPost,
+  };
+
   return { ...existing, hooks: merged };
 }
 
@@ -875,8 +886,8 @@ function install(workspace, env, mode) {
   ];
   for (const h of HOOKS) cpSync(join(__dirname, 'hooks', h), join(target, 'hooks', h));
 
-  // Copy bash hooks (auto-update.sh lives alongside .mjs hooks in the package)
-  const BASH_HOOKS = ['auto-update.sh'];
+  // Copy bash hooks (auto-update.sh and head-guard.sh live alongside .mjs hooks in the package)
+  const BASH_HOOKS = ['auto-update.sh', 'head-guard.sh'];
   for (const h of BASH_HOOKS) {
     const src = join(__dirname, 'hooks', h);
     const dst = join(target, 'hooks', h);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "6.0.1",
+  "version": "6.1.1",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -12,7 +12,14 @@
     "./profile": "./src/profile.mjs",
     "./detect": "./src/detect.mjs",
     "./decide": "./src/decide.mjs",
-    "./dispatch": "./src/dispatch.mjs"
+    "./dispatch": "./src/dispatch.mjs",
+    "./playbook": "./src/playbook.mjs",
+    "./health": "./src/health.mjs",
+    "./repo": "./src/repo.mjs",
+    "./session": "./src/session.mjs",
+    "./decompose": "./src/decompose.mjs",
+    "./brief": "./src/brief.mjs",
+    "./redact": "./src/redact.mjs"
   },
   "keywords": [
     "claude-code",
@@ -33,7 +40,7 @@
   "scripts": {
     "test": "node hooks/test-orchestrator.mjs",
     "test:core": "node --test src/test.mjs",
-    "postinstall": "node install.mjs"
+    "postinstall": "echo 'dual-brain installed. Run: dual-brain install (in your project) to set up hooks.'"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -49,6 +56,7 @@
     "review-rules.md",
     "CLAUDE.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "playbooks/*.json"
   ]
 }

package/playbooks/debug.json

@@ -0,0 +1,49 @@
+{
+  "name": "debug",
+  "description": "Structured bug resolution: reproduce, isolate, hypothesize root cause, fix minimally, verify with tests",
+  "matchIntents": ["debug", "fix"],
+  "steps": [
+    {
+      "id": "reproduce",
+      "title": "Reproduce the Failure",
+      "goal": "Find the failing code path. Identify the error message, stack trace, or unexpected behavior being reported. Locate the relevant source files, the entry point where the failure originates, and any existing tests that exercise this path. Confirm you understand the expected vs actual behavior.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "isolate",
+      "title": "Isolate the Root Cause",
+      "goal": "Narrow down the root cause to a specific file, function, or line range. Trace the data flow from the failing callsite back to where the incorrect value or state originates. Check recent git changes to this code path. Identify the single most likely source of the problem before moving on.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "hypothesize",
+      "title": "Form a Root Cause Hypothesis",
+      "goal": "Based on the isolated evidence, form a clear hypothesis about why the bug occurs. Consider: edge cases not handled, race conditions or ordering issues, incorrect assumptions about inputs or state, stale or shared mutable state, off-by-one errors, or API contract mismatches. State your hypothesis explicitly and explain what evidence supports it.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "fix",
+      "title": "Implement the Minimal Fix",
+      "goal": "Implement the smallest change that fixes the bug according to the hypothesis. Do not refactor surrounding code, rename things, or improve unrelated areas. If a regression test for this bug does not exist, add one. The fix should be easy to review and easy to revert if wrong.",
+      "tier": "execute",
+      "consensus": false,
+      "gate": { "type": "diff-review", "requiredWhen": "high-risk" },
+      "output": { "kind": "patch", "required": true }
+    },
+    {
+      "id": "verify",
+      "title": "Verify Fix and Check for Regressions",
+      "goal": "Run the full test suite. Confirm the bug is no longer reproducible. Confirm no previously passing tests now fail. If regressions are found, determine whether they are related to the fix or pre-existing. Summarize: the root cause in one sentence, the fix applied, and the test evidence that the bug is resolved.",
+      "tier": "execute",
+      "consensus": false,
+      "gate": { "type": "test", "requiredWhen": "always" },
+      "output": { "kind": "summary", "required": true }
+    }
+  ]
+}