create-merlin-brain 3.4.8 → 3.4.9

package/bin/install.cjs

@@ -1005,19 +1005,21 @@ async function install() {
     settings.hooks.TaskCompleted = settings.hooks.TaskCompleted || [];
     settings.hooks.TaskCompleted = removeMerlinPromptHooks(settings.hooks.TaskCompleted);
 
-    // Now add fresh prompt hooks in new format
-    // Prompt-based SessionStart hook: FULL Merlin boot sequence
-    settings.hooks.SessionStart.push({
-      hooks: [{ 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
+    // Prompt-based PreToolUse hook: evaluate Sights check before edits
     settings.hooks.PreToolUse.push({
       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({
       hooks: [{ type: 'prompt', prompt: fs.readFileSync(path.join(HOOKS_DIR, 'stop-check.md'), 'utf8') }]
     });

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.8",
+  "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",