@polymorphism-tech/morph-spec 7.2.0 → 7.4.0

package/src/utils/hooks-installer.js

@@ -1,516 +1,527 @@
-/**
- * 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 = '3.0.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.
- *
- * state.json is NOT in deny because the agent edits it directly as a
- * fallback to the state-sync hook (per v7 hybrid state model). The
- * framework/ tree remains read-only — only the installer touches it.
- */
-const MORPH_DENY = [
-  // Framework files — installer-managed, immutable at runtime
-  '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/**)',
-];
-
-/**
- * Native permissions.allow entries managed by MORPH-SPEC.
- *
- * Pre-authorizes operations the agent legitimately performs during the
- * morph-spec flow, so the user does not get permission prompts on every
- * proposal.md / spec.md / tasks.json write.
- */
-const MORPH_ALLOW = [
-  // Feature artifacts — the agent's working directory during proposal/plan/implement/review
-  'Write(.morph/features/**)',
-  'Edit(.morph/features/**)',
-  // state.json — fallback path when state-sync hook can't cover a case
-  'Edit(.morph/state.json)',
-  // Long-lived architectural context — agent may reconcile during brainstorming
-  'Write(.morph/context/**)',
-  'Edit(.morph/context/**)',
-  // Folder creation under .morph
-  'Bash(mkdir:.morph/**)',
-  'Bash(ls:.morph/**)',
-];
-
-// Backwards-compat alias used by older tests
-const MORPH_PERMISSIONS = MORPH_DENY;
-
-/**
- * All MORPH-SPEC hook definitions.
- * Each entry maps to a Claude Code hook event.
- */
-const MORPH_HOOKS = [
-  // === PreToolUse: Write|Edit — phase + spec protection (silent on success) ===
-  {
-    event: 'PreToolUse',
-    matcher: 'Write|Edit',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/protect-spec-files.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/enforce-phase-writes.js'
-      }
-    ]
-  },
-
-  // === PreToolUse: Bash — denylist (irreversible commands only) ===
-  {
-    event: 'PreToolUse',
-    matcher: 'Bash',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/pre-bash-denylist.js'
-      }
-    ]
-  },
-
-  // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) ===
-  {
-    event: 'PostToolUse',
-    matcher: 'Write|Edit',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
-    }]
-  },
-
-  // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous state.json updates) ===
-  {
-    event: 'PostToolUse',
-    matcher: 'Write|Edit|AskUserQuestion',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/core/state-sync.js',
-      timeout: 3000
-    }]
-  },
-
-  // === PostToolUse: All — loop detection ===
-  {
-    event: 'PostToolUse',
-    matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/core/loop-detect.js',
-      timeout: 5000
-    }]
-  },
-
-  // === Stop — build check + session snapshot ===
-  {
-    event: 'Stop',
-    matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/core/validate-completion.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 (idempotent — preserve user-added entries)
-  settings.permissions = settings.permissions || {};
-  settings.permissions.deny = settings.permissions.deny || [];
-  settings.permissions.allow = settings.permissions.allow || [];
-
-  // Stale-entry cleanup: remove old morph-managed deny entries (e.g. state.json
-  // was previously in deny — v7 moves it to allow)
-  const STALE_DENY = [
-    'Write(.morph/state.json)',
-    'Edit(.morph/state.json)',
-  ];
-  settings.permissions.deny = settings.permissions.deny.filter(
-    p => !MORPH_DENY.includes(p) && !STALE_DENY.includes(p)
-  );
-  for (const perm of MORPH_DENY) {
-    settings.permissions.deny.push(perm);
-  }
-
-  settings.permissions.allow = settings.permissions.allow.filter(
-    p => !MORPH_ALLOW.includes(p)
-  );
-  for (const perm of MORPH_ALLOW) {
-    settings.permissions.allow.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;
-}
+/**
+ * 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 = '3.0.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.
+ *
+ * state.json is NOT in deny because the agent edits it directly as a
+ * fallback to the state-sync hook (per v7 hybrid state model). The
+ * framework/ tree remains read-only — only the installer touches it.
+ */
+const MORPH_DENY = [
+  // Framework files — installer-managed, immutable at runtime
+  '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/**)',
+];
+
+/**
+ * Native permissions.allow entries managed by MORPH-SPEC.
+ *
+ * Pre-authorizes operations the agent legitimately performs during the
+ * morph-spec flow, so the user does not get permission prompts on every
+ * proposal.md / spec.md / tasks.json write.
+ */
+const MORPH_ALLOW = [
+  // Feature artifacts — the agent's working directory during proposal/plan/implement/review
+  'Write(.morph/features/**)',
+  'Edit(.morph/features/**)',
+  // state.json — fallback path when state-sync hook can't cover a case
+  'Edit(.morph/state.json)',
+  // Long-lived architectural context — agent may reconcile during brainstorming
+  'Write(.morph/context/**)',
+  'Edit(.morph/context/**)',
+  // Folder creation under .morph
+  'Bash(mkdir:.morph/**)',
+  'Bash(ls:.morph/**)',
+];
+
+// Backwards-compat alias used by older tests
+const MORPH_PERMISSIONS = MORPH_DENY;
+
+/**
+ * All MORPH-SPEC hook definitions.
+ * Each entry maps to a Claude Code hook event.
+ */
+const MORPH_HOOKS = [
+  // === PreToolUse: Write|Edit — phase + spec protection (silent on success) ===
+  {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit',
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/protect-spec-files.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/enforce-phase-writes.js'
+      }
+    ]
+  },
+
+  // === PreToolUse: Bash — denylist (irreversible commands only) ===
+  {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/pre-bash-denylist.js'
+      }
+    ]
+  },
+
+  // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) ===
+  {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
+    }]
+  },
+
+  // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous state.json updates) ===
+  // gate-guard runs AFTER state-sync so it sees the gate that state-sync just
+  // recorded. Both are silent fail-open guardrails; gate-guard only warns
+  // (never blocks) when an observed gate action disagrees with the persisted
+  // gateDecisions (issue #63).
+  {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit|AskUserQuestion',
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/state-sync.js',
+        timeout: 3000
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/gate-guard.js',
+        timeout: 3000
+      }
+    ]
+  },
+
+  // === PostToolUse: All — loop detection ===
+  {
+    event: 'PostToolUse',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/loop-detect.js',
+      timeout: 5000
+    }]
+  },
+
+  // === Stop — build check + session snapshot ===
+  {
+    event: 'Stop',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/validate-completion.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 (idempotent — preserve user-added entries)
+  settings.permissions = settings.permissions || {};
+  settings.permissions.deny = settings.permissions.deny || [];
+  settings.permissions.allow = settings.permissions.allow || [];
+
+  // Stale-entry cleanup: remove old morph-managed deny entries (e.g. state.json
+  // was previously in deny — v7 moves it to allow)
+  const STALE_DENY = [
+    'Write(.morph/state.json)',
+    'Edit(.morph/state.json)',
+  ];
+  settings.permissions.deny = settings.permissions.deny.filter(
+    p => !MORPH_DENY.includes(p) && !STALE_DENY.includes(p)
+  );
+  for (const perm of MORPH_DENY) {
+    settings.permissions.deny.push(perm);
+  }
+
+  settings.permissions.allow = settings.permissions.allow.filter(
+    p => !MORPH_ALLOW.includes(p)
+  );
+  for (const perm of MORPH_ALLOW) {
+    settings.permissions.allow.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;
+}