@polymorphism-tech/morph-spec 4.10.4 → 4.10.6

package/src/utils/hooks-installer.js

@@ -1,739 +1,739 @@
-/**
- * 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'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/user-prompt/set-terminal-title.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 };
-}
-
-/**
- * Install VS Code terminal settings to enable OSC title sequences.
- *
- * Sets `terminal.integrated.tabs.title` to include `${sequence}` so VS Code
- * renders OSC 0 escape sequences written by the set-terminal-title hook.
- *
- * Idempotent — only writes if the setting is missing or doesn't already
- * include `${sequence}`.
- *
- * @param {string} [homeDirOverride] - Override home directory (for testing)
- * @returns {Promise<{ updated: boolean, path: string|null, alreadySet: boolean }>}
- */
-export async function installVSCodeTerminalSettings(homeDirOverride = null) {
-  const home = homeDirOverride || homedir();
-
-  let settingsPath;
-  if (process.platform === 'win32') {
-    settingsPath = join(home, 'AppData', 'Roaming', 'Code', 'User', 'settings.json');
-  } else if (process.platform === 'darwin') {
-    settingsPath = join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
-  } else {
-    settingsPath = join(home, '.config', 'Code', 'User', 'settings.json');
-  }
-
-  if (!existsSync(settingsPath)) {
-    return { updated: false, path: settingsPath, alreadySet: false };
-  }
-
-  let settings;
-  try {
-    settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-  } catch {
-    settings = {};
-  }
-
-  const KEY = 'terminal.integrated.tabs.title';
-  const current = settings[KEY] || '';
-  if (current.includes('${sequence}')) {
-    return { updated: false, path: settingsPath, alreadySet: true };
-  }
-
-  settings[KEY] = '${sequence}${separator}${local}';
-  await writeFile(settingsPath, JSON.stringify(settings, null, 4) + '\n', 'utf-8');
-  return { updated: true, path: settingsPath, alreadySet: false };
-}
-
-/**
- * Install shell integration for Claude Code terminal title.
- *
- * Writes a wrapper function to the user's shell profile that:
- * 1. Starts a background job watching ~/.claude/terminal_title
- * 2. Updates the terminal tab title in real time via Console.Title (PS) / OSC 0 (bash)
- * 3. Resets the title when the `claude` command exits
- *
- * On Windows: installs to PowerShell 5.1 and/or PowerShell 7 profiles.
- * On Linux/macOS: installs to ~/.bashrc and/or ~/.zshrc (if they exist).
- *
- * Idempotent — skips if the integration block is already present.
- *
- * @param {string} [homeDirOverride] - Override home directory (for testing)
- * @returns {Promise<{ installed: string[], skipped: string[], errors: string[] }>}
- */
-export async function installShellIntegration(homeDirOverride = null) {
-  const home = homeDirOverride || homedir();
-  const installed = [];
-  const skipped = [];
-  const errors = [];
-
-  if (process.platform === 'win32') {
-    const profiles = [
-      join(home, 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1'),
-      join(home, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1'),
-    ];
-    for (const profilePath of profiles) {
-      try {
-        const result = await _appendShellBlock(profilePath, _buildPowerShellBlock(), _psAlreadyInstalled);
-        if (result === 'installed') installed.push(profilePath);
-        else skipped.push(profilePath);
-      } catch (err) {
-        errors.push(profilePath + ': ' + err.message);
-      }
-    }
-  } else {
-    const bashBlock = _buildBashBlock();
-    for (const profilePath of [join(home, '.bashrc'), join(home, '.zshrc')]) {
-      if (!existsSync(profilePath)) continue;
-      try {
-        const result = await _appendShellBlock(profilePath, bashBlock, _bashAlreadyInstalled);
-        if (result === 'installed') installed.push(profilePath);
-        else skipped.push(profilePath);
-      } catch (err) {
-        errors.push(profilePath + ': ' + err.message);
-      }
-    }
-  }
-
-  return { installed, skipped, errors };
-}
-
-/** @returns {string} PowerShell integration block */
-function _buildPowerShellBlock() {
-  return [
-    '',
-    '# === Claude Code terminal title integration (morph-spec) ===',
-    '# Per-session title file prevents cross-session title contamination.',
-    '$script:_claudeExe = Get-Command claude -CommandType Application -ErrorAction SilentlyContinue |',
-    '    Select-Object -First 1 -ExpandProperty Source',
-    '',
-    'function _Start-ClaudeTitleWatcher {',
-    '    param([string]$TitleFile)',
-    '    $rs = [runspacefactory]::CreateRunspace()',
-    '    $rs.Open()',
-    '    $ps = [powershell]::Create()',
-    '    $ps.Runspace = $rs',
-    '    [void]$ps.AddScript({',
-    '        param($f)',
-    '        $last = ""',
-    '        while ($true) {',
-    '            if (Test-Path $f) {',
-    '                try {',
-    '                    $t = (Get-Content $f -Raw -ErrorAction Stop).Trim()',
-    '                    if ($t -and $t -ne $last) {',
-    '                        [Console]::Title = $t',
-    '                        $last = $t',
-    '                    }',
-    '                } catch {}',
-    '            }',
-    '            Start-Sleep -Milliseconds 500',
-    '        }',
-    '    }).AddArgument($TitleFile)',
-    '    $ps.BeginInvoke() | Out-Null',
-    '    return $ps',
-    '}',
-    '',
-    'function Invoke-Claude {',
-    '    [CmdletBinding()]',
-    '    param([Parameter(ValueFromRemainingArguments=$true)][string[]]$Arguments)',
-    '    if (-not $script:_claudeExe) { Write-Error "claude executable not found in PATH"; return }',
-    '    # Per-session file: each Invoke-Claude gets its own title file so multiple',
-    '    # open terminals don\'t overwrite each other\'s titles.',
-    '    $sessionTitleFile = Join-Path $HOME ".claude\\terminal_title_$(New-Guid)"',
-    '    $env:MORPH_TERMINAL_TITLE_FILE = $sessionTitleFile',
-    '    $watcher = _Start-ClaudeTitleWatcher -TitleFile $sessionTitleFile',
-    '    try {',
-    '        & $script:_claudeExe @Arguments',
-    '    } finally {',
-    '        try { $watcher.Stop(); $watcher.Dispose() } catch {}',
-    '        $env:MORPH_TERMINAL_TITLE_FILE = $null',
-    '        Remove-Item $sessionTitleFile -ErrorAction SilentlyContinue',
-    '        [Console]::Title = "PowerShell"',
-    '    }',
-    '}',
-    'Set-Alias -Name claude -Value Invoke-Claude -Force',
-    '# === End Claude Code terminal title integration (morph-spec) ===',
-  ].join('\n');
-}
-
-/** @returns {string} Bash/Zsh integration block */
-function _buildBashBlock() {
-  return [
-    '',
-    '# === Claude Code terminal title integration (morph-spec) ===',
-    '# Per-session title file prevents cross-session title contamination.',
-    '_claude_title_watcher() {',
-    '  local title_file="$1"',
-    '  local last_title=""',
-    '  while true; do',
-    '    if [ -f "$title_file" ]; then',
-    '      local current',
-    '      current=$(cat "$title_file" 2>/dev/null)',
-    '      if [ -n "$current" ] && [ "$current" != "$last_title" ]; then',
-    "        printf '\\e]0;%s\\a' \"$current\"",
-    '        last_title="$current"',
-    '      fi',
-    '    fi',
-    '    sleep 0.5',
-    '  done',
-    '}',
-    '',
-    'claude() {',
-    '  # Per-session file: each invocation gets its own title file so multiple',
-    '  # open terminals don\'t overwrite each other\'s titles.',
-    '  local SESSION_TITLE_FILE',
-    '  SESSION_TITLE_FILE="$HOME/.claude/terminal_title_$$_$RANDOM"',
-    '  export MORPH_TERMINAL_TITLE_FILE="$SESSION_TITLE_FILE"',
-    '  _claude_title_watcher "$SESSION_TITLE_FILE" &',
-    '  local WATCHER_PID=$!',
-    '  command claude "$@"',
-    '  local EXIT_CODE=$?',
-    '  kill "$WATCHER_PID" 2>/dev/null',
-    '  wait "$WATCHER_PID" 2>/dev/null',
-    '  unset MORPH_TERMINAL_TITLE_FILE',
-    '  rm -f "$SESSION_TITLE_FILE"',
-    "  printf '\\e]0;claude\\a'",
-    '  return $EXIT_CODE',
-    '}',
-    '# === End Claude Code terminal title integration (morph-spec) ===',
-  ].join('\n');
-}
-
-/** Check if PowerShell profile already has the integration */
-function _psAlreadyInstalled(content) {
-  return content.includes('Invoke-Claude') || content.includes('_Start-ClaudeTitleWatcher');
-}
-
-/** Check if bash/zsh profile already has the integration */
-function _bashAlreadyInstalled(content) {
-  return content.includes('_claude_title_watcher') || content.includes('command claude "$@"');
-}
-
-/**
- * Append a shell block to a profile file if not already present.
- * Creates the file (and parent dirs) if it doesn't exist.
- * @param {string} profilePath
- * @param {string} block
- * @param {(content: string) => boolean} isInstalled
- * @returns {Promise<'installed'|'skipped'>}
- */
-async function _appendShellBlock(profilePath, block, isInstalled) {
-  let existing = '';
-  let isUtf16le = false;
-
-  if (existsSync(profilePath)) {
-    const raw = await readFile(profilePath);
-    // Detect UTF-16LE: starts with FF FE BOM or has null bytes in the first bytes
-    isUtf16le = (raw[0] === 0xFF && raw[1] === 0xFE) ||
-                (raw.length >= 4 && raw[1] === 0 && raw[3] === 0);
-    existing = isUtf16le ? raw.toString('utf16le').replace(/^\uFEFF/, '') : raw.toString('utf-8');
-  }
-
-  if (isInstalled(existing)) return 'skipped';
-
-  const dir = dirname(profilePath);
-  if (!existsSync(dir)) {
-    await mkdir(dir, { recursive: true });
-  }
-
-  // Always write as UTF-8; trim trailing whitespace from UTF-16LE-decoded content
-  const base = isUtf16le ? existing.trimEnd() + '\n' : existing;
-  await writeFile(profilePath, base + block + '\n', 'utf-8');
-  return 'installed';
-}
-
-/**
- * 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'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/user-prompt/set-terminal-title.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 };
+}
+
+/**
+ * Install VS Code terminal settings to enable OSC title sequences.
+ *
+ * Sets `terminal.integrated.tabs.title` to include `${sequence}` so VS Code
+ * renders OSC 0 escape sequences written by the set-terminal-title hook.
+ *
+ * Idempotent — only writes if the setting is missing or doesn't already
+ * include `${sequence}`.
+ *
+ * @param {string} [homeDirOverride] - Override home directory (for testing)
+ * @returns {Promise<{ updated: boolean, path: string|null, alreadySet: boolean }>}
+ */
+export async function installVSCodeTerminalSettings(homeDirOverride = null) {
+  const home = homeDirOverride || homedir();
+
+  let settingsPath;
+  if (process.platform === 'win32') {
+    settingsPath = join(home, 'AppData', 'Roaming', 'Code', 'User', 'settings.json');
+  } else if (process.platform === 'darwin') {
+    settingsPath = join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
+  } else {
+    settingsPath = join(home, '.config', 'Code', 'User', 'settings.json');
+  }
+
+  if (!existsSync(settingsPath)) {
+    return { updated: false, path: settingsPath, alreadySet: false };
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    settings = {};
+  }
+
+  const KEY = 'terminal.integrated.tabs.title';
+  const current = settings[KEY] || '';
+  if (current.includes('${sequence}')) {
+    return { updated: false, path: settingsPath, alreadySet: true };
+  }
+
+  settings[KEY] = '${sequence}${separator}${local}';
+  await writeFile(settingsPath, JSON.stringify(settings, null, 4) + '\n', 'utf-8');
+  return { updated: true, path: settingsPath, alreadySet: false };
+}
+
+/**
+ * Install shell integration for Claude Code terminal title.
+ *
+ * Writes a wrapper function to the user's shell profile that:
+ * 1. Starts a background job watching ~/.claude/terminal_title
+ * 2. Updates the terminal tab title in real time via Console.Title (PS) / OSC 0 (bash)
+ * 3. Resets the title when the `claude` command exits
+ *
+ * On Windows: installs to PowerShell 5.1 and/or PowerShell 7 profiles.
+ * On Linux/macOS: installs to ~/.bashrc and/or ~/.zshrc (if they exist).
+ *
+ * Idempotent — skips if the integration block is already present.
+ *
+ * @param {string} [homeDirOverride] - Override home directory (for testing)
+ * @returns {Promise<{ installed: string[], skipped: string[], errors: string[] }>}
+ */
+export async function installShellIntegration(homeDirOverride = null) {
+  const home = homeDirOverride || homedir();
+  const installed = [];
+  const skipped = [];
+  const errors = [];
+
+  if (process.platform === 'win32') {
+    const profiles = [
+      join(home, 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1'),
+      join(home, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1'),
+    ];
+    for (const profilePath of profiles) {
+      try {
+        const result = await _appendShellBlock(profilePath, _buildPowerShellBlock(), _psAlreadyInstalled);
+        if (result === 'installed') installed.push(profilePath);
+        else skipped.push(profilePath);
+      } catch (err) {
+        errors.push(profilePath + ': ' + err.message);
+      }
+    }
+  } else {
+    const bashBlock = _buildBashBlock();
+    for (const profilePath of [join(home, '.bashrc'), join(home, '.zshrc')]) {
+      if (!existsSync(profilePath)) continue;
+      try {
+        const result = await _appendShellBlock(profilePath, bashBlock, _bashAlreadyInstalled);
+        if (result === 'installed') installed.push(profilePath);
+        else skipped.push(profilePath);
+      } catch (err) {
+        errors.push(profilePath + ': ' + err.message);
+      }
+    }
+  }
+
+  return { installed, skipped, errors };
+}
+
+/** @returns {string} PowerShell integration block */
+function _buildPowerShellBlock() {
+  return [
+    '',
+    '# === Claude Code terminal title integration (morph-spec) ===',
+    '# Per-session title file prevents cross-session title contamination.',
+    '$script:_claudeExe = Get-Command claude -CommandType Application -ErrorAction SilentlyContinue |',
+    '    Select-Object -First 1 -ExpandProperty Source',
+    '',
+    'function _Start-ClaudeTitleWatcher {',
+    '    param([string]$TitleFile)',
+    '    $rs = [runspacefactory]::CreateRunspace()',
+    '    $rs.Open()',
+    '    $ps = [powershell]::Create()',
+    '    $ps.Runspace = $rs',
+    '    [void]$ps.AddScript({',
+    '        param($f)',
+    '        $last = ""',
+    '        while ($true) {',
+    '            if (Test-Path $f) {',
+    '                try {',
+    '                    $t = (Get-Content $f -Raw -ErrorAction Stop).Trim()',
+    '                    if ($t -and $t -ne $last) {',
+    '                        [Console]::Title = $t',
+    '                        $last = $t',
+    '                    }',
+    '                } catch {}',
+    '            }',
+    '            Start-Sleep -Milliseconds 500',
+    '        }',
+    '    }).AddArgument($TitleFile)',
+    '    $ps.BeginInvoke() | Out-Null',
+    '    return $ps',
+    '}',
+    '',
+    'function Invoke-Claude {',
+    '    [CmdletBinding()]',
+    '    param([Parameter(ValueFromRemainingArguments=$true)][string[]]$Arguments)',
+    '    if (-not $script:_claudeExe) { Write-Error "claude executable not found in PATH"; return }',
+    '    # Per-session file: each Invoke-Claude gets its own title file so multiple',
+    '    # open terminals don\'t overwrite each other\'s titles.',
+    '    $sessionTitleFile = Join-Path $HOME ".claude\\terminal_title_$(New-Guid)"',
+    '    $env:MORPH_TERMINAL_TITLE_FILE = $sessionTitleFile',
+    '    $watcher = _Start-ClaudeTitleWatcher -TitleFile $sessionTitleFile',
+    '    try {',
+    '        & $script:_claudeExe @Arguments',
+    '    } finally {',
+    '        try { $watcher.Stop(); $watcher.Dispose() } catch {}',
+    '        $env:MORPH_TERMINAL_TITLE_FILE = $null',
+    '        Remove-Item $sessionTitleFile -ErrorAction SilentlyContinue',
+    '        [Console]::Title = "PowerShell"',
+    '    }',
+    '}',
+    'Set-Alias -Name claude -Value Invoke-Claude -Force',
+    '# === End Claude Code terminal title integration (morph-spec) ===',
+  ].join('\n');
+}
+
+/** @returns {string} Bash/Zsh integration block */
+function _buildBashBlock() {
+  return [
+    '',
+    '# === Claude Code terminal title integration (morph-spec) ===',
+    '# Per-session title file prevents cross-session title contamination.',
+    '_claude_title_watcher() {',
+    '  local title_file="$1"',
+    '  local last_title=""',
+    '  while true; do',
+    '    if [ -f "$title_file" ]; then',
+    '      local current',
+    '      current=$(cat "$title_file" 2>/dev/null)',
+    '      if [ -n "$current" ] && [ "$current" != "$last_title" ]; then',
+    "        printf '\\e]0;%s\\a' \"$current\"",
+    '        last_title="$current"',
+    '      fi',
+    '    fi',
+    '    sleep 0.5',
+    '  done',
+    '}',
+    '',
+    'claude() {',
+    '  # Per-session file: each invocation gets its own title file so multiple',
+    '  # open terminals don\'t overwrite each other\'s titles.',
+    '  local SESSION_TITLE_FILE',
+    '  SESSION_TITLE_FILE="$HOME/.claude/terminal_title_$$_$RANDOM"',
+    '  export MORPH_TERMINAL_TITLE_FILE="$SESSION_TITLE_FILE"',
+    '  _claude_title_watcher "$SESSION_TITLE_FILE" &',
+    '  local WATCHER_PID=$!',
+    '  command claude "$@"',
+    '  local EXIT_CODE=$?',
+    '  kill "$WATCHER_PID" 2>/dev/null',
+    '  wait "$WATCHER_PID" 2>/dev/null',
+    '  unset MORPH_TERMINAL_TITLE_FILE',
+    '  rm -f "$SESSION_TITLE_FILE"',
+    "  printf '\\e]0;claude\\a'",
+    '  return $EXIT_CODE',
+    '}',
+    '# === End Claude Code terminal title integration (morph-spec) ===',
+  ].join('\n');
+}
+
+/** Check if PowerShell profile already has the integration */
+function _psAlreadyInstalled(content) {
+  return content.includes('Invoke-Claude') || content.includes('_Start-ClaudeTitleWatcher');
+}
+
+/** Check if bash/zsh profile already has the integration */
+function _bashAlreadyInstalled(content) {
+  return content.includes('_claude_title_watcher') || content.includes('command claude "$@"');
+}
+
+/**
+ * Append a shell block to a profile file if not already present.
+ * Creates the file (and parent dirs) if it doesn't exist.
+ * @param {string} profilePath
+ * @param {string} block
+ * @param {(content: string) => boolean} isInstalled
+ * @returns {Promise<'installed'|'skipped'>}
+ */
+async function _appendShellBlock(profilePath, block, isInstalled) {
+  let existing = '';
+  let isUtf16le = false;
+
+  if (existsSync(profilePath)) {
+    const raw = await readFile(profilePath);
+    // Detect UTF-16LE: starts with FF FE BOM or has null bytes in the first bytes
+    isUtf16le = (raw[0] === 0xFF && raw[1] === 0xFE) ||
+                (raw.length >= 4 && raw[1] === 0 && raw[3] === 0);
+    existing = isUtf16le ? raw.toString('utf16le').replace(/^\uFEFF/, '') : raw.toString('utf-8');
+  }
+
+  if (isInstalled(existing)) return 'skipped';
+
+  const dir = dirname(profilePath);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+
+  // Always write as UTF-8; trim trailing whitespace from UTF-16LE-decoded content
+  const base = isUtf16le ? existing.trimEnd() + '\n' : existing;
+  await writeFile(profilePath, base + block + '\n', 'utf-8');
+  return 'installed';
+}
+
+/**
+ * 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;
+}