@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/utils/hooks-installer.js

@@ -1,13 +1,3 @@
-/**
- * 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 } from 'fs/promises';
 import { existsSync, chmodSync, readdirSync } from 'fs';
@@ -15,130 +5,37 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 import { realEffects } from '../lib/installers/effects.js';
 
-/**
- * Current hooks schema version — bump when hook definitions change.
- *
- * 3.6.0 (R2 of the performance plan) consolidates spawns: every core hook now
- * exports `run(payload)` (framework/hooks/claude-code/core/*.js) and the
- * registry below routes multi-hook event+matcher groups through the new
- * `core/chain.js`, which imports and runs several hooks' `run()` in ONE node
- * process instead of one process per hook. Same events, same matchers, same
- * observable behavior (block/warn/silent) — only the process count per
- * Write/Edit drops (9 → 4). The hook files are re-copied unconditionally
- * (`copyDirectory` defaults to `overwrite: true`), so the bump does not gate
- * delivery — it makes `morph-spec update` report the change honestly instead
- * of "already current".
- *
- * 3.8.0 (worktree governance) registers Claude Code's WorktreeCreate /
- * WorktreeRemove events — the native `claude -w` / EnterWorktree / Agent
- * isolation worktree is replaced by `morph-spec worktree setup|provision`
- * (junctions, port block, primary-root landing) and its removal routed
- * through the safe `worktree remove --if-clean` — and appends
- * block-raw-worktree-add to the PreToolUse:Bash chain.
- *
- * 3.9.0 binds telemetry-log to PostToolUseFailure (a Bash command that exits
- * non-zero fires only that event, so red runs used to vanish from the log),
- * PostToolBatch (once per model turn that used tools) and SubagentStop (the
- * sub-agent's own token usage). The three only record, so they run with
- * `async: true`: a node process per model turn never holds the turn up.
- *
- * 3.10.0 appends graph-refresh-kick to the all-tools PostToolUse chain: after a
- * Bash or PowerShell command that runs git/gh/morph-spec it launches the
- * detached refresh of the ROOT's codebase graph
- * (framework/hooks/shared/graph-refresh.js). `update` re-runs
- * this installer, so installed projects get the refresh without re-running
- * `setup-infra` — the step that never reached them.
- *
- * 3.11.0 writes every `timeout` in seconds, the unit Claude Code reads: the
- * values were milliseconds, so a hung hook held the session for hours (120000
- * on WorktreeCreate is 33 h) instead of the seconds they meant.
- *
- * 3.12.0 adds heavy-gate to the Bash PreToolUse chain and heavy-release to the
- * PostToolUse and PostToolUseFailure chains: the opt-in `heavy.gateBash`.
- *
- * 3.13.0 adds warn-bash-source-write to the Bash PreToolUse chain: a warning,
- * never a block, when a command writes project source through a redirect.
- */
 const HOOKS_VERSION = '3.13.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.
- *
- * `Edit(path)` ONLY — never a matching `Write(path)`. Claude Code matches file
- * permissions on `Edit(path)` rules alone; an `Edit` rule covers every
- * file-editing tool, Write included, while a `Write(path)` rule matches nothing
- * and is reported as a warning on every session start. Verified empirically, not
- * assumed: with `Edit(.morph/framework/**)` as the ONLY deny entry, the Write
- * tool was refused and the target file was never created.
- */
+// `Edit(path)` only: an Edit rule also covers Write, while a `Write(path)` rule
+// matches nothing and makes Claude Code warn on every session start.
 const MORPH_DENY = [
-  // Framework files — installer-managed, immutable at runtime
   'Edit(.morph/framework/**)',
-  // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE.md)
   'Edit(.claude/CLAUDE.md)',
-  // .claude/rules/ (copied from framework/rules/)
   'Edit(.claude/rules/**)',
-  // .claude/agents/morph-* (generated by agents-installer)
   'Edit(.claude/agents/morph-*)',
-  // .claude/skills/ (copied from framework/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
- * plan.md / slice report write.
- *
- * `Edit(path)` ONLY, for the same reason as MORPH_DENY: the `Edit` rule already
- * covers Write, and a `Write(path)` rule is inert noise.
- */
 const MORPH_ALLOW = [
-  // Feature artifacts — the agent's working directory during plan/uiux/implement/review
   '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 planning
   'Edit(.morph/context/**)',
-  // Folder creation under .morph
   'Bash(mkdir:.morph/**)',
   'Bash(ls:.morph/**)',
-  // Gate 3 mutation round: restores bytes itself and has --restore; an auto-mode deny pauses the gate
+  // An auto-mode deny here pauses the review mutation round.
   'Bash(morph-spec mutate:*)',
   'Bash(npx morph-spec mutate:*)',
 ];
 
-// 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.
- *
- * R2 consolidation: an entry whose group has more than one hook now declares
- * ONE `core/chain.js` command with an `args` array (the hook base names, in
- * the ORDER they run) instead of one command per hook — chain.js imports and
- * calls each hook's `run(payload)` in that same process (see its own doc
- * comment for the block-first-wins / context-concatenation rules). A group
- * with exactly one hook stays a direct command — chaining a single link buys
- * nothing. `args` must stay a SEPARATE field from `command`: `getHookSubpath()`
- * below extracts the installed path from `command` alone via a regex anchored
- * on `claude-code/`, and inlining args into that string would get captured
- * into the quoted path.
- */
+// A multi-hook group is ONE `core/chain.js` command whose `args` list the hooks in
+// run order (block-first-wins). `args` stays separate from `command`: getHookSubpath()
+// would capture inlined args into the quoted path. `timeout` is in SECONDS.
 const MORPH_HOOKS = [
-  // === SessionStart — worktree feature identity (secondary worktree) or
-  // active-feature summary (primary root). Fulfills the SessionStart
-  // injection role long documented but never wired (inject-morph-context.js).
-  // Solo (only hook for this event) — nothing to chain. ===
   {
     event: 'SessionStart',
     matcher: null,
@@ -149,13 +46,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PreToolUse: Write|Edit — phase + spec protection (silent on success).
-  // Chained in the SAME order the previous two-entry registry ran them:
-  // protect-spec-files (locked-file check) before enforce-phase-writes (phase
-  // folder check) — a block from either one wins and skips the other. Neither
-  // hook declared its own timeout (both are pure sync fs checks with no
-  // subprocess calls), so the chain declares none either — same platform
-  // default both relied on individually. ===
   {
     event: 'PreToolUse',
     matcher: 'Write|Edit',
@@ -166,21 +56,8 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PreToolUse: Bash — irreversible-command guards, chained (block-first-
-  // wins, one process). pre-bash-denylist (static pattern list) runs before
-  // block-destructive-worktree-removal (dynamic: scans the target for reparse
-  // points), so the cheap check short-circuits the filesystem walk. The second
-  // one is the only defense against the raw-removal vector that does not depend
-  // on someone having read MORPH.md. block-raw-worktree-add is its way-IN
-  // counterpart (a raw `git worktree add` builds a tree with no junctions, no
-  // ports, no identity) — static, so it costs nothing after the first two.
-  // warn-bash-source-write only adds context (source written by redirect skips
-  // the Write/Edit guards); after the guards, so a blocked command is not warned.
-  // heavy-gate comes after every guard — it takes a slot, and a command a guard
-  // blocks must not hold one — and before the rewriter.
-  // worktree-env-inject is LAST: it rewrites launcher commands (updatedInput)
-  // with the worktree's port block, and a command a previous link blocked must
-  // never be rewritten. Block-first-wins guarantees it never sees one.
+  // heavy-gate after every guard (a blocked command must not hold a slot);
+  // worktree-env-inject LAST so a command a previous link blocked is never rewritten.
   {
     event: 'PreToolUse',
     matcher: 'Bash',
@@ -191,12 +68,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === WorktreeCreate — REPLACES Claude Code's native `git worktree add` for
-  // `claude -w`, the EnterWorktree tool and `Agent isolation:"worktree"`
-  // (measured: all three fire it). The hook prints the created path as its
-  // last stdout line; a non-zero exit fails the creation. No matcher exists
-  // for this event. 120s: it spawns the morph-spec CLI (setup or provision),
-  // which runs git, links infra, allocates ports and materializes state. ===
   {
     event: 'WorktreeCreate',
     matcher: null,
@@ -207,11 +78,7 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === WorktreeRemove — routes Claude Code's own cleanup through
-  // `morph-spec worktree remove --target --if-clean` (junctions dropped BEFORE
-  // git touches the tree; a dirty tree is left alone). Output ignored, always
-  // exit 0. Secondary net: in headless runs the event was observed not to
-  // fire — block-destructive-worktree-removal remains the primary defense. ===
+  // Not fired in headless runs: block-destructive-worktree-removal stays the primary defense.
   {
     event: 'WorktreeRemove',
     matcher: null,
@@ -222,8 +89,7 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PostToolUse: Write|Edit — comment-guard, solo: it blocks the edit that
-  // adds a forbidden comment. ===
+  // comment-guard must be the last Write|Edit link: a block ends the chain.
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
@@ -233,16 +99,7 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous
-  // state.json updates) then gate-guard. gate-guard runs AFTER state-sync so
-  // it sees the gate that state-sync just recorded — now true within a single
-  // process too, because state-writer.js's persistFeature() invalidates
-  // state-reader.js's per-process loadState() memo on every write (R1.1 added
-  // that memo; without the invalidation, a chained gate-guard could read the
-  // pre-write snapshot). Both are silent fail-open guardrails; gate-guard only
-  // warns (never blocks) when an observed gate action disagrees with the
-  // persisted gateDecisions (issue #63). Both links declared 3000ms; sequential
-  // execution means the worst case is additive, so the chain declares the sum. ===
+  // gate-guard after state-sync so it sees the gate state-sync just recorded.
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit|AskUserQuestion',
@@ -254,15 +111,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PostToolUse: All — telemetry capture (silent) + loop detection +
-  // graph refresh kick. telemetry-log is the single generic vantage point of an
-  // NLH: it appends every tool call (skill, sub-agent dispatch, knowledge-base
-  // read, …) to .morph/logs/events.jsonl. Silent and fail-open — never blocks,
-  // never injects. `morph-spec telemetry` reads the stream back.
-  // graph-refresh-kick only spawns a DETACHED worker (never waits on graphify),
-  // so it rides this chain instead of costing a process of its own per Bash
-  // call. Timeout stays the sum of the first two links (sequential worst case);
-  // the kick returns in milliseconds. ===
   {
     event: 'PostToolUse',
     matcher: null,
@@ -274,9 +122,7 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PostToolUseFailure: All — telemetry of the failed call (exit code,
-  // duration). loop-detect stays out: its warning is shaped for PostToolUse.
-  // heavy-release gives back the slot of a heavy Bash call that failed.
+  // Recording-only bindings are `async: true`; a hook that decides is never async.
   {
     event: 'PostToolUseFailure',
     matcher: null,
@@ -289,8 +135,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PostToolBatch — one event per model turn that used tools. The event
-  // takes no matcher. ===
   {
     event: 'PostToolBatch',
     matcher: null,
@@ -302,8 +146,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === SubagentStop — the sub-agent's token usage, read from its own
-  // transcript (the session transcript does not include it). ===
   {
     event: 'SubagentStop',
     matcher: null,
@@ -315,10 +157,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === UserPromptSubmit — telemetry capture of the user's prompt (silent).
-  // The only vantage point on the user's own prompt; completes the execution
-  // path alongside sub-agent prompts captured on PostToolUse. Solo (the only
-  // hook registered on this event) — nothing to chain. ===
   {
     event: 'UserPromptSubmit',
     matcher: null,
@@ -329,7 +167,6 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === Stop — build check + session snapshot. Solo. ===
   {
     event: 'Stop',
     matcher: null,
@@ -341,25 +178,13 @@ const MORPH_HOOKS = [
 ];
 
 /**
- * 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
- * @param {object} [options]
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
- *   Coletor de efeitos. Esta função é o seam mais barato do caminho de update:
- *   o objeto de settings INTEIRO já é montado em memória e há UMA escrita, no
- *   fim. Previsão e execução percorrem a mesma montagem.
+ * Idempotent merge of the MORPH-SPEC hooks into `.claude/settings.local.json`.
  * @returns {Promise<{ installed: number, updated: boolean }>}
  */
 export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}) {
   const claudeDir = join(targetPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.local.json');
 
-  // Read existing settings or start empty
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
@@ -371,17 +196,12 @@ export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}
 
   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;
@@ -395,11 +215,6 @@ export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}
       entry.matcher = matcher;
     }
     entry.hooks = hooks.map(h => {
-      // Command hooks: transform path to use $CLAUDE_PROJECT_DIR.
-      // Hooks are copied to .morph/framework/hooks/ during `morph-spec init/update`.
-      // `args` (chain.js's hook-name list) is appended AFTER the closing quote —
-      // getHookSubpath() below only ever sees the bare `h.command` path, never
-      // the args, so it can't accidentally capture them into the quoted command.
       const quotedPath = `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/claude-code/${getHookSubpath(h.command)}"`;
       const command = h.args?.length ? `${quotedPath} ${h.args.join(' ')}` : quotedPath;
       return {
@@ -414,18 +229,12 @@ export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}
     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 morph-managed entries we no longer install.
-  // The filters below drop `MORPH_*.includes(p)` before re-adding, so an entry
-  // that LEFT those lists would otherwise survive forever in an existing
-  // install — the upgrade path has to name it explicitly to reclaim it.
-  //   - state.json: was in deny pre-v7, now lives in allow.
-  //   - Write(...): matched nothing and made Claude Code warn on every session
-  //     start; the paired Edit(...) rule is what actually enforced them.
+  // An entry that left MORPH_* would survive forever in an existing install
+  // unless named here.
   const STALE_DENY = [
     'Write(.morph/state.json)',
     'Edit(.morph/state.json)',
@@ -453,17 +262,14 @@ export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}
     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',
@@ -471,29 +277,21 @@ export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}
     };
   }
 
-  // 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
   fx.ensureDir(claudeDir);
 
   fx.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   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']) {
@@ -504,15 +302,12 @@ function findPython() {
     }
     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;
@@ -520,7 +315,7 @@ function findPython() {
     const py3 = dirs
       .filter(d => /^Python3\d*/i.test(d))
       .sort()
-      .reverse(); // prefer highest version
+      .reverse();
     for (const dir of py3) {
       const exe = join(base, dir, 'python.exe');
       if (existsSync(exe)) return exe;
@@ -529,15 +324,6 @@ function findPython() {
   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...');
@@ -551,7 +337,6 @@ function tryInstallPython() {
     } 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 {
@@ -567,53 +352,26 @@ function tryInstallPython() {
   }
 }
 
-/**
- * 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)
- * @param {object} [options]
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
- *   Coletor de efeitos. Estes são os efeitos FORA do projeto — o relatório do
- *   `--dry-run` é obrigado a nomeá-los separadamente, porque ninguém os
- *   adivinha da palavra "update".
+ * Writes OUTSIDE the project (`~/.claude/`), so `--dry-run` must name these effects separately.
  * @returns {Promise<{ installed: boolean, globalDir: string }>}
  */
 export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null, { fx = realEffects() } = {}) {
   const globalDir = globalClaudeDirOverride || join(homedir(), '.claude');
   fx.ensureDir(globalDir);
 
-  // Copy statusline scripts to ~/.claude/
   const scripts = ['statusline.sh', 'statusline.py'];
   for (const fname of scripts) {
     const src = join(hooksSourceDir, fname);
@@ -625,21 +383,15 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
     }
   }
 
-  // Register statusLine in ~/.claude/settings.json (global user settings)
   const settingsPath = join(globalDir, 'settings.json');
 
-  // On Windows, Claude Code cannot execute .sh files directly — call Python instead.
+  // Claude Code on Windows cannot execute .sh directly.
   const statuslineCommand = process.platform === 'win32'
     ? `"${resolvePythonForStatusline()}" "${join(globalDir, 'statusline.py').replace(/\\/g, '/')}"`
     : join(globalDir, 'statusline.sh').replace(/\\/g, '/');
 
-  // refreshInterval: without it the status line only re-renders on events
-  // (new assistant message, /compact, permission or vim mode change), so the
-  // `↻` countdown to the 5h rate-limit reset — the only widget that moves on
-  // its own — sits frozen through a long turn. Everything else is event-driven
-  // and would be fine without this.
-  // Fusão rasa: só `statusLine` é do morph-spec; tudo o mais no
-  // `~/.claude/settings.json` é do usuário e sobrevive intocado.
+  // Without refreshInterval the status line only re-renders on events, freezing
+  // the rate-limit countdown through a long turn. Shallow merge: only `statusLine` is ours.
   fx.mergeJson(settingsPath, {
     statusLine: {
       type: 'command',
@@ -651,12 +403,6 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
   return { installed: true, globalDir };
 }
 
-
-
-/**
- * Remove old v1 agent-teams/dispatch.js hook entries.
- * @param {Object} settings
- */
 function removeOldDispatch(settings) {
   if (!settings.hooks?.PostToolUse) return;
 
@@ -673,12 +419,6 @@ function removeOldDispatch(settings) {
   }
 }
 
-/**
- * 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\//;
 
@@ -686,14 +426,10 @@ function removeMorphHooks(settings) {
     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.
+      // Fallback for entries written before the `_morph` marker existed.
       const nonMorphHooks = entry.hooks.filter(h =>
         typeof h.command !== 'string' || !morphPathPattern.test(h.command)
       );
@@ -706,28 +442,15 @@ function removeMorphHooks(settings) {
   }
 }
 
-/**
- * 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;
 }