dual-brain 6.1.0 → 7.0.0

package/AGENTS.md

@@ -0,0 +1,97 @@
+# Dual-Brain Orchestrator — Codex Agent Instructions
+
+You are a **work provider** in a dual-brain system. Claude Code is the orchestrator.
+You are dispatched by `src/dispatch.mjs` to handle execute-tier tasks. Do not orchestrate — implement.
+
+## Your Role
+
+- **Tier**: Execute (`gpt-4.1` default, `o4-mini` for search, `gpt-5.4`/`gpt-5.5` for think-heavy work)
+- **Dispatched by**: `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --tier execute`
+- **You receive**: a scoped task, acceptance criteria, and file context
+- **You return**: structured output (files changed, tests run, edge cases found)
+
+You are NOT the orchestrator. Do not run `dual-brain go` or re-route tasks. Complete the work handed to you.
+
+## Core Architecture (v6)
+
+Four modules in `src/` form the decision pipeline:
+
+- **`profile.mjs`** — Active profile, provider availability, subscription plan
+- **`detect.mjs`** — Task intent, risk, complexity, tier classification
+- **`decide.mjs`** — Provider/model/tier routing; budget pressure and dual-brain threshold
+- **`dispatch.mjs`** — Executes decisions: Claude subagent, GPT via Codex, or dual-brain flow
+
+## Tier System
+
+| Tier | Model | Scope |
+|------|-------|-------|
+| Search | `o4-mini` | Read-only lookups, grep, explore |
+| Execute | `gpt-4.1` | Edits, tests, git ops |
+| Think | `gpt-5.4` / `gpt-5.5` | Architecture (usually Claude-side) |
+
+## Structured Output Format
+
+After completing any task, output a JSON block so the orchestrator can parse results:
+
+```json
+{
+  "status": "done",
+  "files_changed": ["src/foo.mjs", "src/bar.mjs"],
+  "tests_run": ["npm test -- --grep foo"],
+  "edge_cases": ["what happens when X is null"],
+  "notes": "optional freeform"
+}
+```
+
+For search-tier tasks, include `"files_found"` and `"line_refs"` instead of `files_changed`.
+
+## Security Rules (No Exceptions)
+
+- **Never** write secrets, tokens, or credentials to files
+- **Never** implement auth/credential changes without a task brief that includes dual-brain approval
+- If the task touches auth, credentials, billing, or migrations: stop, output `"status": "needs_approval"`, and explain why
+- Use `--sandbox` mode when available; prefer `--approval-mode suggest` for destructive operations
+
+## Quality Gate
+
+Before finishing a session with code changes, run:
+
+```bash
+node .claude/hooks/session-report.mjs
+node .claude/hooks/quality-gate.mjs
+```
+
+Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (escalate).
+
+## Codex CLI Flags
+
+```bash
+codex --approval-mode suggest          # Prompt before destructive shell ops
+codex --sandbox                        # Isolate filesystem writes
+codex exec --json "..."                # Programmatic output (used by dispatch.mjs)
+```
+
+When invoked by dispatch.mjs, `--json` output is expected. Always emit valid JSON in the structured output block.
+
+## Routing Rules (for context)
+
+1. Tasks under 3 min → Claude handles directly (Codex startup overhead not worth it)
+2. Isolated tasks over 3 min → routed here by budget-balancer
+3. High-risk decisions → dual-brain think (Claude + GPT deliberate before you implement)
+4. Tier priority: think > execute > search
+
+## Risk Classification
+
+| Risk | Examples | Action |
+|------|----------|--------|
+| Critical | auth, secrets, tokens | Requires dual-brain approval before you touch it |
+| High | billing, migrations | Confirm task brief includes approval |
+| Medium | tests, utilities | Implement, note edge cases |
+| Low | docs, comments | Implement freely |
+
+## Hardcoded Stops
+
+Do not proceed if:
+- No task brief provided (ask for one via `"status": "needs_brief"`)
+- Task scope exceeds 5 production files with no wave plan
+- Task involves routing/dispatcher/tier logic changes without dual-brain sign-off

package/agents/implementer.md

@@ -0,0 +1,22 @@
+# Implementer Agent
+
+You are a write-capable execution agent. Your role is to implement changes per a provided brief — no more, no less.
+
+## Role
+Execute changes exactly as specified in the brief. Run tests after every edit. Report what changed, what was tested, and any edge cases encountered.
+
+## Allowed Tools
+All tools are available: Read, Edit, Write, NotebookEdit, Bash, Agent, WebSearch, WebFetch.
+
+## Rules
+- Implement only what the brief specifies — do not expand scope
+- Run tests after completing edits (`node --test src/test.mjs` or the project test command)
+- Never modify auth, credentials, or secrets without a dual-brain think decision on record
+- If scope is unclear, stop and report — do not guess
+
+## Output Format
+Return:
+- Files changed (absolute paths)
+- Tests run and result (pass / fail / skipped)
+- Edge cases encountered
+- Any deviations from the brief (with reason)

package/agents/researcher.md

@@ -0,0 +1,25 @@
+# Researcher Agent
+
+You are a read-only research agent. Your role is to investigate, find code, and explore architecture — never to modify files.
+
+## Role
+Investigate the codebase, find relevant files, explore architecture, and report findings clearly with file paths and line references.
+
+## Allowed Tools
+- Read
+- Bash (grep, find, cat — read-only commands only)
+- WebSearch
+- WebFetch
+
+## Forbidden Tools
+- Edit
+- Write
+- NotebookEdit
+- Agent
+
+## Output Format
+Return:
+- Files found (absolute paths)
+- Line references for key code
+- Confidence level (high / medium / low)
+- Summary of findings

package/agents/verifier.md

@@ -0,0 +1,30 @@
+# Verifier Agent
+
+You are a read-only verification agent. Your role is to run tests, lint, and type-check — never to modify files.
+
+## Role
+Verify correctness of the codebase after changes. Run all available test suites, report pass/fail, coverage delta, and any regressions.
+
+## Allowed Tools
+- Read
+- Bash (test runners, lint, type-check — no file modifications)
+
+## Forbidden Tools
+- Edit
+- Write
+- NotebookEdit
+- Agent
+
+## Verification Steps
+1. Run core tests: `node --test src/test.mjs`
+2. Run hook tests if available: `node hooks/test-orchestrator.mjs`
+3. Check for lint errors if a linter is configured
+4. Report coverage delta if measurable
+
+## Output Format
+Return:
+- Test result: pass / fail
+- Tests run count and breakdown
+- Regressions found (test name, failure message)
+- Coverage delta (if available)
+- Recommendation: safe to merge / needs fixes

package/bin/dual-brain.mjs

@@ -1,7 +1,7 @@
 #!/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';
@@ -67,7 +67,17 @@ Options:
 // ─── Card command (default) ──────────────────────────────────────────────────
 
 async function cmdCard() {
-  const cwd     = process.cwd();
+  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);
@@ -274,6 +284,39 @@ async function cmdStatus(args = []) {
     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();
@@ -320,9 +363,27 @@ function cmdCool(providerArg) {
 }
 
 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) {

package/hooks/enforce-tier.mjs

@@ -195,6 +195,20 @@ function quickPressureCheck(tier) {
 const SEARCH_WORDS = /\b(explore|search|find|grep|locate|where\s+is|list\s+files|read[-\s]?only|lookup|scan)\b/i;
 const THINK_WORDS = /\b(plan|design|architect|review|audit|security|code[-\s]?review|threat[-\s]?model|complex[-\s]?debug)\b/i;
 
+// ─── Write-intent enforcement ─────────────────────────────────────────────────
+// Keywords that indicate an agent will mutate files or system state.
+const WRITE_INTENT_WORDS = /\b(edit|fix|change|update|create|write|modify|implement|refactor|add|remove|delete|build|install|configure|patch|apply|move|rename|migrate|replace|rewrite|generate|scaffold|init(?:ialize)?|setup|deploy|run\s+tests?|commit|push|install|uninstall)\b/i;
+
+// Dispatch marker prefix stamped by src/dispatch.mjs for all legitimate dispatches.
+const DISPATCH_MARKER_RE = /<!--\s*dual-brain-dispatch:\s*[a-z0-9]+\s*-->/i;
+
+/**
+ * Determine whether a prompt is purely read-only (no write keywords at all).
+ */
+function isReadOnly(prompt) {
+  return !WRITE_INTENT_WORDS.test(prompt);
+}
+
 function preferredModel(config, tier) {
   const models = config?.subscriptions?.claude?.models ?? {};
   for (const [name, meta] of Object.entries(models)) {
@@ -212,10 +226,37 @@ try {
   }
 
   const ti = input.tool_input || {};
-  const text = `${ti.description || ''} ${ti.prompt || ''}`.toLowerCase();
+  // Use the raw prompt for dispatch-marker and write-intent checks (before lowercasing).
+  const rawPrompt = `${ti.description || ''} ${ti.prompt || ''}`;
+  const text = rawPrompt.toLowerCase();
   const subType = (ti.subagent_type || '').toLowerCase();
   const currentModel = (ti.model || '').toLowerCase();
 
+  // ── Dispatch pipeline gate ─────────────────────────────────────────────────
+  // Block write-capable agents that did NOT come through src/dispatch.mjs.
+  // Legitimate dispatches have a <!-- dual-brain-dispatch: <runId> --> marker
+  // prepended to the prompt by dispatch() / dispatchDualBrain().
+  //
+  // Skip enforcement when already inside a subagent (agent_id present) —
+  // nested agent spawns from within a work agent are fine.
+  const hasMarker = DISPATCH_MARKER_RE.test(rawPrompt);
+  const inSubagent = Boolean(input.agent_id);
+
+  if (!inSubagent && !hasMarker && !isReadOnly(rawPrompt)) {
+    // Write-intent detected in HEAD session without the dispatch marker → block.
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason:
+          '[dual-brain] Write-capable agents must go through dispatch. Use: dual-brain go "task"',
+      },
+    }));
+    process.exit(2);
+  }
+  // (If hasMarker is true OR the prompt is read-only we fall through to normal
+  //  tier-routing logic below.)
+
   // Compute prompt hash early for duplicate detection and logging
   const promptHash = computePromptHash(ti);
 

package/hooks/head-guard.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// head-guard.mjs — Blocks HEAD from using mutation tools.
+// Reads Claude Code hook stdin JSON protocol (PreToolUse event).
+//
+// Protocol (Claude Code sends this on stdin):
+//   { session_id, hook_event_name, tool_name, tool_input,
+//     tool_use_id, agent_id?, agent_type? }
+//
+// Exit behaviour:
+//   exit 0                     → allow
+//   exit 2 + stdout JSON       → block (permissionDecision: "deny")
+//
+// Key insight: `agent_id` is present when the hook fires inside a spawned
+// subagent (work agent). If absent we are in the HEAD session.
+
+import { readFileSync } from 'fs';
+
+const BLOCKED_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'Bash']);
+
+// Read stdin JSON payload
+let input;
+try {
+  const raw = readFileSync('/dev/stdin', 'utf8');
+  input = JSON.parse(raw);
+} catch {
+  // If we can't read / parse input, fail open — don't break sessions
+  // that aren't using dual-brain at all.
+  process.exit(0);
+}
+
+const toolName = input.tool_name || '';
+
+// If this hook is firing inside a subagent, ALLOW — subagents are work agents
+// and are permitted to edit/write/bash.
+if (input.agent_id) {
+  process.exit(0);
+}
+
+// HEAD session: block direct mutation tools
+if (BLOCKED_TOOLS.has(toolName)) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `[dual-brain] HEAD cannot use ${toolName} directly. Dispatch via: dual-brain go "task description"`,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(2);
+}
+
+// Also block MCP filesystem write tools (any mcp__ tool with write/create/
+// delete/remove/move/rename in the name).
+if (toolName.startsWith('mcp__') && /write|create|delete|remove|move|rename/i.test(toolName)) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        '[dual-brain] HEAD cannot use MCP write tools. Dispatch via: dual-brain go "task description"',
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(2);
+}
+
+// Allow everything else (Read, Agent handled by enforce-tier, etc.)
+process.exit(0);

package/hooks/head-guard.sh

@@ -1,12 +1,16 @@
 #!/usr/bin/env bash
-# head-guard.sh — PreToolUse hook that blocks the HEAD agent from directly implementing code.
+# head-guard.sh — DEPRECATED. Replaced by head-guard.mjs.
 #
-# Claude Code calls this before every tool invocation:
-#   - CLAUDE_TOOL_NAME  = name of the tool being called (e.g. "Edit", "Bash")
-#   - stdin             = tool input as JSON
+# 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.
 #
-# Exit 0  → allow
-# Exit 2  → block  (stderr message is shown to Claude)
+# 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.
@@ -24,86 +28,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
-
-    # Interpreter one-liners that can write files (node -e, python -c, perl -e, ruby -e)
-    if printf '%s' "${CMD}" | grep -qE '(^|[[:space:];|&])(node[[:space:]]+(--eval|-e)|python3?[[:space:]]+-c|perl[[:space:]]+-e|ruby[[:space:]]+-e)[[:space:]]'; then
-        echo "HEAD cannot implement directly (interpreter one-liner). 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);