claws-code 0.8.0

package/scripts/inject-dev-hooks.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// inject-dev-hooks.js — Register Claws dev-discipline hooks into a project's
+// .claude/settings.json. Idempotent: detects existing hooks by _source tag
+// and updates in place. Safe-merge: uses json-safe.mjs mergeIntoFile —
+// atomic write, JSONC-tolerant, abort-on-malformed (FINDING-B-3).
+//
+// Claude Code settings.json hooks format:
+//   { hooks: { SessionStart: [{matcher, hooks:[{type,command}], _source}], ... } }
+//
+// Usage: node scripts/inject-dev-hooks.js [project-root]
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const SOURCE_TAG = 'claws-dev-hooks';
+
+const HELPERS_MJS = pathToFileURL(
+  path.resolve(__dirname, '_helpers', 'json-safe.mjs')
+).href;
+
+// Five dev-hook definitions — event → script file in .claws-bin/dev-hooks/
+const DEV_HOOK_DEFS = [
+  { event: 'SessionStart', matcher: '*', script: 'check-stale-main.js' },
+  { event: 'PostToolUse',  matcher: 'Bash', script: 'check-tag-pushed.js' },
+  { event: 'PostToolUse',  matcher: 'Bash', script: 'check-tag-vs-main.js' },
+  { event: 'Stop',         matcher: '*', script: 'check-open-claws-terminals.js' },
+  { event: 'SessionStart', matcher: '*', script: 'check-extension-dirs.js' },
+];
+
+function buildEntry(def, binDir) {
+  return {
+    _source: SOURCE_TAG,
+    matcher: def.matcher,
+    hooks: [{ type: 'command', command: `node "${path.join(binDir, def.script)}"` }],
+  };
+}
+
+async function inject(projectRoot) {
+  const { mergeIntoFile } = await import(HELPERS_MJS);
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const binDir = path.join(projectRoot, '.claws-bin', 'dev-hooks');
+
+  let totalRegistered = 0;
+  const result = await mergeIntoFile(settingsPath, (settings) => {
+    // Migrate legacy array format (same guard as inject-settings-hooks.js)
+    if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+      settings.hooks = {};
+    }
+
+    for (const def of DEV_HOOK_DEFS) {
+      if (!Array.isArray(settings.hooks[def.event])) {
+        settings.hooks[def.event] = [];
+      }
+      const arr = settings.hooks[def.event];
+      const newCmd = `node "${path.join(binDir, def.script)}"`;
+      const exactIdx = arr.findIndex(
+        (e) => e._source === SOURCE_TAG && e.hooks && e.hooks[0] && e.hooks[0].command === newCmd
+      );
+      if (exactIdx === -1) {
+        // Also remove any old entry for this script path (from a different binDir)
+        const oldIdx = arr.findIndex(
+          (e) => e._source === SOURCE_TAG && e.hooks && e.hooks[0] &&
+                 e.hooks[0].command.includes(def.script)
+        );
+        if (oldIdx !== -1) arr[oldIdx] = buildEntry(def, binDir);
+        else arr.push(buildEntry(def, binDir));
+      }
+      totalRegistered++;
+    }
+  }, { allowJsonc: true });
+
+  if (!result.ok) {
+    const e = result.error;
+    process.stderr.write(`inject-dev-hooks: settings merge failed: ${e.message}\n`);
+    if (e.backupSavedAt) process.stderr.write(`  original backed up to: ${e.backupSavedAt}\n`);
+    process.exit(1);
+  }
+  return totalRegistered;
+}
+
+const projectRoot = process.argv[2] || process.cwd();
+
+if (!fs.existsSync(projectRoot)) {
+  console.error(`inject-dev-hooks: project root not found: ${projectRoot}`);
+  process.exit(1);
+}
+
+(async () => {
+  const count = await inject(projectRoot);
+  console.log(`  inject-dev-hooks: ${count} hooks ready (_source: "${SOURCE_TAG}")`);
+})().catch((e) => {
+  console.error(`inject-dev-hooks failed: ${e.message}`);
+  process.exit(1);
+});

package/scripts/inject-global-claude-md.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Inject the Claws machine-wide policy block into ~/.claude/CLAUDE.md.
+// Usage: node inject-global-claude-md.js [--dry-run]
+//
+// Behavior:
+// 1. Reads templates/CLAUDE.global.md (relative to this script).
+// 2. Substitutes {VERSION} and {LIFECYCLE_PHASES} from code (package.json,
+//    extension/src/lifecycle-store.ts).
+// 3. Inserts or replaces the fenced block:
+//    <!-- CLAWS-GLOBAL:BEGIN [v<X.Y.Z>] --> ... <!-- CLAWS-GLOBAL:END [v<X.Y.Z>] -->
+//    Sentinel match is regex-based so prior-version blocks upgrade cleanly.
+// 4. Creates ~/.claude/CLAUDE.md with a stub if it doesn't exist.
+// 5. Preserves all non-Claws content byte-for-byte.
+// 6. Idempotent — safe to run on every install.
+
+'use strict';
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// M-28: atomic write helper.
+function writeAtomic(filePath, content) {
+  const tmp = filePath + '.claws-tmp.' + process.pid + '-' + (++writeAtomic._nonce);
+  let _fd;
+  try {
+    _fd = fs.openSync(tmp, 'w', 0o644);
+    fs.writeSync(_fd, content);
+    fs.fsyncSync(_fd);
+    fs.closeSync(_fd);
+    _fd = null;
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    if (_fd != null) { try { fs.closeSync(_fd); } catch { /* ignore */ } }
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+writeAtomic._nonce = 0;
+
+const REPO_ROOT = path.join(__dirname, '..');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+const GLOBAL_CLAUDE_MD = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+const TEMPLATE_PATH    = path.join(REPO_ROOT, 'templates', 'CLAUDE.global.md');
+
+const BEGIN_RE = /<!-- CLAWS-GLOBAL:BEGIN(?: v[\d.]+(?:-[\w.]+)?| v1)? -->/;
+const END_RE   = /<!-- CLAWS-GLOBAL:END(?: v[\d.]+(?:-[\w.]+)?| v1)? -->/;
+
+// ── Source-of-truth readers ────────────────────────────────────────────────
+function readPhases() {
+  const ltPath = path.join(REPO_ROOT, 'extension', 'src', 'lifecycle-store.ts');
+  try {
+    const src = fs.readFileSync(ltPath, 'utf8');
+    const m = src.match(/export type Phase\s*=([^;]+);/);
+    if (!m) return [];
+    return Array.from(m[1].matchAll(/'([A-Z][A-Z0-9-]+)'/g)).map((x) => x[1]);
+  } catch (err) {
+    return [];
+  }
+}
+
+function readVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch (err) {
+    return 'unknown';
+  }
+}
+
+const PHASES = readPhases();
+const VERSION = readVersion();
+
+const BEGIN_LITERAL = `<!-- CLAWS-GLOBAL:BEGIN v${VERSION} -->`;
+const END_LITERAL   = `<!-- CLAWS-GLOBAL:END v${VERSION} -->`;
+
+// Read template
+let template;
+try {
+  template = fs.readFileSync(TEMPLATE_PATH, 'utf8').trim();
+} catch (e) {
+  console.error(`inject-global-claude-md: cannot read template at ${TEMPLATE_PATH}: ${e.message}`);
+  process.exit(1);
+}
+
+// Substitute parameters in the template body, then re-stamp sentinels.
+const phaseChain = PHASES.length ? PHASES.join(' → ') : '(unavailable)';
+template = template
+  .replace(/\{VERSION\}/g, VERSION)
+  .replace(/\{LIFECYCLE_PHASES\}/g, phaseChain)
+  .replace(/<!-- CLAWS-GLOBAL:BEGIN(?: v[\d.]+(?:-[\w.]+)?| v1)? -->/g, BEGIN_LITERAL)
+  .replace(/<!-- CLAWS-GLOBAL:END(?: v[\d.]+(?:-[\w.]+)?| v1)? -->/g, END_LITERAL);
+
+// Ensure template is wrapped in sentinels (it should already be, but guard)
+if (!template.includes(BEGIN_LITERAL)) {
+  template = BEGIN_LITERAL + '\n' + template + '\n' + END_LITERAL;
+}
+
+// Read existing global CLAUDE.md (or start fresh)
+let existing = '';
+let existed  = false;
+try {
+  existing = fs.readFileSync(GLOBAL_CLAUDE_MD, 'utf8');
+  existed  = true;
+} catch { /* file doesn't exist yet */ }
+
+// Insert or replace the fenced block (regex match — accepts any prior version).
+const beginMatch = existing.match(BEGIN_RE);
+const endMatch   = existing.match(END_RE);
+
+let next;
+if (beginMatch && endMatch && endMatch.index > beginMatch.index) {
+  next = existing.slice(0, beginMatch.index) + template + existing.slice(endMatch.index + endMatch[0].length);
+} else if (existed) {
+  const sep = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  next = existing + sep + template + '\n';
+} else {
+  next = '# Claude Code — Machine-Wide Configuration\n\n' +
+    '<!-- Add your personal Claude Code context above this line -->\n\n' +
+    template + '\n';
+}
+
+if (DRY_RUN) {
+  console.log('[dry-run] would write to:', GLOBAL_CLAUDE_MD);
+  console.log(next);
+  process.exit(0);
+}
+
+try { fs.mkdirSync(path.dirname(GLOBAL_CLAUDE_MD), { recursive: true }); } catch { /* ignore */ }
+
+let orig = '';
+try { orig = fs.readFileSync(GLOBAL_CLAUDE_MD, 'utf8'); } catch { /* ignore */ }
+
+if (next !== orig) {
+  writeAtomic(GLOBAL_CLAUDE_MD, next);
+  const action = beginMatch ? 'Claws global block updated' : 'Claws global block inserted';
+  console.log(`~/.claude/CLAUDE.md ${existed ? action : 'created with Claws global block'} (v${VERSION}, ${PHASES.length} phases)`);
+} else {
+  console.log(`~/.claude/CLAUDE.md already has the current Claws global block (v${VERSION})`);
+}

package/scripts/inject-settings-hooks.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+// Register Claws lifecycle hooks into ~/.claude/settings.json.
+// M-03/M-38: uses json-safe.mjs mergeIntoFile — atomic write, JSONC-tolerant,
+// abort-on-malformed (NEVER silently reset to {}).
+//
+// Usage: node inject-settings-hooks.js [claws-bin-dir] [--dry-run] [--remove]
+//
+// Adds hooks (all tagged _source:"claws" for clean uninstall):
+//   SessionStart  — emits lifecycle reminder when .claws/claws.sock detected
+//   PreToolUse    — long-running Bash guard + Edit/Write mcp_server.js guard
+//   PreToolUse (MCP spawn-class) — BUG-28: explicit matchers for claws_create /
+//     claws_worker / claws_fleet / claws_dispatch_subworker so Monitor arm gate
+//     fires even if Claude Code does not propagate the '*' hook to MCP tools.
+//   PostToolUse (MCP spawn-class) — Wave C: fail-close spawn → monitor race window.
+//     After any spawn-class tool succeeds, waits up to 5s for lifecycle.monitors
+//     to register the terminal. If missing, publishes wave.violation + auto-closes.
+//     Explicit per-tool matchers (belt-and-suspenders, matching PreToolUse pattern).
+//   Stop          — kills sidecar, kills tail -F, reminds model to close terminals
+//
+// Idempotent: running twice produces the same result.
+// --remove: strips all _source:"claws" hooks without touching others.
+
+'use strict';
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { pathToFileURL } = require('url');
+
+const DEFAULT_CLAWS_BIN = __dirname;
+const CLAWS_BIN = path.resolve(
+  (process.argv[2] && !process.argv[2].startsWith('--'))
+    ? process.argv[2]
+    : DEFAULT_CLAWS_BIN
+);
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const REMOVE  = process.argv.includes('--remove');
+// M-18: atomic remove+add in one read-modify-write cycle — eliminates the
+// kill-window where settings.json has zero Claws hooks between --remove and re-add.
+const UPDATE  = process.argv.includes('--update');
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const SOURCE_TAG    = 'claws';
+
+// W7-2b: conservative orphan-hook detection. Only entries that match the Claws
+// hook script filename pattern OR reference a Windows temp-dir install path are
+// considered orphans. Entries with _source === 'claws' are intentionally excluded
+// here — they are handled by the existing stale-dedup logic below.
+const CLAWS_HOOK_SCRIPT_RE = /(?:session-start|pre-tool-use|pre-bash-no-verify-block|post-tool-use|stop)-claws\.js/;
+
+function isOrphanHookEntry(entry) {
+  if (entry._source) return false; // any _source means it belongs to a known tool
+  const cmd = (entry.hooks && entry.hooks[0] && entry.hooks[0].command) || '';
+  return cmd.includes('claws-install-') || CLAWS_HOOK_SCRIPT_RE.test(cmd);
+}
+
+function removeOrphanHooks(cfg) {
+  if (!cfg.hooks) return 0;
+  let count = 0;
+  for (const [event, arr] of Object.entries(cfg.hooks)) {
+    if (!Array.isArray(arr)) continue;
+    cfg.hooks[event] = arr.filter(entry => {
+      if (!isOrphanHookEntry(entry)) return true;
+      const cmd = entry.hooks[0].command;
+      const truncated = cmd.length > 80 ? cmd.slice(0, 77) + '...' : cmd;
+      console.log(`  removed orphan ${event}: ${truncated}`);
+      count++;
+      return false;
+    });
+  }
+  return count;
+}
+
+// F5: advisory exclusive lock — prevents concurrent inject-settings-hooks
+// invocations (e.g. install.sh + update.sh race) from producing a torn write.
+// 15 attempts × 100ms backoff = 1.5s max wait; handles bursts of concurrent writers.
+const LOCK_PATH = `${SETTINGS_PATH}.lock`;
+async function withLock(fn) {
+  let fd;
+  for (let attempt = 0; attempt < 15; attempt++) {
+    try {
+      fd = fs.openSync(LOCK_PATH, 'wx');
+      break;
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        // Parent directory doesn't exist yet — create it (fresh install).
+        fs.mkdirSync(path.dirname(LOCK_PATH), { recursive: true });
+        try { fd = fs.openSync(LOCK_PATH, 'wx'); break; } catch (e2) {
+          if (e2.code !== 'EEXIST') throw e2; // unexpected error
+          // else: another process grabbed it after mkdir — fall through to sleep
+        }
+      } else if (e.code !== 'EEXIST') {
+        throw e; // unexpected error (not a lock contention)
+      }
+      await new Promise(r => setTimeout(r, 100));
+    }
+  }
+  if (fd === undefined) {
+    throw new Error(`settings.json lock busy after ${15 * 100}ms — another process may be stuck`);
+  }
+  try {
+    return await fn();
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore */ }
+    try { fs.unlinkSync(LOCK_PATH); } catch { /* ignore */ }
+  }
+}
+
+const HELPERS_URL = pathToFileURL(path.resolve(__dirname, '_helpers', 'json-safe.mjs')).href;
+
+// M-15 + F1: canonical install = CLAWS_BIN/hooks/ directory exists AND the
+// specific script file is present. Both checks are required: if only the dir
+// is present but the script is missing (empty hooks/ dir, custom CLAWS_BIN,
+// or post-install deletion), a bare `node` invocation exits non-zero with
+// MODULE_NOT_FOUND — breaking the SAFETY CONTRACT (hooks must never exit
+// non-zero except intentional deny). Fall through to wrapped form instead.
+function isCanonicalInstall(scriptName) {
+  try {
+    const hooksDir = path.join(CLAWS_BIN, 'hooks');
+    return fs.statSync(hooksDir).isDirectory() &&
+           fs.existsSync(path.join(hooksDir, scriptName));
+  } catch {
+    return false;
+  }
+}
+
+function hookCmd(scriptName) {
+  const scriptPath = path.join(CLAWS_BIN, 'hooks', scriptName);
+  if (isCanonicalInstall(scriptName)) {
+    // Direct node invocation: hooks/ dir and script both confirmed present.
+    // Skips the sh -c wrapper to reduce fork overhead per hook invocation.
+    return `node ${JSON.stringify(scriptPath)}`;
+  }
+  // W7h-30A: Windows has no sh in PATH — emit direct node invocation.
+  // The fault-tolerance wrapper (misfire log) is Unix-only; on Windows, simpler
+  // direct node is correct and avoids "sh not found" errors breaking hooks silently.
+  if (process.platform === 'win32') {
+    return `node ${JSON.stringify(scriptPath)}`;
+  }
+  // Non-canonical or partially-installed: wrap with file-exists guard + misfire logging.
+  // Missing path: writes forensic entry to /tmp/claws-hook-misfire.log (2>/dev/null
+  // suppresses errors when /tmp is unwritable) AND echoes to stderr so the event is
+  // always visible even on read-only filesystems. exit 0 preserves the SAFETY CONTRACT.
+  // Path is passed as $0 to avoid shell-escape pitfalls.
+  return (
+    `sh -c 'if [ -f "$0" ]; then exec node "$0"; ` +
+    `else msg="[claws-hook-misfire] $(date -u +%Y-%m-%dT%H:%M:%SZ) missing path: $0"; ` +
+    `printf "%s\\n" "$msg" >> /tmp/claws-hook-misfire.log 2>/dev/null; ` +
+    `printf "%s\\n" "$msg" >&2; ` +
+    `exit 0; fi' ${JSON.stringify(scriptPath)}`
+  );
+}
+
+function makeHookEntry(matcher, scriptName) {
+  return {
+    matcher,
+    _source: SOURCE_TAG,
+    hooks: [{ type: 'command', command: hookCmd(scriptName) }],
+  };
+}
+
+(async () => {
+  const { mergeIntoFile, parseJsonSafe } = await import(HELPERS_URL);
+
+  const HOOKS_TO_ADD = [
+    // SessionStart: emits lifecycle reminder + spawns stream-events.js sidecar (idempotent)
+    { event: 'SessionStart', scriptName: 'session-start-claws.js', entry: makeHookEntry('*', 'session-start-claws.js') },
+    // PreToolUse '*': Bash long-running guard + Edit/Write mcp_server.js guard
+    { event: 'PreToolUse',   scriptName: 'pre-tool-use-claws.js',  entry: makeHookEntry('*', 'pre-tool-use-claws.js') },
+    // F32 (v0.7.13-hook-p1): block git commit --no-verify and similar bypass flags.
+    // advisory-mechanism-audit Finding F32: highest-ROI hook fix. Workers that try
+    // to skip pre-commit hooks (tests, lint, type checks) get a hard rejection.
+    { event: 'PreToolUse', scriptName: 'pre-bash-no-verify-block.js', entry: makeHookEntry('Bash', 'pre-bash-no-verify-block.js') },
+    // W7h-30C / BUG-28: explicit MCP spawn-class PreToolUse matchers — belt-and-suspenders
+    // for Claude Code builds where '*' is not propagated to MCP tool calls. The server-side
+    // gate in mcp_server.js (T4) remains the primary enforcer; these hooks fire even when
+    // the '*' matcher misses, ensuring Monitor-arm enforcement on Windows and older builds.
+    { event: 'PreToolUse', scriptName: 'pre-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_create',             'pre-tool-use-claws.js') },
+    { event: 'PreToolUse', scriptName: 'pre-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_worker',             'pre-tool-use-claws.js') },
+    { event: 'PreToolUse', scriptName: 'pre-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_fleet',              'pre-tool-use-claws.js') },
+    { event: 'PreToolUse', scriptName: 'pre-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_dispatch_subworker', 'pre-tool-use-claws.js') },
+    // Wave C: PostToolUse spawn-class matchers — fail-close the spawn → monitor race window.
+    // Explicit per-tool matchers (belt-and-suspenders, same rationale as PreToolUse above).
+    // After each successful spawn, waits up to ~5s for lifecycle.monitors to register the
+    // terminal. If missing, publishes wave.violation and auto-closes the orphaned terminal.
+    { event: 'PostToolUse', scriptName: 'post-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_create',             'post-tool-use-claws.js') },
+    { event: 'PostToolUse', scriptName: 'post-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_worker',             'post-tool-use-claws.js') },
+    { event: 'PostToolUse', scriptName: 'post-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_fleet',              'post-tool-use-claws.js') },
+    { event: 'PostToolUse', scriptName: 'post-tool-use-claws.js', entry: makeHookEntry('mcp__claws__claws_dispatch_subworker', 'post-tool-use-claws.js') },
+    // Stop: kills stream-events.js sidecar + reminds model to close terminals / complete REFLECT
+    { event: 'Stop',        scriptName: 'stop-claws.js',          entry: makeHookEntry('*', 'stop-claws.js') },
+  ];
+
+  if (DRY_RUN) {
+    let raw = '{}';
+    try { raw = fs.readFileSync(SETTINGS_PATH, 'utf8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    const parsed = parseJsonSafe(raw, { allowJsonc: true });
+    if (!parsed.ok) {
+      console.error('[claws] settings.json is malformed — dry-run aborted (file unchanged).');
+      console.error('  Error:', parsed.error.message);
+      process.exit(1);
+    }
+    const cfg = parsed.data;
+    if (!cfg.hooks) cfg.hooks = {};
+    removeOrphanHooks(cfg);
+    for (const { event, scriptName, entry } of HOOKS_TO_ADD) {
+      if (!cfg.hooks[event]) cfg.hooks[event] = [];
+      const arr = cfg.hooks[event];
+      // Dry-run: use same exact-match dedup as live path (M-14)
+      const exactDryIdx = arr.findIndex(e =>
+        e._source === SOURCE_TAG && e.matcher === entry.matcher &&
+        e.hooks && e.hooks[0] && e.hooks[0].command === entry.hooks[0].command
+      );
+      if (exactDryIdx === -1) {
+        const staleDryIdx = arr.findIndex(e =>
+          e._source === SOURCE_TAG && e.matcher === entry.matcher && e.hooks && e.hooks[0]
+        );
+        if (staleDryIdx !== -1) arr[staleDryIdx] = entry;
+        else arr.push(entry);
+      }
+    }
+    console.log('[dry-run] would write to:', SETTINGS_PATH);
+    console.log(JSON.stringify(cfg, null, 2));
+    return;
+  }
+
+  if (REMOVE) {
+    let removed = 0;
+    const result = await withLock(() => mergeIntoFile(SETTINGS_PATH, (cfg) => {
+      if (!cfg.hooks) return;
+      removed += removeOrphanHooks(cfg);
+      for (const [event, arr] of Object.entries(cfg.hooks)) {
+        if (!Array.isArray(arr)) continue;
+        const filtered = arr.filter(e => e._source !== SOURCE_TAG);
+        removed += arr.length - filtered.length;
+        cfg.hooks[event] = filtered;
+      }
+    }));
+    if (!result.ok) {
+      console.error('[claws] Failed to update settings.json:', result.error.message);
+      if (result.error.backupSavedAt) {
+        console.error('  Original backed up to:', result.error.backupSavedAt);
+        console.error('  Aborting — your settings.json is unchanged.');
+      }
+      process.exit(1);
+    }
+    console.log(`Removed ${removed} Claws hook(s) from ${SETTINGS_PATH}`);
+    return;
+  }
+
+  // M-18: --update does remove-then-add atomically in one mergeIntoFile call.
+  // No kill-window where settings.json has zero Claws hooks.
+  if (UPDATE) {
+    let removed = 0;
+    let changed = 0;
+    const result = await withLock(() => mergeIntoFile(SETTINGS_PATH, (cfg) => {
+      // FINDING-B-1: migrate legacy flat-array hooks format → object-keyed format.
+      // Early Claude Code versions stored hooks as [{event:"SessionStart",...}, ...].
+      // JSON.stringify of a named-property-on-array drops the new hooks silently.
+      if (Array.isArray(cfg.hooks)) {
+        const legacyArr = cfg.hooks;
+        cfg.hooks = {};
+        for (const entry of legacyArr) {
+          if (!entry.event) continue;
+          if (entry._source === SOURCE_TAG) { removed++; continue; } // drop old claws hooks
+          if (!cfg.hooks[entry.event]) cfg.hooks[entry.event] = [];
+          const { event: _ev, ...rest } = entry;
+          cfg.hooks[entry.event].push(rest);
+        }
+      }
+      if (!cfg.hooks) cfg.hooks = {};
+      // W7-2b: clean orphan hooks before the remove+add cycle
+      removed += removeOrphanHooks(cfg);
+      // Step 1: remove all existing Claws hooks
+      for (const [event, arr] of Object.entries(cfg.hooks)) {
+        if (!Array.isArray(arr)) continue;
+        const filtered = arr.filter(e => e._source !== SOURCE_TAG);
+        removed += arr.length - filtered.length;
+        cfg.hooks[event] = filtered;
+      }
+      // Step 2: add current Claws hooks
+      for (const { event, entry } of HOOKS_TO_ADD) {
+        if (!cfg.hooks[event]) cfg.hooks[event] = [];
+        cfg.hooks[event].push(entry);
+        changed++;
+      }
+    }));
+    if (!result.ok) {
+      console.error('[claws] Failed to update settings.json:', result.error.message);
+      if (result.error.backupSavedAt) {
+        console.error('  Original backed up to:', result.error.backupSavedAt);
+        console.error('  Aborting — your settings.json is unchanged.');
+      }
+      process.exit(1);
+    }
+    console.log(`Updated Claws hooks in ${SETTINGS_PATH} (removed ${removed}, added ${changed})`);
+    return;
+  }
+
+  // Add/update hooks
+  let changed = 0;
+  const result = await withLock(() => mergeIntoFile(SETTINGS_PATH, (cfg) => {
+    // FINDING-B-1: migrate legacy flat-array format before add/dedup logic.
+    if (Array.isArray(cfg.hooks)) {
+      const legacyArr = cfg.hooks;
+      cfg.hooks = {};
+      for (const entry of legacyArr) {
+        if (!entry.event) continue;
+        if (!cfg.hooks[entry.event]) cfg.hooks[entry.event] = [];
+        const { event: _ev, ...rest } = entry;
+        cfg.hooks[entry.event].push(rest);
+      }
+    }
+    if (!cfg.hooks) cfg.hooks = {};
+    // W7-2b: remove orphan entries from pre-fix installs before dedup logic
+    removeOrphanHooks(cfg);
+    for (const { event, scriptName, entry } of HOOKS_TO_ADD) {
+      if (!cfg.hooks[event]) cfg.hooks[event] = [];
+      const arr = cfg.hooks[event];
+
+      // M-14: exact-command equality for dedup. The _source === 'claws' guard
+      // was already present before M-14 and prevented non-Claws hooks from
+      // matching (findIndex short-circuits on _source). M-14's actual improvement:
+      // replace substring command.includes(scriptName) with strict equality,
+      // making "already current" (no-op) vs "stale/old-format Claws entry"
+      // (upgrade in-place via staleIdx) unambiguous and cleaner.
+      const exactIdx = arr.findIndex(e =>
+        e._source === SOURCE_TAG &&
+        e.matcher === entry.matcher &&
+        e.hooks && e.hooks[0] &&
+        e.hooks[0].command === entry.hooks[0].command
+      );
+
+      if (exactIdx !== -1) {
+        // Already current — no-op
+      } else {
+        // Check for a stale Claws entry to upgrade (different command, same source+matcher)
+        const staleIdx = arr.findIndex(e =>
+          e._source === SOURCE_TAG &&
+          e.matcher === entry.matcher &&
+          e.hooks && e.hooks[0]
+        );
+        if (staleIdx !== -1) {
+          arr[staleIdx] = entry;
+          changed++;
+        } else {
+          arr.push(entry);
+          changed++;
+        }
+      }
+    }
+  }));
+
+  if (!result.ok) {
+    console.error('[claws] Failed to update settings.json:', result.error.message);
+    if (result.error.backupSavedAt) {
+      console.error('  Original backed up to:', result.error.backupSavedAt);
+      console.error('  Aborting — your settings.json is unchanged.');
+    }
+    process.exit(1);
+  }
+
+  if (changed > 0) {
+    console.log(`Added ${changed} Claws hook(s) to ${SETTINGS_PATH}`);
+  } else {
+    console.log('Claws hooks already present in settings.json');
+  }
+})().catch(e => {
+  console.error('[claws] inject-settings-hooks unexpected error:', e.message);
+  process.exit(1);
+});