@stackmemoryai/stackmemory 1.0.1 → 1.2.1

package/dist/src/orchestrators/multimodal/harness.js

@@ -2,11 +2,20 @@ import { fileURLToPath as __fileURLToPath } from 'url';
 import { dirname as __pathDirname } from 'path';
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
-import { callClaude, callCodexCLI, implementWithClaude } from "./providers.js";
+import {
+  callClaude,
+  callCodexCLI,
+  captureGitDiff,
+  implementWithClaude,
+  parseEditMetrics,
+  runPostImplChecks
+} from "./providers.js";
 import * as fs from "fs";
 import * as path from "path";
 import { FrameManager } from "../../core/context/index.js";
 import { deriveProjectId } from "./utils.js";
+import { HARNESS_TARGETS, summarizeRuns } from "./baselines.js";
+import { feedbackLoops } from "../../core/monitoring/feedback-loops.js";
 function heuristicPlan(input) {
   return {
     summary: `Plan for: ${input.task}`,
@@ -50,6 +59,7 @@ Repo: ${input.repoPath}
 Notes: ${input.contextNotes || "(none)"}
 ${contextSummary}
 Constraints: Keep the plan minimal and implementable in a single PR.`;
+  const t0 = Date.now();
   let plan;
   try {
     const raw = await callClaude(plannerPrompt, {
@@ -65,6 +75,7 @@ Constraints: Keep the plan minimal and implementable in a single PR.`;
   } catch {
     plan = heuristicPlan(input);
   }
+  const planLatencyMs = Date.now() - t0;
   const implementer = options.implementer || "codex";
   const maxIters = Math.max(1, options.maxIters ?? 2);
   const iterations = [];
@@ -104,11 +115,25 @@ Incorporate reviewer suggestions: ${lastCritique.suggestions.join("; ")}`;
       lastCommand = `claude:${options.plannerModel || "sonnet"} prompt`;
       lastOutput = impl.output;
     }
-    const criticSystem = `You are a strict code reviewer. Return a JSON object: { approved: boolean, issues: string[], suggestions: string[] }`;
+    const diff = options.dryRun !== false ? "(dry run \u2014 no diff)" : captureGitDiff(input.repoPath);
+    const checks = options.dryRun !== false ? null : runPostImplChecks(input.repoPath);
+    const checksSection = checks ? `
+
+Post-implementation checks:
+  Lint: ${checks.lintOk ? "PASS" : "FAIL"}
+${checks.lintOutput}
+  Tests: ${checks.testsOk ? "PASS" : "FAIL"}
+${checks.testOutput}` : "";
+    const criticSystem = `You are a strict code reviewer. Review the git diff against the plan. Check for: correctness, missing steps, unrelated changes, bugs, security issues. Also review lint and test results if provided. Return raw JSON only (no markdown fences): { "approved": boolean, "issues": ["string"], "suggestions": ["string"] }`;
     const criticPrompt = `Plan: ${plan.summary}
+Acceptance criteria:
+${plan.steps.map((s) => s.acceptanceCriteria?.join(", ") || s.title).join("\n")}
+
 Attempt ${i + 1}/${maxIters}
-Command: ${lastCommand}
-Output: ${lastOutput.slice(0, 2e3)}`;
+Implementer exit: ${ok ? "success" : "failed"}
+
+Git diff:
+${diff}${checksSection}`;
     try {
       const raw = await callClaude(criticPrompt, {
         model: options.reviewerModel,
@@ -126,7 +151,7 @@ Output: ${lastOutput.slice(0, 2e3)}`;
     iterations.push({
       command: lastCommand,
       ok,
-      outputPreview: lastOutput.slice(0, 400),
+      outputPreview: diff.slice(0, 2e3),
       critique: lastCritique
     });
     if (lastCritique.approved) {
@@ -134,6 +159,24 @@ Output: ${lastOutput.slice(0, 2e3)}`;
       break;
     }
   }
+  const totalLatencyMs = Date.now() - t0;
+  const finalDiff = options.dryRun !== false ? "(dry run \u2014 no diff)" : captureGitDiff(input.repoPath);
+  const editMetrics = parseEditMetrics(finalDiff);
+  const runMetrics = {
+    timestamp: Date.now(),
+    task: input.task,
+    plannerModel: options.plannerModel || "default",
+    reviewerModel: options.reviewerModel || "default",
+    implementer,
+    planLatencyMs,
+    totalLatencyMs,
+    iterations: iterations.length,
+    approved,
+    editAttempts: editMetrics.editAttempts,
+    editSuccesses: editMetrics.editSuccesses,
+    editFuzzyFallbacks: editMetrics.editFuzzyFallbacks,
+    contextTokens: Math.ceil(finalDiff.length / 4)
+  };
   try {
     const dir = options.auditDir || path.join(input.repoPath, ".stackmemory", "build");
     fs.mkdirSync(dir, { recursive: true });
@@ -146,12 +189,49 @@ Output: ${lastOutput.slice(0, 2e3)}`;
           input,
           options: { ...options, auditDir: void 0 },
           plan,
-          iterations
+          iterations,
+          metrics: runMetrics
         },
         null,
         2
       )
     );
+    const metricsFile = path.join(dir, "harness-metrics.jsonl");
+    fs.appendFileSync(metricsFile, JSON.stringify(runMetrics) + "\n");
+    try {
+      const lines = fs.readFileSync(metricsFile, "utf-8").split("\n").filter((l) => l.trim());
+      const recent = lines.slice(-10).map((l) => JSON.parse(l));
+      if (recent.length >= 3) {
+        const summary = summarizeRuns(recent);
+        if (summary.approvalRate < HARNESS_TARGETS.firstPassApprovalRate) {
+          feedbackLoops.fire(
+            "harnessRegression",
+            "metrics_append",
+            {
+              metric: "approvalRate",
+              current: summary.approvalRate,
+              target: HARNESS_TARGETS.firstPassApprovalRate,
+              window: recent.length
+            },
+            "regression_alert"
+          );
+        }
+        if (summary.p95TotalLatencyMs > HARNESS_TARGETS.totalLatencyP95Ms) {
+          feedbackLoops.fire(
+            "harnessRegression",
+            "metrics_append",
+            {
+              metric: "totalLatencyP95",
+              current: summary.p95TotalLatencyMs,
+              target: HARNESS_TARGETS.totalLatencyP95Ms,
+              window: recent.length
+            },
+            "regression_alert"
+          );
+        }
+      }
+    } catch {
+    }
   } catch {
   }
   if (options.record) {

package/dist/src/orchestrators/multimodal/providers.js

@@ -3,6 +3,7 @@ import { dirname as __pathDirname } from 'path';
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import { spawnSync } from "child_process";
+import { STRUCTURED_RESPONSE_SUFFIX } from "./constants.js";
 async function callClaude(prompt, options) {
   const apiKey = process.env["ANTHROPIC_API_KEY"];
   if (!apiKey) {
@@ -15,7 +16,7 @@ async function callClaude(prompt, options) {
   const { Anthropic } = await import("@anthropic-ai/sdk");
   const client = new Anthropic({ apiKey });
   const model = options.model || "claude-sonnet-4-20250514";
-  const system = options.system || "You are a precise software planning assistant.";
+  const system = (options.system || "You are a precise software planning assistant.") + STRUCTURED_RESPONSE_SUFFIX;
   try {
     const msg = await client.messages.create({
       model,
@@ -79,6 +80,113 @@ function callCodexCLI(prompt, args = [], dryRun = true, cwd) {
     return { ok: false, output: e?.message || String(e), command: printable };
   }
 }
+function captureGitDiff(cwd, maxLen = 12e3) {
+  try {
+    const unstaged = spawnSync("git", ["diff"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 1e4
+    });
+    const staged = spawnSync("git", ["diff", "--cached"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 1e4
+    });
+    const untracked = spawnSync(
+      "git",
+      ["ls-files", "--others", "--exclude-standard"],
+      { cwd, encoding: "utf8", timeout: 1e4 }
+    );
+    let diff = "";
+    if (staged.stdout?.trim()) diff += staged.stdout;
+    if (unstaged.stdout?.trim()) diff += (diff ? "\n" : "") + unstaged.stdout;
+    if (untracked.stdout?.trim()) {
+      const newFiles = untracked.stdout.trim().split("\n").slice(0, 10);
+      diff += (diff ? "\n" : "") + `New untracked files:
+${newFiles.join("\n")}`;
+    }
+    if (!diff.trim()) return "(no changes detected)";
+    if (diff.length > maxLen) {
+      return diff.slice(0, maxLen) + `
+... (truncated, ${diff.length} total chars)`;
+    }
+    return diff;
+  } catch {
+    return "(git diff failed)";
+  }
+}
+function runPostImplChecks(cwd) {
+  const maxOutput = 2e3;
+  function truncate(s) {
+    if (s.length <= maxOutput) return s;
+    return s.slice(0, maxOutput) + `
+... (truncated, ${s.length} total chars)`;
+  }
+  let lintOk = false;
+  let lintOutput = "";
+  try {
+    const lint = spawnSync("npm", ["run", "lint"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 3e4
+    });
+    lintOk = lint.status === 0;
+    lintOutput = truncate((lint.stdout || "") + (lint.stderr || ""));
+  } catch (e) {
+    lintOutput = truncate(e instanceof Error ? e.message : String(e));
+  }
+  let testsOk = false;
+  let testOutput = "";
+  try {
+    const tests = spawnSync(
+      "npx",
+      ["vitest", "run", "--reporter=dot", "--bail=1"],
+      {
+        cwd,
+        encoding: "utf8",
+        timeout: 12e4
+      }
+    );
+    testsOk = tests.status === 0;
+    testOutput = truncate((tests.stdout || "") + (tests.stderr || ""));
+  } catch (e) {
+    testOutput = truncate(e instanceof Error ? e.message : String(e));
+  }
+  return { lintOk, lintOutput, testsOk, testOutput };
+}
+function parseEditMetrics(diff) {
+  if (!diff || diff.startsWith("(")) {
+    return { editAttempts: 0, editSuccesses: 0, editFuzzyFallbacks: 0 };
+  }
+  const lines = diff.split("\n");
+  let currentFileHunks = 0;
+  let currentFileHasConflict = false;
+  let totalAttempts = 0;
+  let totalSuccesses = 0;
+  const flushFile = () => {
+    totalAttempts += currentFileHunks;
+    if (!currentFileHasConflict) {
+      totalSuccesses += currentFileHunks;
+    }
+    currentFileHunks = 0;
+    currentFileHasConflict = false;
+  };
+  for (const line of lines) {
+    if (/^diff --git /.test(line)) {
+      flushFile();
+    } else if (/^@@ /.test(line)) {
+      currentFileHunks++;
+    } else if (/^[<>=]{7}/.test(line)) {
+      currentFileHasConflict = true;
+    }
+  }
+  flushFile();
+  return {
+    editAttempts: totalAttempts,
+    editSuccesses: totalSuccesses,
+    editFuzzyFallbacks: 0
+  };
+}
 async function implementWithClaude(prompt, options) {
   try {
     const out = await callClaude(prompt, {
@@ -93,5 +201,8 @@ async function implementWithClaude(prompt, options) {
 export {
   callClaude,
   callCodexCLI,
-  implementWithClaude
+  captureGitDiff,
+  implementWithClaude,
+  parseEditMetrics,
+  runPostImplChecks
 };

package/dist/src/skills/recursive-agent-orchestrator.js

@@ -8,6 +8,7 @@ import { logger } from "../core/monitoring/logger.js";
 import { ParallelExecutor } from "../core/execution/parallel-executor.js";
 import { RecursiveContextManager } from "../core/context/recursive-context-manager.js";
 import { ClaudeCodeSubagentClient } from "../integrations/claude-code/subagent-client.js";
+import { STRUCTURED_RESPONSE_SUFFIX } from "../orchestrators/multimodal/constants.js";
 class RecursiveAgentOrchestrator {
   frameManager;
   contextRetriever;
@@ -72,7 +73,7 @@ Rules:
 - Maximize parallelism \u2014 independent tasks run concurrently
 - Each subtask names its agent type: planning, code, testing, linting, review, improve, context, publish
 - Include failure modes and rollback steps for risky operations
-- Keep subtask descriptions actionable (verb + object + constraint)`,
+- Keep subtask descriptions actionable (verb + object + constraint)` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: ["decompose", "analyze", "strategize", "prioritize"]
     });
     configs.set("code", {
@@ -87,7 +88,7 @@ Rules:
 - Add .js extensions to relative TypeScript imports (ESM)
 - Return undefined over throwing; log+continue over crash
 - No emojis, no unnecessary comments, functions under 20 lines
-- Validate inputs at system boundaries only`,
+- Validate inputs at system boundaries only` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: ["implement", "refactor", "optimize", "document"]
     });
     configs.set("testing", {
@@ -102,7 +103,7 @@ Rules:
 - Prioritize: critical paths > edge cases > happy paths
 - Each test should assert meaningful behavior, not implementation details
 - Use parameterized tests (it.each) to consolidate similar cases
-- Run tests after writing: npm run test:run`,
+- Run tests after writing: npm run test:run` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: [
         "generate-tests",
         "validate",
@@ -121,7 +122,7 @@ Rules:
 - Run: npm run lint (ESLint + Prettier)
 - Auto-fix: npm run lint:fix
 - ESM imports require .js extension on relative paths
-- Report unfixable issues with file:line format`,
+- Report unfixable issues with file:line format` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: ["lint", "format", "type-check", "security-scan"]
     });
     configs.set("review", {
@@ -136,7 +137,7 @@ Rules:
 - Flag: SQL injection, XSS, secret exposure, command injection
 - Flag: functions > 20 lines, cyclomatic complexity > 5
 - Flag: missing error handling at system boundaries
-- Suggest specific fixes, not vague improvements`,
+- Suggest specific fixes, not vague improvements` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: [
         "review",
         "critique",
@@ -155,7 +156,7 @@ Rules:
 - Apply only the specific improvements requested \u2014 no scope creep
 - Maintain backward compatibility unless explicitly breaking
 - Run lint + tests after changes to verify nothing regressed
-- Keep changes minimal and focused`,
+- Keep changes minimal and focused` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: ["enhance", "refactor", "optimize", "polish"]
     });
     configs.set("context", {
@@ -169,7 +170,7 @@ Rules:
 - Check docs/specs/ for ONE_PAGER.md, DEV_SPEC.md, PROMPT_PLAN.md
 - Check CLAUDE.md and AGENTS.md for project conventions
 - Search src/ for relevant implementations
-- Return concise summaries, not full file contents`,
+- Return concise summaries, not full file contents` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: ["search", "retrieve", "summarize", "contextualize"]
     });
     configs.set("publish", {
@@ -183,7 +184,7 @@ Rules:
 - Verify lint + tests + build pass before any publish
 - Follow semver: breaking=major, feature=minor, fix=patch
 - Generate changelog from git log since last tag
-- Never force-push or skip pre-publish hooks`,
+- Never force-push or skip pre-publish hooks` + STRUCTURED_RESPONSE_SUFFIX,
       capabilities: ["publish-npm", "github-release", "deploy", "document"]
     });
     return configs;
@@ -557,9 +558,13 @@ ${sections.join("\n\n")}` : "";
     const pricing = {
       "claude-sonnet-4-5-20250929": 15,
       "claude-haiku-4-5-20251001": 1,
-      "claude-opus-4-6": 75
+      "claude-opus-4-6": 75,
+      // External providers — much cheaper
+      "llama-4-scout-17b-16e-instruct": 0.35,
+      "THUDM/glm-4-9b-chat": 0.06
     };
-    return tokens / 1e6 * (pricing[model] || 10);
+    const modelName = typeof model === "string" ? model : model.model;
+    return tokens / 1e6 * (pricing[modelName] || 10);
   }
   countGeneratedTests(node) {
     let count = 0;

package/dist/src/utils/fuzzy-edit.js

@@ -0,0 +1,162 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    () => new Array(n + 1).fill(0)
+  );
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[m][n];
+}
+function normalizeWhitespace(text) {
+  return text.split("\n").map((line) => line.trim().replace(/\s+/g, " ")).join("\n");
+}
+function stripIndentation(text) {
+  return text.split("\n").map((line) => line.trimStart()).join("\n");
+}
+function fuzzyMatch(content, oldString, threshold = 0.85) {
+  if (!oldString) return null;
+  const exactIdx = content.indexOf(oldString);
+  if (exactIdx !== -1) {
+    return {
+      found: true,
+      startIndex: exactIdx,
+      endIndex: exactIdx + oldString.length,
+      confidence: 1,
+      matchedText: oldString,
+      method: "exact"
+    };
+  }
+  const normContent = normalizeWhitespace(content);
+  const normOld = normalizeWhitespace(oldString);
+  const normIdx = normContent.indexOf(normOld);
+  if (normIdx !== -1) {
+    const match = mapNormalizedToOriginal(
+      content,
+      normContent,
+      normOld,
+      normIdx
+    );
+    if (match) {
+      return {
+        found: true,
+        startIndex: match.start,
+        endIndex: match.end,
+        confidence: 0.95,
+        matchedText: content.slice(match.start, match.end),
+        method: "whitespace-normalized"
+      };
+    }
+  }
+  const stripContent = stripIndentation(content);
+  const stripOld = stripIndentation(oldString);
+  const stripIdx = stripContent.indexOf(stripOld);
+  if (stripIdx !== -1) {
+    const match = mapStrippedToOriginal(
+      content,
+      stripContent,
+      stripOld,
+      stripIdx
+    );
+    if (match) {
+      return {
+        found: true,
+        startIndex: match.start,
+        endIndex: match.end,
+        confidence: 0.9,
+        matchedText: content.slice(match.start, match.end),
+        method: "indentation-insensitive"
+      };
+    }
+  }
+  const contentLines = content.split("\n");
+  const oldLines = oldString.split("\n");
+  const windowSize = oldLines.length;
+  if (windowSize === 0 || contentLines.length < windowSize) return null;
+  let bestScore = 0;
+  let bestStart = -1;
+  let bestEnd = -1;
+  for (let i = 0; i <= contentLines.length - windowSize; i++) {
+    const windowText = contentLines.slice(i, i + windowSize).join("\n");
+    const maxLen = Math.max(windowText.length, oldString.length);
+    if (maxLen === 0) continue;
+    const dist = levenshtein(windowText, oldString);
+    const similarity = 1 - dist / maxLen;
+    if (similarity > bestScore) {
+      bestScore = similarity;
+      bestStart = i;
+      bestEnd = i + windowSize;
+    }
+  }
+  if (bestScore >= threshold && bestStart >= 0) {
+    let startCharIdx = 0;
+    for (let i = 0; i < bestStart; i++) {
+      startCharIdx += contentLines[i].length + 1;
+    }
+    let endCharIdx = startCharIdx;
+    for (let i = bestStart; i < bestEnd; i++) {
+      endCharIdx += contentLines[i].length + (i < bestEnd - 1 ? 1 : 0);
+    }
+    return {
+      found: true,
+      startIndex: startCharIdx,
+      endIndex: endCharIdx,
+      confidence: Math.round(bestScore * 100) / 100,
+      matchedText: contentLines.slice(bestStart, bestEnd).join("\n"),
+      method: "line-fuzzy"
+    };
+  }
+  return null;
+}
+function fuzzyEdit(content, oldString, newString, threshold = 0.85) {
+  const match = fuzzyMatch(content, oldString, threshold);
+  if (!match) return null;
+  const result = content.slice(0, match.startIndex) + newString + content.slice(match.endIndex);
+  return { content: result, match };
+}
+function mapNormalizedToOriginal(original, _normalized, normNeedle, normIdx) {
+  const normLines = _normalized.split("\n");
+  const origLines = original.split("\n");
+  let charCount = 0;
+  let startLine = 0;
+  for (let i = 0; i < normLines.length; i++) {
+    if (charCount + normLines[i].length >= normIdx) {
+      startLine = i;
+      break;
+    }
+    charCount += normLines[i].length + 1;
+  }
+  const needleLineCount = normNeedle.split("\n").length;
+  const endLine = startLine + needleLineCount;
+  let startChar = 0;
+  for (let i = 0; i < startLine; i++) {
+    startChar += origLines[i].length + 1;
+  }
+  let endChar = startChar;
+  for (let i = startLine; i < endLine && i < origLines.length; i++) {
+    endChar += origLines[i].length + (i < endLine - 1 ? 1 : 0);
+  }
+  return { start: startChar, end: endChar };
+}
+function mapStrippedToOriginal(original, stripped, stripNeedle, stripIdx) {
+  return mapNormalizedToOriginal(original, stripped, stripNeedle, stripIdx);
+}
+export {
+  fuzzyEdit,
+  fuzzyMatch
+};

package/dist/src/utils/hook-installer.js

@@ -0,0 +1,155 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const CANONICAL_HOOKS = [
+  {
+    scriptName: "session-rescue.sh",
+    eventType: "Stop",
+    timeout: 12,
+    required: true
+  },
+  {
+    scriptName: "stop-checkpoint.js",
+    eventType: "Stop",
+    timeout: 5,
+    commandPrefix: "node",
+    required: true
+  },
+  {
+    scriptName: "chime-on-stop.sh",
+    eventType: "Stop",
+    timeout: 2,
+    required: true
+  },
+  {
+    scriptName: "auto-checkpoint.js",
+    eventType: "PostToolUse",
+    timeout: 2,
+    commandPrefix: "node",
+    required: true
+  }
+];
+const DEAD_HOOKS = ["sms-response-handler.js"];
+function buildCommand(entry, hooksDir) {
+  const scriptPath = path.join(hooksDir, entry.scriptName);
+  if (entry.commandPrefix) {
+    return `${entry.commandPrefix} ${scriptPath}`;
+  }
+  return scriptPath;
+}
+function hookExists(settings, entry) {
+  const groups = settings.hooks?.[entry.eventType];
+  if (!groups) return false;
+  for (const group of groups) {
+    for (const hook of group.hooks) {
+      if (hook.command.includes(entry.scriptName)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function hasDeadHooks(settings) {
+  if (!settings.hooks) return false;
+  for (const groups of Object.values(settings.hooks)) {
+    for (const group of groups) {
+      for (const hook of group.hooks) {
+        for (const dead of DEAD_HOOKS) {
+          if (hook.command.includes(dead)) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function removeDeadHooks(settings) {
+  if (!settings.hooks) return false;
+  let removed = false;
+  for (const eventType of Object.keys(settings.hooks)) {
+    const groups = settings.hooks[eventType];
+    for (const group of groups) {
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter((hook) => {
+        for (const dead of DEAD_HOOKS) {
+          if (hook.command.includes(dead)) return false;
+        }
+        return true;
+      });
+      if (group.hooks.length < before) removed = true;
+    }
+    settings.hooks[eventType] = groups.filter((g) => g.hooks.length > 0);
+    if (settings.hooks[eventType].length === 0) {
+      delete settings.hooks[eventType];
+    }
+  }
+  return removed;
+}
+function addHook(settings, entry, hooksDir) {
+  if (!settings.hooks) settings.hooks = {};
+  const eventGroups = settings.hooks[entry.eventType] || [];
+  const command = buildCommand(entry, hooksDir);
+  const hookCmd = { type: "command", command };
+  if (entry.timeout) hookCmd.timeout = entry.timeout;
+  const matcherValue = entry.matcher ?? void 0;
+  const targetGroup = eventGroups.find((g) => {
+    if (matcherValue) return g.matcher === matcherValue;
+    return !g.matcher;
+  });
+  if (targetGroup) {
+    targetGroup.hooks.push(hookCmd);
+  } else {
+    const newGroup = { hooks: [hookCmd] };
+    if (matcherValue) newGroup.matcher = matcherValue;
+    eventGroups.push(newGroup);
+  }
+  settings.hooks[entry.eventType] = eventGroups;
+}
+function mergeSettings(existing, hooksDir) {
+  const merged = JSON.parse(JSON.stringify(existing));
+  removeDeadHooks(merged);
+  for (const entry of CANONICAL_HOOKS) {
+    if (!hookExists(merged, entry)) {
+      addHook(merged, entry, hooksDir);
+    }
+  }
+  return merged;
+}
+function getSettingsPath() {
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+function readSettings(settingsPath) {
+  const p = settingsPath ?? getSettingsPath();
+  try {
+    if (fs.existsSync(p)) {
+      return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+  } catch {
+  }
+  return {};
+}
+function writeSettingsAtomic(settings, settingsPath) {
+  const p = settingsPath ?? getSettingsPath();
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmp = p + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+  fs.renameSync(tmp, p);
+}
+export {
+  CANONICAL_HOOKS,
+  DEAD_HOOKS,
+  buildCommand,
+  getSettingsPath,
+  hasDeadHooks,
+  hookExists,
+  mergeSettings,
+  readSettings,
+  removeDeadHooks,
+  writeSettingsAtomic
+};