create-merlin-brain 3.4.7 → 3.4.9

package/bin/install.cjs

@@ -176,14 +176,18 @@ function ensureDir(dir) {
   }
 }
 
-async function promptApiKey() {
+async function promptApiKey(hasExisting) {
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
   });
 
+  const prompt = hasExisting
+    ? `\n${colors.cyan}?${colors.reset} Merlin Sights API key (Enter to keep existing, or paste new): `
+    : `\n${colors.cyan}?${colors.reset} Merlin Sights API key (get one at ${colors.cyan}merlin.build${colors.reset}, Enter to skip): `;
+
   return new Promise((resolve) => {
-    rl.question(`\n${colors.cyan}?${colors.reset} Merlin Sights API key (press Enter to skip): `, (answer) => {
+    rl.question(prompt, (answer) => {
       rl.close();
       resolve(answer.trim());
     });
@@ -272,9 +276,9 @@ merlin-loop() {
     if (rcContent.includes('# Merlin Brain - The AI Brain') ||
         rcContent.includes('# Merlin Brain - Makes Claude Code') ||
         rcContent.includes('# Merlin Brain -')) {
-      // Remove old blocks
-      rcContent = rcContent.replace(/\n# ═+\n# Merlin Brain[\s\S]*?alias cc="claude"\n?/g, '');
-      rcContent = rcContent.replace(/\n# Merlin Brain - Makes Claude Code[\s\S]*?alias cc='claude'\n?/g, '');
+      // Remove old blocks (capture full block including trailing merlin-loop if present)
+      rcContent = rcContent.replace(/\n# ═+\n# Merlin Brain[\s\S]*?alias cc="claude"\n?([\s\S]*?merlin-loop\(\) \{[\s\S]*?\n\}\n)?/g, '');
+      rcContent = rcContent.replace(/\n# Merlin Brain - Makes Claude Code[\s\S]*?alias cc='claude'\n?([\s\S]*?merlin-loop\(\) \{[\s\S]*?\n\}\n)?/g, '');
       rcContent = rcContent.replace(/\n# Merlin - Claude Code with[\s\S]*?alias cc=.*\n?/g, '');
       fs.writeFileSync(rcFile, rcContent);
       logSuccess('Updating existing Merlin shell integration');
@@ -302,7 +306,7 @@ function cleanupLegacy() {
     const content = fs.readFileSync(claudeMdPath, 'utf8');
     if (content.includes('ccwiki_') || content.includes('briefed')) {
       fs.unlinkSync(claudeMdPath);
-      cleaned.push('~/.claude/CLAUDE.md (had old naming)');
+      cleaned.push('Removed ~/.claude/CLAUDE.md (had old naming)');
     }
   }
 
@@ -324,20 +328,27 @@ function cleanupLegacy() {
         let settings = JSON.parse(content);
 
         // Remove broken hooks (contain $HOME, gsd-, or old paths)
+        // Iterate ALL hook types, handle both old and new format
         if (settings.hooks) {
-          const hookTypes = ['PreToolUse', 'PostToolUse', 'Stop', 'Start'];
-          for (const hookType of hookTypes) {
+          for (const hookType of Object.keys(settings.hooks)) {
             if (Array.isArray(settings.hooks[hookType])) {
               const originalLength = settings.hooks[hookType].length;
-              settings.hooks[hookType] = settings.hooks[hookType].filter(hook => {
-                // Remove hooks with $HOME (doesn't work on Windows)
-                // Remove hooks with gsd- (old Get Shit Done)
-                // Remove hooks referencing non-existent files
-                const hookPath = typeof hook === 'string' ? hook : hook?.command || hook?.path || '';
-                if (hookPath.includes('$HOME') ||
-                    hookPath.includes('gsd-') ||
-                    hookPath.includes('ccwiki') ||
-                    hookPath.includes('briefed')) {
+              settings.hooks[hookType] = settings.hooks[hookType].filter(entry => {
+                // Extract command paths from both old and new format
+                let hookPaths = '';
+                if (entry.command) {
+                  // Old format: { type, command, ... }
+                  hookPaths = entry.command;
+                } else if (entry.hooks && Array.isArray(entry.hooks)) {
+                  // New format: { matcher?, hooks: [{ type, command }] }
+                  hookPaths = entry.hooks.map(h => h.command || h.path || '').join(' ');
+                } else if (typeof entry === 'string') {
+                  hookPaths = entry;
+                }
+                if (hookPaths.includes('$HOME') ||
+                    hookPaths.includes('gsd-') ||
+                    hookPaths.includes('ccwiki') ||
+                    hookPaths.includes('briefed')) {
                   return false;
                 }
                 return true;
@@ -359,13 +370,13 @@ function cleanupLegacy() {
 
         if (modified) {
           fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-          cleaned.push('~/.claude/settings.local.json (removed old tools and broken hooks)');
+          cleaned.push('Cleaned ~/.claude/settings.local.json (old tools and broken hooks)');
         }
       } catch (jsonErr) {
         // If JSON parsing fails, just do string replacement
         if (modified) {
           fs.writeFileSync(settingsPath, content);
-          cleaned.push('~/.claude/settings.local.json (removed old tools)');
+          cleaned.push('Cleaned ~/.claude/settings.local.json (old tools)');
         }
       }
     } catch (e) { /* ignore */ }
@@ -379,7 +390,7 @@ function cleanupLegacy() {
       // Remove old gsd-* hook files
       if (file.startsWith('gsd-') || file.includes('ccwiki') || file.includes('briefed')) {
         removeFile(path.join(hooksDir, file));
-        cleaned.push(`~/.claude/hooks/${file}`);
+        cleaned.push(`Removed ~/.claude/hooks/${file}`);
       }
     }
   }
@@ -424,7 +435,7 @@ function cleanupLegacy() {
 
       if (modified) {
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-        cleaned.push('~/.claude/config.json (migrated to global binary)');
+        cleaned.push('Migrated ~/.claude/config.json (to global binary)');
       }
     } catch (e) { /* ignore */ }
   }
@@ -470,7 +481,7 @@ function cleanupLegacy() {
 
       if (modified) {
         fs.writeFileSync(desktopConfigPath, JSON.stringify(config, null, 2));
-        cleaned.push('~/.claude/claude_desktop_config.json (migrated to global binary)');
+        cleaned.push('Migrated ~/.claude/claude_desktop_config.json (to global binary)');
       }
     } catch (e) { /* ignore */ }
   }
@@ -513,7 +524,7 @@ function cleanupLegacy() {
 
   for (const dir of dirsToRemove) {
     if (removeDirRecursive(dir)) {
-      cleaned.push(dir.replace(os.homedir(), '~'));
+      cleaned.push('Removed ' + dir.replace(os.homedir(), '~'));
     }
   }
 
@@ -543,7 +554,7 @@ function cleanupLegacy() {
 
   for (const file of filesToRemove) {
     if (removeFile(file)) {
-      cleaned.push(file.replace(os.homedir(), '~'));
+      cleaned.push('Removed ' + file.replace(os.homedir(), '~'));
     }
   }
 
@@ -565,7 +576,7 @@ function cleanupLegacy() {
     try {
       // Reset to empty object so Merlin auto-detects from git remote
       fs.writeFileSync(merlinConfigPath, '{}');
-      cleaned.push('~/.merlin/config.json (reset for auto-detect)');
+      cleaned.push('Reset ~/.merlin/config.json (for auto-detect)');
     } catch (e) { /* ignore */ }
   }
 
@@ -586,7 +597,7 @@ function cleanupLegacy() {
           claudeJson.mcpServers.merlin.command = 'merlin-brain';
           delete claudeJson.mcpServers.merlin.args;
           modified = true;
-          cleaned.push('~/.claude.json (migrated to global binary)');
+          cleaned.push('Migrated ~/.claude.json (to global binary)');
         }
       }
 
@@ -594,7 +605,7 @@ function cleanupLegacy() {
       if (claudeJson.mcpServers?.briefed) {
         delete claudeJson.mcpServers.briefed;
         modified = true;
-        cleaned.push('~/.claude.json (removed deprecated briefed server)');
+        cleaned.push('Removed deprecated briefed server from ~/.claude.json');
       }
 
       if (modified) {
@@ -622,7 +633,7 @@ function cleanupLegacy() {
         const pkgJsonPath2 = path.join(entryPath, 'node_modules', 'create-merlin-pro', 'package.json');
         if (fs.existsSync(pkgJsonPath) || fs.existsSync(pkgJsonPath2)) {
           removeDirRecursive(entryPath);
-          cleaned.push('~/.npm/_npx/' + entry.name + ' (old npx cache)');
+          cleaned.push('Removed ~/.npm/_npx/' + entry.name + ' (old npx cache)');
         }
       }
     }
@@ -639,12 +650,12 @@ function cleanupLegacy() {
       // Remove old gsd-*.md and ccwiki-*.md agents
       if ((file.startsWith('gsd-') || file.startsWith('ccwiki-')) && file.endsWith('.md')) {
         removeFile(path.join(agentsDir, file));
-        cleaned.push(`~/.claude/agents/${file}`);
+        cleaned.push(`Removed ~/.claude/agents/${file}`);
       }
       // Remove backup files in agents
       if (file.endsWith('.backup') || file.endsWith('.bak') || file.endsWith('.old') || file.endsWith('~')) {
         removeFile(path.join(agentsDir, file));
-        cleaned.push(`~/.claude/agents/${file}`);
+        cleaned.push(`Removed ~/.claude/agents/${file}`);
       }
     }
   }
@@ -709,7 +720,7 @@ function cleanupLegacy() {
 
       if (modified) {
         fs.writeFileSync(rcFile, content);
-        cleaned.push(rcFile.replace(os.homedir(), '~') + ' (removed old integrations)');
+        cleaned.push('Updated ' + rcFile.replace(os.homedir(), '~') + ' (removed old integrations)');
       }
     }
   }
@@ -734,7 +745,7 @@ async function install() {
   const cleaned = cleanupLegacy();
   if (cleaned.length > 0) {
     for (const item of cleaned) {
-      logSuccess(`Removed ${item}`);
+      logSuccess(item);
     }
   } else {
     logSuccess('No legacy artifacts found');
@@ -890,60 +901,83 @@ async function install() {
     }
     settings.hooks = settings.hooks || {};
 
-    const addHookIfMissing = (hookArray, hookConfig) => {
-      const exists = hookArray.some(h => h.command === hookConfig.command);
-      if (!exists) hookArray.push(hookConfig);
+    // ═══════════════════════════════════════════════════════════════
+    // MIGRATE old-format hooks to new format (matcher + hooks array)
+    // Old: { type, command, matcher?, prompt? }
+    // New: { matcher?, hooks: [{ type, command, prompt? }] }
+    // ═══════════════════════════════════════════════════════════════
+    for (const [eventName, entries] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(entries)) continue;
+      settings.hooks[eventName] = entries.map(entry => {
+        // Already in new format (has hooks array)
+        if (entry.hooks && Array.isArray(entry.hooks)) return entry;
+        // Old format → convert to new format
+        const handler = {};
+        if (entry.type) handler.type = entry.type;
+        if (entry.command) handler.command = entry.command;
+        if (entry.prompt) handler.prompt = entry.prompt;
+        if (entry.timeout !== undefined) handler.timeout = entry.timeout;
+        if (entry.async !== undefined) handler.async = entry.async;
+        if (entry.statusMessage) handler.statusMessage = entry.statusMessage;
+        const newEntry = {};
+        if (entry.matcher) newEntry.matcher = entry.matcher;
+        newEntry.hooks = [handler];
+        return newEntry;
+      });
+    }
+
+    // Helper: check if a command hook already exists in an array (new format)
+    const addHookIfMissing = (hookArray, matcherGroup) => {
+      const cmd = matcherGroup.hooks?.[0]?.command;
+      if (!cmd) { hookArray.push(matcherGroup); return hookArray; }
+      const exists = hookArray.some(entry =>
+        entry.hooks?.some(h => h.command === cmd)
+      );
+      if (!exists) hookArray.push(matcherGroup);
       return hookArray;
     };
 
-    // SessionStart hook
+    // SessionStart hooks
     settings.hooks.SessionStart = settings.hooks.SessionStart || [];
     addHookIfMissing(settings.hooks.SessionStart, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/session-start.sh'
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/session-start.sh' }]
     });
 
     // SessionStart hook: Agent sync (background, runs at most once/hour)
     addHookIfMissing(settings.hooks.SessionStart, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/agent-sync.sh'
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/agent-sync.sh' }]
     });
 
     // PreToolUse hook (Edit/Write only)
     settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
     addHookIfMissing(settings.hooks.PreToolUse, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/pre-edit-sights-check.sh',
-      matcher: 'Edit|Write'
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/pre-edit-sights-check.sh' }]
     });
 
     // PostToolUse hook (Edit/Write only)
     settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
     addHookIfMissing(settings.hooks.PostToolUse, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/post-edit-logger.sh',
-      matcher: 'Edit|Write'
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/post-edit-logger.sh' }]
     });
 
     // Stop hook (session end)
     settings.hooks.Stop = settings.hooks.Stop || [];
     addHookIfMissing(settings.hooks.Stop, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/session-end.sh'
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/session-end.sh' }]
     });
 
     // TeammateIdle hook (Agent Teams quality gate — only fires when Teams active)
     settings.hooks.TeammateIdle = settings.hooks.TeammateIdle || [];
     addHookIfMissing(settings.hooks.TeammateIdle, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/teammate-idle-verify.sh'
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/teammate-idle-verify.sh' }]
     });
 
     // SubagentStart hook (Agent Teams context injection — only fires when Teams active)
     settings.hooks.SubagentStart = settings.hooks.SubagentStart || [];
     addHookIfMissing(settings.hooks.SubagentStart, {
-      type: 'command',
-      command: 'bash ~/.claude/hooks/subagent-context.sh'
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/subagent-context.sh' }]
     });
 
     // --- Prompt-based hooks (LLM evaluates .md content) ---
@@ -951,11 +985,15 @@ async function install() {
     // first (identified by containing 'merlin' or 'Merlin' in their prompt text),
     // then re-add fresh ones. This prevents duplicate hooks across version upgrades.
     const removeMerlinPromptHooks = (hookArray) => {
-      return hookArray.filter(h => {
-        if (h.type !== 'prompt') return true; // keep non-prompt hooks
-        const prompt = (h.prompt || '').toLowerCase();
-        // Merlin prompt hooks contain these markers
-        return !(prompt.includes('merlin') || prompt.includes('sights'));
+      return hookArray.filter(entry => {
+        if (!entry.hooks || !Array.isArray(entry.hooks)) return true;
+        // Remove entry if ALL its hooks are Merlin prompt hooks
+        const allMerlinPrompts = entry.hooks.every(h => {
+          if (h.type !== 'prompt') return false;
+          const prompt = (h.prompt || '').toLowerCase();
+          return prompt.includes('merlin') || prompt.includes('sights');
+        });
+        return !allMerlinPrompts;
       });
     };
 
@@ -964,34 +1002,31 @@ async function install() {
     settings.hooks.Stop = removeMerlinPromptHooks(settings.hooks.Stop);
     settings.hooks.Notification = settings.hooks.Notification || [];
     settings.hooks.Notification = removeMerlinPromptHooks(settings.hooks.Notification);
+    settings.hooks.TaskCompleted = settings.hooks.TaskCompleted || [];
+    settings.hooks.TaskCompleted = removeMerlinPromptHooks(settings.hooks.TaskCompleted);
 
-    // Now add fresh prompt hooks
-    // Prompt-based SessionStart hook: FULL Merlin boot sequence
-    // This is the key hook that makes every session feel like Loop
-    settings.hooks.SessionStart.push({
-      type: 'prompt',
-      prompt: fs.readFileSync(path.join(HOOKS_DIR, 'session-start-boot.md'), 'utf8')
+    // Now add fresh prompt/command hooks in new format
+    // NOTE: SessionStart does NOT support prompt hooks (only command hooks).
+    // The Merlin boot sequence is handled via CLAUDE.md instructions instead.
+    // We use a command hook to inject additionalContext at session start.
+    addHookIfMissing(settings.hooks.SessionStart, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/session-start-context.sh' }]
     });
 
-    // Prompt-based PreToolUse hook: enforce Sights check before edits
-    // This is the Sights guarantee — no edit without context
+    // Prompt-based PreToolUse hook: evaluate Sights check before edits
     settings.hooks.PreToolUse.push({
-      type: 'prompt',
-      prompt: fs.readFileSync(path.join(HOOKS_DIR, 'pre-edit-sights-enforce.md'), 'utf8'),
-      matcher: 'Edit|Write'
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'prompt', prompt: fs.readFileSync(path.join(HOOKS_DIR, 'pre-edit-sights-enforce.md'), 'utf8') }]
     });
 
-    // Prompt-based Stop hook: quality gate before session ends
+    // Prompt-based Stop hook: evaluate whether stopping is appropriate
     settings.hooks.Stop.push({
-      type: 'prompt',
-      prompt: fs.readFileSync(path.join(HOOKS_DIR, 'stop-check.md'), 'utf8')
+      hooks: [{ type: 'prompt', prompt: fs.readFileSync(path.join(HOOKS_DIR, 'stop-check.md'), 'utf8') }]
     });
 
-    // Prompt-based Notification hook: verify task completion quality
-    settings.hooks.Notification.push({
-      type: 'prompt',
-      prompt: fs.readFileSync(path.join(HOOKS_DIR, 'task-completed-verify.md'), 'utf8'),
-      matcher: 'task_completed'
+    // Task completion verification hook (using dedicated TaskCompleted event)
+    settings.hooks.TaskCompleted.push({
+      hooks: [{ type: 'prompt', prompt: fs.readFileSync(path.join(HOOKS_DIR, 'task-completed-verify.md'), 'utf8') }]
     });
 
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
@@ -1031,11 +1066,15 @@ async function install() {
 
   let apiKey = existingApiKey;
   if (existingApiKey) {
-    logSuccess(`Sights API key already configured (skipping prompt)`);
+    const masked = existingApiKey.slice(0, 8) + '...' + existingApiKey.slice(-4);
+    console.log(`  Existing API key found: ${colors.cyan}${masked}${colors.reset}`);
   } else {
-    console.log(`Merlin Sights provides instant codebase context.`);
-    console.log(`Get your API key at: ${colors.cyan}https://merlin.build${colors.reset}`);
-    apiKey = await promptApiKey();
+    console.log(`  Merlin Sights provides instant codebase context.`);
+    console.log(`  Get your API key at: ${colors.cyan}https://merlin.build${colors.reset}`);
+  }
+  const inputKey = await promptApiKey(!!existingApiKey);
+  if (inputKey) {
+    apiKey = inputKey;
   }
 
   if (apiKey) {

package/files/hooks/agent-sync.sh

@@ -2,19 +2,19 @@
 # Merlin Hook: Agent Sync (SessionStart, background)
 # Checks installed agents freshness and updates from cloud. Max once/hour.
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 AGENTS_DIR="${HOME}/.claude/agents"
 MERLIN_DIR="${HOME}/.claude/merlin"
 LAST_SYNC="${MERLIN_DIR}/.last-agent-sync"
 API_URL="${MERLIN_API_URL:-https://api.merlin.build}"
 
-[ -d "${AGENTS_DIR}" ] || exit 0
+[ -d "${AGENTS_DIR}" ] || { echo '{}'; exit 0; }
 
 # Skip if synced within the last hour
 if [ -f "${LAST_SYNC}" ]; then
   last=$(cat "${LAST_SYNC}" 2>/dev/null || echo "0")
-  [ $(($(date +%s) - last)) -lt 3600 ] && exit 0
+  [ $(($(date +%s) - last)) -lt 3600 ] && { echo '{}'; exit 0; }
 fi
 
 sync_agents() {
@@ -41,4 +41,7 @@ sync_agents() {
 }
 
 sync_agents &
+
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/post-edit-logger.sh

@@ -5,7 +5,7 @@
 # Always exits 0 — never blocks Claude Code.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -30,4 +30,6 @@ fi
 # Log file change event
 log_event "file_changed" "$(printf '{"file":"%s","tool":"%s"}' "${file_path:-unknown}" "${tool_name:-unknown}")"
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/pre-edit-sights-check.sh

@@ -5,7 +5,7 @@
 # Advisory only — always exits 0, never blocks edits.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -35,4 +35,6 @@ fi
 # Log the pre-edit event
 log_event "pre_edit" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/pre-edit-sights-enforce.md

@@ -1,25 +1,12 @@
-# Merlin Sights Enforcement — Before Every Edit
+You are evaluating whether a file edit should proceed. Context: $ARGUMENTS
 
-STOP. You are about to modify a file. Merlin requires a Sights check first.
+Check: Has the assistant recently called merlin_get_context, merlin_find_files, or merlin_search for this file's area in the current conversation? Look at recent tool calls in the transcript.
 
-## Required: Context Check
-If you have NOT called `merlin_get_context` for this file's area in the last 2 minutes:
-1. Call `merlin_get_context("brief description of what you're changing and why")`
-2. Review what Sights returns — existing patterns, related files, conventions
-3. Check if similar code already exists (don't duplicate)
-4. THEN proceed with the edit
+Rules:
+- If Sights was consulted recently (within the last few messages) for this area: allow the edit
+- If this is a minor/trivial edit (formatting, typo fix, small change): allow the edit
+- If this is a significant edit and Sights was NOT consulted: suggest checking first
 
-## Required: Convention Check
-Follow ALL rules from Sights:
-- Max file size (usually 400 lines) — if approaching, split the file
-- Naming conventions — match existing patterns
-- Testing requirements — note if tests are needed
-
-## Required: Show Your Work
-After the Sights check, show a brief line so the user sees Merlin is involved:
-```
-Merlin | Checked [area] | [what you found or "clear to edit"]
-```
-
-## Never Skip This
-Every edit should be informed by codebase knowledge. This is what makes Merlin sessions better than raw Claude sessions. The user chose Merlin for a reason — deliver on it.
+Respond with ONLY valid JSON, no other text:
+- Allow the edit: {"ok": true}
+- Suggest Sights check first: {"ok": false, "reason": "Call merlin_get_context before editing this file to check for existing patterns and conventions"}

package/files/hooks/session-end.sh

@@ -5,7 +5,7 @@
 # Always exits 0 — never blocks Claude Code shutdown.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -24,4 +24,6 @@ if command -v merlin >/dev/null 2>&1; then
   merlin save-checkpoint "Session ended" >/dev/null 2>&1 &
 fi
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/session-start-context.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: SessionStart (context injection)
+# Injects Merlin identity context into the session via additionalContext.
+# Uses the SessionStart command hook JSON output format.
+# Always exits 0 — never blocks Claude Code startup.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Output additionalContext JSON for Claude to see at session start.
+# This reminds Claude it's a Merlin-powered session.
+# Full boot instructions are in CLAUDE.md — this is a lightweight nudge.
+cat <<'CONTEXT_JSON'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "You are a Merlin-powered session. Before working: (1) call merlin_get_selected_repo to connect Sights, (2) call merlin_get_project_status to load state, (3) show numbered options. Check Sights before every edit. Route complex tasks to specialists via /merlin:route. Save checkpoints before stopping."
+  }
+}
+CONTEXT_JSON
+
+exit 0

package/files/hooks/session-start.sh

@@ -5,7 +5,7 @@
 # Always exits 0 — never blocks Claude Code startup.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -28,4 +28,6 @@ if command -v merlin >/dev/null 2>&1; then
   record_sights_call
 fi
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/stop-check.md

@@ -1,36 +1,13 @@
-# Merlin Session End Protocol — Before Stopping
+You are evaluating whether Claude should stop working. Analyze the conversation context: $ARGUMENTS
 
-Before this session ends, complete this checklist:
+Check these criteria:
+1. Did the user's most recent request get fully addressed?
+2. Are there any obvious errors or broken code that should be fixed before stopping?
+3. Did Claude mention follow-up tasks it intended to complete but hasn't done yet?
 
-## 1. Uncommitted Work
-Check `git status`. If there are uncommitted changes:
-- Stage and commit with a clear message
-- Run `merlin_run_verification` before committing
+IMPORTANT: This is NOT about saving checkpoints or showing summaries — those are handled elsewhere.
+Only evaluate whether the core work is done.
 
-## 2. Save Checkpoint
-Call `merlin_save_checkpoint` with:
-- What was accomplished this session
-- What's left to do
-- Any blockers or decisions made
-This lets the next session (or another agent) pick up exactly where you left off.
-
-## 3. Session Summary
-Show the user a brief summary:
-```
-Merlin | Session Complete
-- [X] files changed
-- [Y] Sights queries made
-- [Z] tasks completed
-- Checkpoint saved: [yes/no]
-```
-
-## 4. Next Steps
-Always end with what should happen next:
-```
-Next session:
-[1] Continue with [next task]
-[2] Review what was built
-[3] [other relevant option]
-```
-
-Do NOT stop without saving checkpoint. The user trusts Merlin to maintain continuity across sessions.
+Respond with ONLY valid JSON, no other text:
+- If stopping is appropriate: {"ok": true}
+- If Claude should continue: {"ok": false, "reason": "brief explanation of what's unfinished"}

package/files/hooks/subagent-context.sh

@@ -5,7 +5,7 @@
 # Advisory only — always exits 0, never blocks subagent startup.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -28,9 +28,21 @@ fi
 # Log subagent start event
 log_event "subagent_start" "$(printf '{"task":"%s"}' "${task_desc:-unknown}")"
 
-# If Merlin CLI available, fetch and output context for the task
+# If Merlin CLI available, fetch context for the task and output as JSON
 if [ -n "$task_desc" ] && command -v merlin >/dev/null 2>&1; then
-  merlin context "$task_desc" 2>/dev/null || true
+  context_text=$(merlin context "$task_desc" 2>/dev/null || true)
+  if [ -n "$context_text" ]; then
+    # Output as proper JSON additionalContext for the subagent
+    # Use jq if available, otherwise output empty JSON (context is best-effort)
+    if command -v jq >/dev/null 2>&1; then
+      jq -n --arg ctx "$context_text" '{hookSpecificOutput:{hookEventName:"SubagentStart",additionalContext:$ctx}}'
+    else
+      echo '{}'
+    fi
+    exit 0
+  fi
 fi
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/task-completed-verify.md

@@ -1,14 +1,13 @@
-# Task Completion Verification - Merlin Quality Gate
+You are evaluating whether a task should be marked as completed. Context: $ARGUMENTS
 
-Before marking this task as complete, verify:
+Check these criteria:
+1. Was the task's stated objective accomplished based on the conversation?
+2. Were there any errors or test failures mentioned that haven't been resolved?
+3. Is the implementation reasonably complete (not a half-finished skeleton)?
 
-1. **Code Quality**: Does the implementation follow the project's coding conventions? Check with merlin_get_conventions if unsure.
+Be lenient — don't block completion for minor issues like missing docs or style nits.
+Only block if the core objective clearly wasn't met or there are unresolved errors.
 
-2. **Sights Alignment**: Is the code consistent with existing patterns? Verify with merlin_get_context for the modified areas.
-
-3. **No Regressions**: Run the project's test suite if it exists. Check build passes.
-
-4. **Documentation**: If the task added new APIs or features, are they documented?
-
-If all verifications pass, allow task completion.
-If issues are found, list them and suggest fixes before completing.
+Respond with ONLY valid JSON, no other text:
+- Task is complete: {"ok": true}
+- Task is not complete: {"ok": false, "reason": "brief explanation of what's unfinished"}

package/files/hooks/task-completed-verify.sh

@@ -5,7 +5,7 @@
 # Informational only — always exits 0 for v1.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -43,4 +43,6 @@ if [ -f "tsconfig.json" ] && command -v npx >/dev/null 2>&1; then
   fi
 fi
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/files/hooks/teammate-idle-verify.sh

@@ -5,7 +5,7 @@
 # Advisory only — always exits 0, never blocks teammates.
 #
 set -euo pipefail
-trap 'exit 0' ERR
+trap 'echo "{}"; exit 0' ERR
 
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -38,4 +38,6 @@ if command -v npm >/dev/null 2>&1; then
   npm run build --if-present >/dev/null 2>&1 || true
 fi
 
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.4.7",
+  "version": "3.4.9",
   "description": "Merlin - The Ultimate AI Brain for Claude Code. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",