@polymorphism-tech/morph-spec 4.10.7 → 4.10.8

package/src/utils/hooks-installer.js

@@ -1,494 +1,556 @@
-/**
- * Claude Code Hooks Installer (v2)
- *
- * Registry-based installer for all MORPH-SPEC Claude Code hooks.
- * Declarative MORPH_HOOKS array defines all hooks.
- * Idempotent merge into .claude/settings.local.json.
- *
- * Called by `morph-spec init` and `morph-spec update`.
- */
-
-import { join, dirname } from 'path';
-import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
-import { existsSync, chmodSync, readdirSync } from 'fs';
-import { homedir } from 'os';
-import { execSync } from 'child_process';
-
-/** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '2.12.0';
-
-/** Marker for old dispatch.js (v1) */
-const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
-
-/**
- * Native permissions.deny entries managed by MORPH-SPEC.
- * These replace the protect-readonly-files.js PreToolUse hook,
- * using Claude Code's built-in permissions system instead.
- */
-const MORPH_PERMISSIONS = [
-  // Core framework state and readonly files
-  'Write(.morph/state.json)',
-  'Edit(.morph/state.json)',
-  'Write(.morph/framework/**)',
-  'Edit(.morph/framework/**)',
-  // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE.md)
-  'Write(.claude/CLAUDE.md)',
-  'Edit(.claude/CLAUDE.md)',
-  // .claude/rules/ (copied from framework/rules/)
-  'Write(.claude/rules/**)',
-  'Edit(.claude/rules/**)',
-  // .claude/agents/morph-* (generated by agents-installer)
-  'Write(.claude/agents/morph-*)',
-  'Edit(.claude/agents/morph-*)',
-  // .claude/skills/ (copied from framework/skills/)
-  'Write(.claude/skills/**)',
-  'Edit(.claude/skills/**)',
-];
-
-/**
- * All MORPH-SPEC hook definitions.
- * Each entry maps to a Claude Code hook event.
- */
-const MORPH_HOOKS = [
-  // === SessionStart ===
-  {
-    event: 'SessionStart',
-    matcher: 'startup|resume|compact',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/session-start/inject-morph-context.js'
-    }]
-  },
-
-  // === SessionStart: compact only — post-compact context restore ===
-  {
-    event: 'SessionStart',
-    matcher: 'compact',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/session-start/post-compact-restore.js'
-    }]
-  },
-
-  // === UserPromptSubmit ===
-  {
-    event: 'UserPromptSubmit',
-    matcher: null,
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/user-prompt/enrich-prompt.js'
-      },
-    ]
-  },
-
-  // === PreToolUse: Write|Edit ===
-  {
-    event: 'PreToolUse',
-    matcher: 'Write|Edit',
-    hooks: [
-      // Note: protect-readonly-files.js replaced by native permissions.deny (see MORPH_PERMISSIONS)
-      // Order matters: cheapest check first
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/pre-tool-use/protect-spec-files.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js'
-      }
-    ]
-  },
-
-  // === PreToolUse: Bash ===
-  {
-    event: 'PreToolUse',
-    matcher: 'Bash',
-    hooks: [{
-      type: 'prompt',
-      prompt: `You are a guard for a morph-spec project. Read the bash command from the hook input and check EXACTLY these 3 conditions. IMPORTANT: reading files (cat, head, tail, grep, less, bat) is NEVER blocked regardless of path.
-1. Does the command DELETE .morph/ or .morph/state.json or .morph/framework/ using rm -r, rm -rf, or rmdir? BLOCK only these exact paths. NOTE: deleting .morph/features/ subdirectories is NOT blocked.
-2. Does the command OVERWRITE .morph/state.json using a shell redirect (>) combined with sed, jq, awk, echo, cat, or printf? If yes, BLOCK.
-3. Does the command WRITE TO .morph/framework/ via a shell redirect (>) or Node.js fs.writeFileSync/appendFileSync on a path under .morph/framework/? READING .morph/framework/ is always allowed. Writing to .morph/features/, .morph/config/, .morph/context/ is allowed.
-If ANY of these 3 specific conditions matches, respond: {"ok": false, "reason": "MORPH-SPEC: [explain what was blocked]. To read agents/state use: morph-spec state get <feature> | morph-spec dispatch-agents <feature> <phase> --table | cat .morph/framework/agents.json (reading is always allowed). To update state use: morph-spec state set <feature> <key> <value>."}
-Otherwise respond: {"ok": true}`
-    }]
-  },
-
-  // === PostToolUse: Bash ===
-  {
-    event: 'PostToolUse',
-    matcher: 'Bash',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/post-tool-use/dispatch.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/post-tool-use/context-refresh.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/post-tool-use/skill-reminder.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/post-tool-use/validator-feedback.js'
-      }
-    ]
-  },
-
-  // === Stop ===
-  {
-    event: 'Stop',
-    matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/stop/validate-completion.js'
-    }]
-  },
-
-  // === PreCompact ===
-  {
-    event: 'PreCompact',
-    matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/pre-compact/save-morph-context.js'
-    }]
-  },
-
-  // === PostToolUseFailure ===
-  {
-    event: 'PostToolUseFailure',
-    matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/post-tool-use/handle-tool-failure.js',
-      timeout: 10000,
-    }]
-  },
-
-  // === Notification ===
-  {
-    event: 'Notification',
-    matcher: 'idle_prompt',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/notification/approval-reminder.js'
-    }]
-  },
-
-  // === TeammateIdle ===
-  // Fires when an Agent Team teammate finishes and is about to go idle.
-  // Exit 2 = send feedback to teammate to continue working (validation failed).
-  // Exit 0 = teammate may become idle (validation passed).
-  // Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in env above).
-  {
-    event: 'TeammateIdle',
-    matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/teammate-idle/teammate-idle.js'
-    }]
-  }
-];
-
-/**
- * Install or update all MORPH-SPEC hooks in .claude/settings.local.json.
- *
- * - Idempotent: safe to call multiple times
- * - Removes old v1 dispatch.js entry if present
- * - Tracks installed version via _morph_managed.hooks_version
- *
- * @param {string} targetPath - Project root directory
- * @returns {Promise<{ installed: number, updated: boolean }>}
- */
-export async function installClaudeHooks(targetPath) {
-  const claudeDir = join(targetPath, '.claude');
-  const settingsPath = join(claudeDir, 'settings.local.json');
-
-  // Read existing settings or start empty
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-    } catch {
-      settings = {};
-    }
-  }
-
-  settings.hooks = settings.hooks || {};
-
-  // Check if already at current version
-  const managed = settings._morph_managed || {};
-  const alreadyCurrent = managed.hooks_version === HOOKS_VERSION;
-
-  // Remove old v1 dispatch.js entry
-  removeOldDispatch(settings);
-
-  // Remove all morph-managed hooks (clean slate for idempotent update)
-  removeMorphHooks(settings);
-
-  // Install all hooks from the registry
-  let installed = 0;
-  for (const hookDef of MORPH_HOOKS) {
-    const { event, matcher, hooks } = hookDef;
-
-    if (!settings.hooks[event]) {
-      settings.hooks[event] = [];
-    }
-
-    const entry = { _morph: true };
-    if (matcher) {
-      entry.matcher = matcher;
-    }
-    entry.hooks = hooks.map(h => {
-      // Agent and prompt hooks: pass through as-is (no command path transform)
-      if (h.type === 'agent' || h.type === 'prompt') {
-        const agentHook = { type: h.type, prompt: h.prompt };
-        if (h.timeout !== undefined) agentHook.timeout = h.timeout;
-        return agentHook;
-      }
-      // Command hooks: transform path to use $CLAUDE_PROJECT_DIR
-      // Hooks are copied to .morph/framework/hooks/ during `morph-spec init/update`
-      return {
-        type: h.type,
-        command: `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
-        ...(h.timeout !== undefined ? { timeout: h.timeout } : {})
-      };
-    });
-
-    settings.hooks[event].push(entry);
-    installed++;
-  }
-
-  // Install native permissions.deny entries (idempotent)
-  settings.permissions = settings.permissions || {};
-  settings.permissions.deny = settings.permissions.deny || [];
-  // Remove previously managed permissions to avoid duplicates on re-install
-  settings.permissions.deny = settings.permissions.deny.filter(
-    p => !MORPH_PERMISSIONS.includes(p)
-  );
-  for (const perm of MORPH_PERMISSIONS) {
-    settings.permissions.deny.push(perm);
-  }
-
-  // JSON Schema for IDE auto-complete and validation
-  settings['$schema'] = 'https://json.schemastore.org/claude-code-settings.json';
-
-  // Environment variables — always set MORPH_SPEC_ACTIVE + Agent Teams flag, preserve user additions
-  settings.env = {
-    ...settings.env,
-    MORPH_SPEC_ACTIVE: 'true',
-    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
-  };
-
-  // Attribution — only set if not already customized by user
-  if (!settings.attribution) {
-    settings.attribution = {
-      commit: '🤖 Co-authored by MORPH-SPEC',
-      pr: '',
-    };
-  }
-
-  // Plans directory for Claude Code plan mode
-  if (!settings.plansDirectory) {
-    settings.plansDirectory = '.morph/plans';
-  }
-
-  // Track installed hooks version
-  settings._morph_managed = settings._morph_managed || {};
-  settings._morph_managed.hooks_version = HOOKS_VERSION;
-  settings._morph_managed.hooks_installed = [...new Set(MORPH_HOOKS.map(h => h.event))];
-  settings._morph_managed.generated_at = new Date().toISOString();
-
-  // Ensure .claude directory exists
-  if (!existsSync(claudeDir)) {
-    await mkdir(claudeDir, { recursive: true });
-  }
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-  return { installed, updated: !alreadyCurrent };
-}
-
-/**
- * Resolve Python executable suitable for the statusLine command.
- *
- * On non-Windows: returns 'python3' (standard PATH name).
- * On Windows: Claude Code runs commands via the system shell where python3/python
- * may not be on PATH. We probe with execSync first, then fall back to known
- * Windows install locations (AppData\Local\Programs\Python\Python3*).
- *
- * @returns {string} Python executable (full path on Windows if needed)
- */
-function resolvePythonForStatusline() {
-  if (process.platform !== 'win32') {
-    return 'python3';
-  }
-  // Try PATH-visible commands first (works if user added Python to PATH)
-  // 'py' is the Windows Python Launcher — standard on any Windows Python install
-  for (const cmd of ['python3', 'py', 'python']) {
-    try {
-      const ver = execSync(`${cmd} --version`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
-      if ((ver + '').includes('Python 3')) return cmd;
-    } catch { /* not on PATH */ }
-  }
-  // Probe known Windows install locations
-  const base = join(homedir(), 'AppData', 'Local', 'Programs', 'Python');
-  if (existsSync(base)) {
-    let dirs;
-    try { dirs = readdirSync(base); } catch { dirs = []; }
-    const py3 = dirs
-      .filter(d => /^Python3\d*/i.test(d))
-      .sort()
-      .reverse(); // prefer highest version
-    for (const dir of py3) {
-      const exe = join(base, dir, 'python.exe');
-      if (existsSync(exe)) return exe;
-    }
-  }
-  // Last resort: return python3 and let it fail with a clear error
-  return 'python3';
-}
-
-/**
- * Install the morph-spec statusline globally into ~/.claude/.
- *
- * Copies statusline.sh and statusline.py to ~/.claude/ and registers
- * the statusLine config in ~/.claude/settings.json so it applies to
- * every Claude Code session, not just morph-spec projects.
- *
- * Python 3 must be available as `python3` on PATH (global prerequisite).
- *
- * @param {string} hooksSourceDir - Path to framework/hooks/claude-code/
- * @param {string} [globalClaudeDirOverride] - Override ~/.claude/ (for testing)
- * @returns {Promise<{ installed: boolean, globalDir: string }>}
- */
-export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null) {
-  const globalDir = globalClaudeDirOverride || join(homedir(), '.claude');
-  await mkdir(globalDir, { recursive: true });
-
-  // Copy statusline scripts to ~/.claude/
-  const scripts = ['statusline.sh', 'statusline.py'];
-  for (const fname of scripts) {
-    const src = join(hooksSourceDir, fname);
-    if (existsSync(src)) {
-      await copyFile(src, join(globalDir, fname));
-      if (process.platform !== 'win32') {
-        try { chmodSync(join(globalDir, fname), 0o755); } catch { /* non-critical */ }
-      }
-    }
-  }
-
-  // Register statusLine in ~/.claude/settings.json (global user settings)
-  const settingsPath = join(globalDir, 'settings.json');
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-    } catch {
-      settings = {};
-    }
-  }
-
-  // On Windows, Claude Code cannot execute .sh files directly — call Python instead.
-  const statuslineCommand = process.platform === 'win32'
-    ? `"${resolvePythonForStatusline()}" "${join(globalDir, 'statusline.py').replace(/\\/g, '/')}"`
-    : join(globalDir, 'statusline.sh').replace(/\\/g, '/');
-
-  settings.statusLine = {
-    type: 'command',
-    command: statuslineCommand,
-    padding: 2
-  };
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-  return { installed: true, globalDir };
-}
-
-
-
-/**
- * Remove old v1 agent-teams/dispatch.js hook entries.
- * @param {Object} settings
- */
-function removeOldDispatch(settings) {
-  if (!settings.hooks?.PostToolUse) return;
-
-  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
-    if (!Array.isArray(entry.hooks)) return true;
-    return !entry.hooks.some(h =>
-      h.command === OLD_DISPATCH_COMMAND ||
-      (typeof h.command === 'string' && h.command.includes('agent-teams/dispatch.js'))
-    );
-  });
-
-  if (settings.hooks.PostToolUse.length === 0) {
-    delete settings.hooks.PostToolUse;
-  }
-}
-
-/**
- * Remove all morph-managed hook entries.
- * Uses _morph:true marker (v2.2+) with legacy path-pattern fallback.
- * Preserves any user-added hooks.
- * @param {Object} settings
- */
-function removeMorphHooks(settings) {
-  const morphPathPattern = /framework\/hooks\/claude-code\//;
-
-  for (const [event, entries] of Object.entries(settings.hooks)) {
-    if (!Array.isArray(entries)) continue;
-
-    settings.hooks[event] = entries.filter(entry => {
-      // Remove if explicitly marked as morph-managed
-      if (entry._morph === true) return false;
-
-      if (!Array.isArray(entry.hooks)) return true;
-      // Legacy path-pattern detection: remove if all hooks are morph command hooks
-      // Note: legacy path only covers command-type hooks (those with a path-matching command).
-      // Agent/prompt hooks without _morph marker are NOT removed by this fallback.
-      // This is acceptable since all morph hooks since v2.2.0 carry the _morph marker.
-      const nonMorphHooks = entry.hooks.filter(h =>
-        typeof h.command !== 'string' || !morphPathPattern.test(h.command)
-      );
-      return nonMorphHooks.length > 0;
-    });
-
-    if (settings.hooks[event].length === 0) {
-      delete settings.hooks[event];
-    }
-  }
-}
-
-/**
- * Extract hook subpath from a full command string.
- * @param {string} command - e.g., 'node framework/hooks/claude-code/stop/validate-completion.js'
- * @returns {string} e.g., 'stop/validate-completion.js'
- */
-function getHookSubpath(command) {
-  const match = command.match(/claude-code\/(.+)$/);
-  return match ? match[1] : command;
-}
-
-/**
- * Get the current hooks version.
- * @returns {string}
- */
-export function getHooksVersion() {
-  return HOOKS_VERSION;
-}
-
-/**
- * Get the list of hook definitions (for testing/inspection).
- * @returns {Array}
- */
-export function getHookDefinitions() {
-  return MORPH_HOOKS;
-}
+/**
+ * Claude Code Hooks Installer (v2)
+ *
+ * Registry-based installer for all MORPH-SPEC Claude Code hooks.
+ * Declarative MORPH_HOOKS array defines all hooks.
+ * Idempotent merge into .claude/settings.local.json.
+ *
+ * Called by `morph-spec init` and `morph-spec update`.
+ */
+
+import { join, dirname } from 'path';
+import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
+import { existsSync, chmodSync, readdirSync } from 'fs';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+
+/** Current hooks schema version — bump when hook definitions change */
+const HOOKS_VERSION = '2.12.0';
+
+/** Marker for old dispatch.js (v1) */
+const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
+
+/**
+ * Native permissions.deny entries managed by MORPH-SPEC.
+ * These replace the protect-readonly-files.js PreToolUse hook,
+ * using Claude Code's built-in permissions system instead.
+ */
+const MORPH_PERMISSIONS = [
+  // Core framework state and readonly files
+  'Write(.morph/state.json)',
+  'Edit(.morph/state.json)',
+  'Write(.morph/framework/**)',
+  'Edit(.morph/framework/**)',
+  // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE.md)
+  'Write(.claude/CLAUDE.md)',
+  'Edit(.claude/CLAUDE.md)',
+  // .claude/rules/ (copied from framework/rules/)
+  'Write(.claude/rules/**)',
+  'Edit(.claude/rules/**)',
+  // .claude/agents/morph-* (generated by agents-installer)
+  'Write(.claude/agents/morph-*)',
+  'Edit(.claude/agents/morph-*)',
+  // .claude/skills/ (copied from framework/skills/)
+  'Write(.claude/skills/**)',
+  'Edit(.claude/skills/**)',
+];
+
+/**
+ * All MORPH-SPEC hook definitions.
+ * Each entry maps to a Claude Code hook event.
+ */
+const MORPH_HOOKS = [
+  // === SessionStart ===
+  {
+    event: 'SessionStart',
+    matcher: 'startup|resume|compact',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/session-start/inject-morph-context.js'
+    }]
+  },
+
+  // === SessionStart: compact only — post-compact context restore ===
+  {
+    event: 'SessionStart',
+    matcher: 'compact',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/session-start/post-compact-restore.js'
+    }]
+  },
+
+  // === UserPromptSubmit ===
+  {
+    event: 'UserPromptSubmit',
+    matcher: null,
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/user-prompt/enrich-prompt.js'
+      },
+    ]
+  },
+
+  // === PreToolUse: Write|Edit ===
+  {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit',
+    hooks: [
+      // Note: protect-readonly-files.js replaced by native permissions.deny (see MORPH_PERMISSIONS)
+      // Order matters: cheapest check first
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/protect-spec-files.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js'
+      }
+    ]
+  },
+
+  // === PreToolUse: Bash ===
+  {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    hooks: [{
+      type: 'prompt',
+      prompt: `You are a guard for a morph-spec project. Read the bash command from the hook input and check EXACTLY these 3 conditions. IMPORTANT: reading files (cat, head, tail, grep, less, bat) is NEVER blocked regardless of path.
+1. Does the command DELETE .morph/ or .morph/state.json or .morph/framework/ using rm -r, rm -rf, or rmdir? BLOCK only these exact paths. NOTE: deleting .morph/features/ subdirectories is NOT blocked.
+2. Does the command OVERWRITE .morph/state.json using a shell redirect (>) combined with sed, jq, awk, echo, cat, or printf? If yes, BLOCK.
+3. Does the command WRITE TO .morph/framework/ via a shell redirect (>) or Node.js fs.writeFileSync/appendFileSync on a path under .morph/framework/? READING .morph/framework/ is always allowed. Writing to .morph/features/, .morph/config/, .morph/context/ is allowed.
+If ANY of these 3 specific conditions matches, respond: {"ok": false, "reason": "MORPH-SPEC: [explain what was blocked]. To read agents/state use: morph-spec state get <feature> | morph-spec dispatch-agents <feature> <phase> --table | cat .morph/framework/agents.json (reading is always allowed). To update state use: morph-spec state set <feature> <key> <value>."}
+Otherwise respond: {"ok": true}`
+    }]
+  },
+
+  // === PostToolUse: Bash ===
+  {
+    event: 'PostToolUse',
+    matcher: 'Bash',
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/post-tool-use/dispatch.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/post-tool-use/context-refresh.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/post-tool-use/skill-reminder.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/post-tool-use/validator-feedback.js'
+      }
+    ]
+  },
+
+  // === Stop ===
+  {
+    event: 'Stop',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/stop/validate-completion.js'
+    }]
+  },
+
+  // === PreCompact ===
+  {
+    event: 'PreCompact',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/pre-compact/save-morph-context.js'
+    }]
+  },
+
+  // === PostToolUseFailure ===
+  {
+    event: 'PostToolUseFailure',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/post-tool-use/handle-tool-failure.js',
+      timeout: 10000,
+    }]
+  },
+
+  // === Notification ===
+  {
+    event: 'Notification',
+    matcher: 'idle_prompt',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/notification/approval-reminder.js'
+    }]
+  },
+
+  // === TeammateIdle ===
+  // Fires when an Agent Team teammate finishes and is about to go idle.
+  // Exit 2 = send feedback to teammate to continue working (validation failed).
+  // Exit 0 = teammate may become idle (validation passed).
+  // Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in env above).
+  {
+    event: 'TeammateIdle',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/teammate-idle/teammate-idle.js'
+    }]
+  }
+];
+
+/**
+ * Install or update all MORPH-SPEC hooks in .claude/settings.local.json.
+ *
+ * - Idempotent: safe to call multiple times
+ * - Removes old v1 dispatch.js entry if present
+ * - Tracks installed version via _morph_managed.hooks_version
+ *
+ * @param {string} targetPath - Project root directory
+ * @returns {Promise<{ installed: number, updated: boolean }>}
+ */
+export async function installClaudeHooks(targetPath) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  // Read existing settings or start empty
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+
+  // Check if already at current version
+  const managed = settings._morph_managed || {};
+  const alreadyCurrent = managed.hooks_version === HOOKS_VERSION;
+
+  // Remove old v1 dispatch.js entry
+  removeOldDispatch(settings);
+
+  // Remove all morph-managed hooks (clean slate for idempotent update)
+  removeMorphHooks(settings);
+
+  // Install all hooks from the registry
+  let installed = 0;
+  for (const hookDef of MORPH_HOOKS) {
+    const { event, matcher, hooks } = hookDef;
+
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    const entry = { _morph: true };
+    if (matcher) {
+      entry.matcher = matcher;
+    }
+    entry.hooks = hooks.map(h => {
+      // Agent and prompt hooks: pass through as-is (no command path transform)
+      if (h.type === 'agent' || h.type === 'prompt') {
+        const agentHook = { type: h.type, prompt: h.prompt };
+        if (h.timeout !== undefined) agentHook.timeout = h.timeout;
+        return agentHook;
+      }
+      // Command hooks: transform path to use $CLAUDE_PROJECT_DIR
+      // Hooks are copied to .morph/framework/hooks/ during `morph-spec init/update`
+      return {
+        type: h.type,
+        command: `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
+        ...(h.timeout !== undefined ? { timeout: h.timeout } : {})
+      };
+    });
+
+    settings.hooks[event].push(entry);
+    installed++;
+  }
+
+  // Install native permissions.deny entries (idempotent)
+  settings.permissions = settings.permissions || {};
+  settings.permissions.deny = settings.permissions.deny || [];
+  // Remove previously managed permissions to avoid duplicates on re-install
+  settings.permissions.deny = settings.permissions.deny.filter(
+    p => !MORPH_PERMISSIONS.includes(p)
+  );
+  for (const perm of MORPH_PERMISSIONS) {
+    settings.permissions.deny.push(perm);
+  }
+
+  // JSON Schema for IDE auto-complete and validation
+  settings['$schema'] = 'https://json.schemastore.org/claude-code-settings.json';
+
+  // Environment variables — always set MORPH_SPEC_ACTIVE + Agent Teams flag, preserve user additions
+  settings.env = {
+    ...settings.env,
+    MORPH_SPEC_ACTIVE: 'true',
+    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+  };
+
+  // Attribution — only set if not already customized by user
+  if (!settings.attribution) {
+    settings.attribution = {
+      commit: '🤖 Co-authored by MORPH-SPEC',
+      pr: '',
+    };
+  }
+
+  // Plans directory for Claude Code plan mode
+  if (!settings.plansDirectory) {
+    settings.plansDirectory = '.morph/plans';
+  }
+
+  // Track installed hooks version
+  settings._morph_managed = settings._morph_managed || {};
+  settings._morph_managed.hooks_version = HOOKS_VERSION;
+  settings._morph_managed.hooks_installed = [...new Set(MORPH_HOOKS.map(h => h.event))];
+  settings._morph_managed.generated_at = new Date().toISOString();
+
+  // Ensure .claude directory exists
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { installed, updated: !alreadyCurrent };
+}
+
+/**
+ * Try to find an existing Python 3 executable.
+ *
+ * @returns {string|null} Python command/path if found, null otherwise
+ */
+function findPython() {
+  if (process.platform !== 'win32') {
+    for (const cmd of ['python3', 'python']) {
+      try {
+        const ver = execSync(`${cmd} --version`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+        if ((ver + '').includes('Python 3')) return cmd;
+      } catch { /* not on PATH */ }
+    }
+    return null;
+  }
+  // Windows: try PATH-visible commands first
+  // 'py' is the Windows Python Launcher — standard on any Windows Python install
+  for (const cmd of ['python3', 'py', 'python']) {
+    try {
+      const ver = execSync(`${cmd} --version`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+      if ((ver + '').includes('Python 3')) return cmd;
+    } catch { /* not on PATH */ }
+  }
+  // Probe known Windows install locations
+  const base = join(homedir(), 'AppData', 'Local', 'Programs', 'Python');
+  if (existsSync(base)) {
+    let dirs;
+    try { dirs = readdirSync(base); } catch { dirs = []; }
+    const py3 = dirs
+      .filter(d => /^Python3\d*/i.test(d))
+      .sort()
+      .reverse(); // prefer highest version
+    for (const dir of py3) {
+      const exe = join(base, dir, 'python.exe');
+      if (existsSync(exe)) return exe;
+    }
+  }
+  return null;
+}
+
+/**
+ * Attempt to auto-install Python 3 using the system package manager.
+ *
+ * On Windows: uses winget (built-in on Windows 10+).
+ * On macOS: uses brew if available.
+ * On Linux: tries apt-get, then dnf.
+ *
+ * @returns {boolean} true if installation succeeded
+ */
+function tryInstallPython() {
+  const log = (msg) => process.stdout.write(`  ${msg}\n`);
+  log('⚠ Python 3 not found — attempting automatic installation...');
+
+  try {
+    if (process.platform === 'win32') {
+      execSync('winget install -e --id Python.Python.3.12 --accept-source-agreements --accept-package-agreements', {
+        stdio: 'inherit',
+        timeout: 120_000,
+      });
+    } else if (process.platform === 'darwin') {
+      execSync('brew install python3', { stdio: 'inherit', timeout: 120_000 });
+    } else {
+      // Linux — try apt-get first, then dnf
+      try {
+        execSync('sudo apt-get update -qq && sudo apt-get install -y python3', { stdio: 'inherit', timeout: 120_000 });
+      } catch {
+        execSync('sudo dnf install -y python3', { stdio: 'inherit', timeout: 120_000 });
+      }
+    }
+    log('✓ Python 3 installed successfully.');
+    return true;
+  } catch (err) {
+    log(`✗ Automatic Python installation failed: ${err.message}`);
+    log('  Please install Python 3 manually: https://www.python.org/downloads/');
+    return false;
+  }
+}
+
+/**
+ * Resolve Python executable suitable for the statusLine command.
+ *
+ * Tries to find Python 3 on the system. If not found, attempts automatic
+ * installation via the system package manager (winget/brew/apt/dnf).
+ *
+ * @returns {string} Python executable (full path on Windows if needed)
+ */
+function resolvePythonForStatusline() {
+  // First pass — check existing installation
+  let python = findPython();
+  if (python) return python;
+
+  // Not found — try to install
+  if (tryInstallPython()) {
+    // Re-probe after installation
+    python = findPython();
+    if (python) return python;
+  }
+
+  // Last resort: return python3 and let it fail with a clear error
+  return 'python3';
+}
+
+/**
+ * Install the morph-spec statusline globally into ~/.claude/.
+ *
+ * Copies statusline.sh and statusline.py to ~/.claude/ and registers
+ * the statusLine config in ~/.claude/settings.json so it applies to
+ * every Claude Code session, not just morph-spec projects.
+ *
+ * Python 3 must be available as `python3` on PATH (global prerequisite).
+ *
+ * @param {string} hooksSourceDir - Path to framework/hooks/claude-code/
+ * @param {string} [globalClaudeDirOverride] - Override ~/.claude/ (for testing)
+ * @returns {Promise<{ installed: boolean, globalDir: string }>}
+ */
+export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null) {
+  const globalDir = globalClaudeDirOverride || join(homedir(), '.claude');
+  await mkdir(globalDir, { recursive: true });
+
+  // Copy statusline scripts to ~/.claude/
+  const scripts = ['statusline.sh', 'statusline.py'];
+  for (const fname of scripts) {
+    const src = join(hooksSourceDir, fname);
+    if (existsSync(src)) {
+      await copyFile(src, join(globalDir, fname));
+      if (process.platform !== 'win32') {
+        try { chmodSync(join(globalDir, fname), 0o755); } catch { /* non-critical */ }
+      }
+    }
+  }
+
+  // Register statusLine in ~/.claude/settings.json (global user settings)
+  const settingsPath = join(globalDir, 'settings.json');
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  // On Windows, Claude Code cannot execute .sh files directly — call Python instead.
+  const statuslineCommand = process.platform === 'win32'
+    ? `"${resolvePythonForStatusline()}" "${join(globalDir, 'statusline.py').replace(/\\/g, '/')}"`
+    : join(globalDir, 'statusline.sh').replace(/\\/g, '/');
+
+  settings.statusLine = {
+    type: 'command',
+    command: statuslineCommand,
+    padding: 2
+  };
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { installed: true, globalDir };
+}
+
+
+
+/**
+ * Remove old v1 agent-teams/dispatch.js hook entries.
+ * @param {Object} settings
+ */
+function removeOldDispatch(settings) {
+  if (!settings.hooks?.PostToolUse) return;
+
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+    if (!Array.isArray(entry.hooks)) return true;
+    return !entry.hooks.some(h =>
+      h.command === OLD_DISPATCH_COMMAND ||
+      (typeof h.command === 'string' && h.command.includes('agent-teams/dispatch.js'))
+    );
+  });
+
+  if (settings.hooks.PostToolUse.length === 0) {
+    delete settings.hooks.PostToolUse;
+  }
+}
+
+/**
+ * Remove all morph-managed hook entries.
+ * Uses _morph:true marker (v2.2+) with legacy path-pattern fallback.
+ * Preserves any user-added hooks.
+ * @param {Object} settings
+ */
+function removeMorphHooks(settings) {
+  const morphPathPattern = /framework\/hooks\/claude-code\//;
+
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+
+    settings.hooks[event] = entries.filter(entry => {
+      // Remove if explicitly marked as morph-managed
+      if (entry._morph === true) return false;
+
+      if (!Array.isArray(entry.hooks)) return true;
+      // Legacy path-pattern detection: remove if all hooks are morph command hooks
+      // Note: legacy path only covers command-type hooks (those with a path-matching command).
+      // Agent/prompt hooks without _morph marker are NOT removed by this fallback.
+      // This is acceptable since all morph hooks since v2.2.0 carry the _morph marker.
+      const nonMorphHooks = entry.hooks.filter(h =>
+        typeof h.command !== 'string' || !morphPathPattern.test(h.command)
+      );
+      return nonMorphHooks.length > 0;
+    });
+
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+  }
+}
+
+/**
+ * Extract hook subpath from a full command string.
+ * @param {string} command - e.g., 'node framework/hooks/claude-code/stop/validate-completion.js'
+ * @returns {string} e.g., 'stop/validate-completion.js'
+ */
+function getHookSubpath(command) {
+  const match = command.match(/claude-code\/(.+)$/);
+  return match ? match[1] : command;
+}
+
+/**
+ * Get the current hooks version.
+ * @returns {string}
+ */
+export function getHooksVersion() {
+  return HOOKS_VERSION;
+}
+
+/**
+ * Get the list of hook definitions (for testing/inspection).
+ * @returns {Array}
+ */
+export function getHookDefinitions() {
+  return MORPH_HOOKS;
+}