sweet-search 2.5.2 → 2.5.4

package/scripts/inject-agent-instructions.js

@@ -0,0 +1,431 @@
+/**
+ * Multi-file injection of the sweet-search agent policy across every major
+ * coding-agent harness (CLAUDE.md / AGENTS.md / GEMINI.md / Cursor rule).
+ *
+ * Canonical source: **CLAUDE.md** by default (sweet-search is Claude-first;
+ * the existing project CLAUDE.md is where users look). Other harnesses get
+ * `@CLAUDE.md` import shims (or symlinks). When the user disables Claude
+ * Code with `--no-claude-code`, AGENTS.md is promoted to canonical so other
+ * harnesses still receive the policy body.
+ *
+ * NOTE: this design diverges from the plan's §3.3 / §10 which framed
+ * AGENTS.md as canonical. The flip was a user-driven product call (sweet-
+ * search ships best on Claude, the existing CLAUDE.md is the natural home,
+ * and Codex / Gemini both follow `@imports` so the cross-harness chain works
+ * with either canonical). Plan doc update is tracked as a follow-up.
+ *
+ * Marker contract (idempotent rewrite — never modify content outside it):
+ *   <!-- sweet-search:agent-instructions:begin -->
+ *   ... managed body ...
+ *   <!-- sweet-search:agent-instructions:end -->
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, lstatSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const MARKER_BEGIN = '<!-- sweet-search:agent-instructions:begin -->';
+export const MARKER_END = '<!-- sweet-search:agent-instructions:end -->';
+
+export const AGENTS_FILE = 'AGENTS.md';
+export const CLAUDE_FILE = 'CLAUDE.md';
+export const GEMINI_FILE = 'GEMINI.md';
+export const CURSOR_FILE = '.cursor/rules/sweet-search.mdc';
+
+/**
+ * Public harness identifiers used by the per-harness `--no-<name>` flags
+ * in `scripts/init.js`. Order matches `--help` output.
+ */
+export const ALL_HARNESSES = ['claude-code', 'agents', 'gemini', 'cursor'];
+
+const MARKER_RE = new RegExp(
+  `${escapeRegex(MARKER_BEGIN)}[\\s\\S]*?${escapeRegex(MARKER_END)}\\n?`,
+);
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ─── Canonical policy body = the frozen M++ champion (integration seam) ──────
+//
+// Plan §10 / §3.7.1 step 13 / DDD "Integration seam": scripts/init.js is the
+// SOLE consumer of the prompt-optimization ship-file. We read that artifact at
+// load time and strip its YAML front-matter; the remaining body is the frozen
+// M++ champion (PHASE7), injected VERBATIM into the harness files so users get
+// exactly the prompt that was benchmarked (held-out 0.988 Maximin, OOD 0.952,
+// HOMP/SCS/counter all pass; 5-cell cross-harness validated). Per-harness shims
+// (Cursor frontmatter, @imports) are applied at write-time, not embedded here.
+//
+// The artifact is generated from Mpp.md by
+// `core/prompt-optimization/sweep/finalize-mpp.mjs` and shipped via the
+// package.json "files" list. If it is missing we fail LOUDLY rather than
+// silently shipping a placeholder/older policy.
+
+const SHIP_FILE_REL = 'core/prompt-optimization/data/p7-final/sweet-search-system-prompt.md';
+
+/** Strip a leading YAML front-matter block (`---\n … \n---\n`) if present. */
+export function stripFrontMatter(text) {
+  return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+}
+
+function readShippedPolicy() {
+  const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/scripts
+  const shipPath = join(here, '..', SHIP_FILE_REL);
+  let raw;
+  try {
+    raw = readFileSync(shipPath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `inject-agent-instructions: cannot read the M++ ship-file at ${shipPath}. ` +
+      'It MUST be present (packaged via package.json "files"). Regenerate with ' +
+      '`node core/prompt-optimization/sweep/finalize-mpp.mjs`. ' +
+      `Cause: ${err.message}`,
+    );
+  }
+  const body = stripFrontMatter(raw).trimEnd();
+  if (!body) {
+    throw new Error(`inject-agent-instructions: M++ ship-file at ${shipPath} has an empty body.`);
+  }
+  return body;
+}
+
+export const CANONICAL_POLICY_BODY = readShippedPolicy();
+
+const CURSOR_FRONTMATTER = `---
+description: Sweet Search tool-routing, stopping, and citation policy
+alwaysApply: false
+filePattern: "**/*"
+---
+
+`;
+
+// ─── Block builders ──────────────────────────────────────────────────────────
+
+function wrapMarker(body) {
+  return `${MARKER_BEGIN}\n${body.trimEnd()}\n${MARKER_END}\n`;
+}
+
+/**
+ * Body for the canonical-source file (CLAUDE.md by default; AGENTS.md when
+ * the user opts out of Claude Code with `--no-claude-code`). Inlines the
+ * full policy plus, for CLAUDE.md, an extra `@.claude/rules/sweet-search.md`
+ * import line so the Claude-specific shim is loaded.
+ */
+export function buildCanonicalBlock({ extraImports = [] } = {}) {
+  if (extraImports.length === 0) {
+    return wrapMarker(CANONICAL_POLICY_BODY);
+  }
+  const importLines = extraImports.map(t => `@${t}`).join('\n');
+  return wrapMarker(`${CANONICAL_POLICY_BODY}\n${importLines}\n`);
+}
+
+/**
+ * Body for non-canonical harnesses that prefer to @import the canonical
+ * file (Codex CLI, Gemini CLI when symlinks aren't used, AGENTS.md when
+ * canonical is CLAUDE.md). Cursor doesn't get this — it inlines the body
+ * because its frontmatter is required.
+ */
+export function buildImportBlock({ importTargets }) {
+  const lines = importTargets.map(t => `@${t}`).join('\n');
+  return wrapMarker(
+    `<!-- Auto-generated by \`sweet-search init\`. Edit the canonical file (CLAUDE.md by default, AGENTS.md when --no-claude) instead. -->\n\n${lines}`,
+  );
+}
+
+/** Body for the cursor .mdc (frontmatter + inlined canonical body). */
+export function buildCursorFile() {
+  return CURSOR_FRONTMATTER + wrapMarker(CANONICAL_POLICY_BODY);
+}
+
+// ─── Marker injection ───────────────────────────────────────────────────────
+
+/**
+ * Idempotent rewrite of the marker block.
+ *  - File missing: write `block` (with optional `prefix` like cursor frontmatter).
+ *  - Marker present: replace in-place.
+ *  - File exists, no marker: prepend `block` followed by an empty line.
+ * @returns 'created' | 'replaced' | 'prepended' | 'unchanged'
+ */
+export function injectMarkerBlock({ filePath, block, prefix = '' }) {
+  if (!existsSync(filePath)) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, prefix + block);
+    return 'created';
+  }
+  const current = readFileSync(filePath, 'utf8');
+  if (MARKER_RE.test(current)) {
+    const next = current.replace(MARKER_RE, block);
+    if (next === current) return 'unchanged';
+    writeFileSync(filePath, next);
+    return 'replaced';
+  }
+  // No marker — prepend the block. Keeps user content intact.
+  writeFileSync(filePath, block + '\n' + current);
+  return 'prepended';
+}
+
+/**
+ * Strip just the marker block (keep all surrounding user content).
+ * Used by uninstall.
+ * @returns 'removed' | 'not-found' | 'file-deleted'
+ *   `file-deleted` means the file became empty after stripping the marker
+ *   (i.e. it was wholly sweet-search-managed) and the file itself was unlinked.
+ */
+export function stripMarkerBlock({ filePath, deleteIfEmpty = true }) {
+  if (!existsSync(filePath)) return 'not-found';
+  const stat = lstatSync(filePath);
+  // Symlinks: never edit the link target — caller handles symlink removal
+  // explicitly via removeSymlinkIfOurs.
+  if (stat.isSymbolicLink()) return 'not-found';
+  const current = readFileSync(filePath, 'utf8');
+  if (!MARKER_RE.test(current)) return 'not-found';
+  const next = current.replace(MARKER_RE, '').replace(/^\n+/, '').trimEnd() + '\n';
+  if (deleteIfEmpty && next.trim() === '') {
+    unlinkSync(filePath);
+    return 'file-deleted';
+  }
+  writeFileSync(filePath, next);
+  return 'removed';
+}
+
+// ─── Symlink helpers (GEMINI.md → canonical, etc.) ──────────────────────────
+
+/**
+ * Create a relative symlink `linkPath → targetPath` only if `linkPath`
+ * doesn't already exist (or is already the same symlink). Falls back to
+ * `inline` if the link can't be created (Windows w/o privilege, target on
+ * different volume).
+ *
+ * @returns 'created' | 'already-correct' | 'fell-back-to-copy' | 'preserved-existing'
+ */
+export function symlinkOrFallback({ linkPath, targetPath, fallbackInject }) {
+  const relTarget = relative(dirname(linkPath), targetPath);
+  if (existsSync(linkPath) || lstatExists(linkPath)) {
+    let stat;
+    try { stat = lstatSync(linkPath); } catch { stat = null; }
+    if (stat && stat.isSymbolicLink()) {
+      const current = readlinkSync(linkPath);
+      if (current === relTarget) return 'already-correct';
+      // Different symlink target — leave it alone, user may have customised.
+      return 'preserved-existing';
+    }
+    // Regular file already exists — never overwrite. Inject marker into the
+    // existing file so the policy still flows through.
+    fallbackInject();
+    return 'fell-back-to-copy';
+  }
+  try {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    symlinkSync(relTarget, linkPath);
+    return 'created';
+  } catch {
+    fallbackInject();
+    return 'fell-back-to-copy';
+  }
+}
+
+function lstatExists(p) {
+  try { lstatSync(p); return true; } catch { return false; }
+}
+
+/**
+ * Remove a symlink only if it points at the expected sweet-search target.
+ * @returns 'removed' | 'not-our-symlink' | 'not-found'
+ */
+export function removeSymlinkIfOurs({ linkPath, expectedTargets }) {
+  if (!lstatExists(linkPath)) return 'not-found';
+  let stat;
+  try { stat = lstatSync(linkPath); } catch { return 'not-found'; }
+  if (!stat.isSymbolicLink()) return 'not-our-symlink';
+  let target;
+  try { target = readlinkSync(linkPath); } catch { return 'not-our-symlink'; }
+  const expected = Array.isArray(expectedTargets) ? expectedTargets : [expectedTargets];
+  if (!expected.includes(target)) return 'not-our-symlink';
+  unlinkSync(linkPath);
+  return 'removed';
+}
+
+// ─── Public API: install + uninstall ────────────────────────────────────────
+
+/**
+ * Install the canonical policy file plus per-harness shims/symlinks.
+ * Idempotent. Returns a per-file status report.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string[]} [args.harnesses]   defaults to ALL_HARNESSES
+ * @param {boolean}  [args.useSymlinks] default true; only governs GEMINI.md
+ *
+ * Canonical resolution:
+ *   - claude-code enabled → CLAUDE.md is canonical (body inside marker)
+ *   - claude-code disabled → AGENTS.md is canonical
+ * Other harnesses always import / symlink to whichever file is canonical.
+ */
+export function injectAgentInstructions({
+  projectRoot,
+  harnesses = ALL_HARNESSES,
+  useSymlinks = true,
+} = {}) {
+  if (!projectRoot) throw new TypeError('inject-agent-instructions: projectRoot is required');
+  const enabled = new Set(harnesses);
+  const report = { harnesses: {}, canonical: null };
+
+  if (enabled.size === 0) return report;
+
+  // 1. Canonical file: CLAUDE.md when Claude Code is enabled, else AGENTS.md.
+  //    Body is the full policy plus (Claude-only) the @.claude/rules import.
+  let canonicalFile;
+  let canonicalBlock;
+  if (enabled.has('claude-code')) {
+    canonicalFile = CLAUDE_FILE;
+    canonicalBlock = buildCanonicalBlock({
+      extraImports: ['.claude/rules/sweet-search.md'],
+    });
+    report.canonical = 'claude-code';
+  } else if (enabled.has('agents') || enabled.has('gemini') || enabled.has('cursor')) {
+    canonicalFile = AGENTS_FILE;
+    canonicalBlock = buildCanonicalBlock();
+    report.canonical = 'agents'; // AGENTS.md is the multi-harness convention (Codex, OpenCode, …)
+  } else {
+    return report; // no canonical, nothing to write
+  }
+
+  if (enabled.has('claude-code')) {
+    const claudePath = join(projectRoot, CLAUDE_FILE);
+    report.harnesses['claude-code'] = injectMarkerBlock({
+      filePath: claudePath,
+      block: canonicalBlock,
+    });
+  }
+
+  // 2. AGENTS.md — canonical when Claude Code is disabled, otherwise a
+  //    @CLAUDE.md import shim for Codex / OpenCode.
+  if (enabled.has('agents')) {
+    const agentsPath = join(projectRoot, AGENTS_FILE);
+    if (canonicalFile === AGENTS_FILE) {
+      report.harnesses.agents = injectMarkerBlock({
+        filePath: agentsPath,
+        block: canonicalBlock,
+      });
+    } else {
+      report.harnesses.agents = injectMarkerBlock({
+        filePath: agentsPath,
+        block: buildImportBlock({ importTargets: [canonicalFile] }),
+      });
+    }
+  }
+
+  // 3. GEMINI.md — symlink → canonical when possible, else marker block with @import.
+  if (enabled.has('gemini')) {
+    const geminiPath = join(projectRoot, GEMINI_FILE);
+    if (useSymlinks) {
+      report.harnesses.gemini = symlinkOrFallback({
+        linkPath: geminiPath,
+        targetPath: join(projectRoot, canonicalFile),
+        fallbackInject: () => injectMarkerBlock({
+          filePath: geminiPath,
+          block: buildImportBlock({ importTargets: [canonicalFile] }),
+        }),
+      });
+    } else {
+      report.harnesses.gemini = injectMarkerBlock({
+        filePath: geminiPath,
+        block: buildImportBlock({ importTargets: [canonicalFile] }),
+      });
+    }
+  }
+
+  // 4. .cursor/rules/sweet-search.mdc — frontmatter + inlined body (no symlink).
+  if (enabled.has('cursor')) {
+    const cursorPath = join(projectRoot, CURSOR_FILE);
+    if (existsSync(cursorPath)) {
+      // Existing file — replace marker block in-place; preserve frontmatter
+      // and any user notes outside the markers.
+      report.harnesses.cursor = injectMarkerBlock({
+        filePath: cursorPath,
+        block: buildCanonicalBlock(),
+      });
+    } else {
+      // Fresh file — write frontmatter + canonical body in marker block.
+      mkdirSync(dirname(cursorPath), { recursive: true });
+      writeFileSync(cursorPath, buildCursorFile());
+      report.harnesses.cursor = 'created';
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Reverse `injectAgentInstructions`. Strips marker blocks (preserving user
+ * content) and removes our symlinks. Per §4A: never modify content outside
+ * the marker; never delete a file the user created.
+ */
+export function removeAgentInstructions({ projectRoot, dryRun = false } = {}) {
+  if (!projectRoot) throw new TypeError('remove-agent-instructions: projectRoot is required');
+  const report = { harnesses: {} };
+  const claudePath = join(projectRoot, CLAUDE_FILE);
+  const agentsPath = join(projectRoot, AGENTS_FILE);
+  const geminiPath = join(projectRoot, GEMINI_FILE);
+  const cursorPath = join(projectRoot, CURSOR_FILE);
+
+  if (dryRun) {
+    report.harnesses['claude-code'] = previewMarkerStrip(claudePath);
+    report.harnesses.agents = previewMarkerStrip(agentsPath);
+    report.harnesses.gemini = previewSymlinkRemoval(geminiPath, [CLAUDE_FILE, AGENTS_FILE])
+      || previewMarkerStrip(geminiPath);
+    report.harnesses.cursor = previewWholeFileRemoval(cursorPath);
+    return report;
+  }
+
+  report.harnesses['claude-code'] = stripMarkerBlock({ filePath: claudePath });
+  report.harnesses.agents = stripMarkerBlock({ filePath: agentsPath });
+  // GEMINI.md: try symlink removal first (accept either canonical target),
+  // then fall back to marker strip if it was a copy.
+  const geminiSymlink = removeSymlinkIfOurs({
+    linkPath: geminiPath,
+    expectedTargets: [CLAUDE_FILE, AGENTS_FILE],
+  });
+  report.harnesses.gemini = geminiSymlink !== 'not-our-symlink'
+    ? geminiSymlink
+    : stripMarkerBlock({ filePath: geminiPath });
+  // Cursor file: we always wholly own it (frontmatter is ours), so safe to remove
+  // when our marker is present. Preserve user-customised cursor files.
+  report.harnesses.cursor = removeWholeFileIfOurs(cursorPath);
+
+  return report;
+}
+
+function previewMarkerStrip(filePath) {
+  if (!existsSync(filePath)) return 'not-found';
+  let stat;
+  try { stat = lstatSync(filePath); } catch { return 'not-found'; }
+  if (stat.isSymbolicLink()) return 'not-found';
+  const text = readFileSync(filePath, 'utf8');
+  return MARKER_RE.test(text) ? 'dry-run' : 'not-found';
+}
+
+function previewSymlinkRemoval(linkPath, expectedTargets) {
+  if (!lstatExists(linkPath)) return null;
+  let stat;
+  try { stat = lstatSync(linkPath); } catch { return null; }
+  if (!stat.isSymbolicLink()) return null;
+  let target;
+  try { target = readlinkSync(linkPath); } catch { return null; }
+  const expected = Array.isArray(expectedTargets) ? expectedTargets : [expectedTargets];
+  return expected.includes(target) ? 'dry-run' : null;
+}
+
+function previewWholeFileRemoval(filePath) {
+  if (!existsSync(filePath)) return 'not-found';
+  const text = readFileSync(filePath, 'utf8');
+  return MARKER_RE.test(text) ? 'dry-run' : 'not-found';
+}
+
+function removeWholeFileIfOurs(filePath) {
+  if (!existsSync(filePath)) return 'not-found';
+  const text = readFileSync(filePath, 'utf8');
+  if (!MARKER_RE.test(text)) return 'not-our-symlink'; // user-owned cursor file
+  unlinkSync(filePath);
+  return 'file-deleted';
+}

package/scripts/install-prompt-reminders.js

@@ -0,0 +1,188 @@
+/**
+ * Install / remove the sweet-search UserPromptSubmit reminder hook.
+ *
+ * Plan reference: §4C / §10 step 16. Default-on; `--no-prompt-reminders`
+ * opts out. Universally gated by `--no-claude` (handled in init.js — when
+ * --no-claude, this installer is never called).
+ *
+ * Mirrors the existing prewarm SessionStart pattern in init.js
+ * (registerPrewarmSessionStartHook): sweet-search-owned by filename match,
+ * so re-running init updates the entry rather than appending duplicates.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+
+// Filename doubles as the ownership marker — settings.json entries are
+// matched by `command.includes(PROMPT_REMINDER_HOOK_FILENAME)`.
+export const PROMPT_REMINDER_HOOK_FILENAME = 'sweet-search-remind-tools.mjs';
+const SOURCE_REL = ['scripts', 'hooks', 'remind-tools.mjs'];
+
+/**
+ * Copy the hook script into `.claude/hooks/` and register a
+ * `hooks.UserPromptSubmit` entry in `.claude/settings.json`. Idempotent.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.packageRoot       — sweet-search install root (for source resolution)
+ * @param {boolean} [args.skipped=false]  — set when --no-prompt-reminders
+ * @returns {{ status: string, detail: string, hookPath?: string }}
+ *   status ∈ { registered, skipped, error }
+ */
+export function installPromptReminderHook({ projectRoot, packageRoot, skipped = false } = {}) {
+  if (skipped) return { status: 'skipped', detail: '--no-prompt-reminders flag' };
+  if (!projectRoot) return { status: 'error', detail: 'install-prompt-reminders: projectRoot is required' };
+  if (!packageRoot) return { status: 'error', detail: 'install-prompt-reminders: packageRoot is required' };
+
+  const hookSrcAbs = join(packageRoot, ...SOURCE_REL);
+  if (!existsSync(hookSrcAbs)) {
+    return { status: 'error', detail: `hook source missing: ${hookSrcAbs}` };
+  }
+
+  const hookDestAbs = join(projectRoot, '.claude', 'hooks', PROMPT_REMINDER_HOOK_FILENAME);
+  const hookRelFromProject = relative(projectRoot, hookDestAbs);
+  if (hookRelFromProject.startsWith('..') || isAbsolute(hookRelFromProject)) {
+    // Defensive — hookDestAbs is constructed from projectRoot so this can't
+    // happen, but the same guardrail used by registerPrewarmSessionStartHook
+    // catches anyone refactoring the join() above incorrectly.
+    return { status: 'error', detail: 'hook destination escapes projectRoot' };
+  }
+
+  try {
+    mkdirSync(dirname(hookDestAbs), { recursive: true });
+    copyFileSync(hookSrcAbs, hookDestAbs);
+  } catch (err) {
+    return { status: 'error', detail: `hook copy failed: ${err.message}` };
+  }
+
+  const command = `node ${hookRelFromProject}`;
+  const settingsResult = writeUserPromptSubmitEntry({
+    projectRoot,
+    command,
+    ownershipFilename: PROMPT_REMINDER_HOOK_FILENAME,
+  });
+  if (settingsResult.status !== 'registered') return settingsResult;
+  return { ...settingsResult, hookPath: hookRelFromProject };
+}
+
+/**
+ * Reverse `installPromptReminderHook`. Removes the hook file and the
+ * UserPromptSubmit settings entry sweet-search owns. Never touches other
+ * UserPromptSubmit entries the user added.
+ *
+ * @returns {{ status: string, detail: string }} — status ∈
+ *   { removed, not-found, dry-run, error }
+ */
+export function removePromptReminderHook({ projectRoot, dryRun = false } = {}) {
+  if (!projectRoot) return { status: 'error', detail: 'remove-prompt-reminders: projectRoot is required' };
+
+  const hookDestAbs = join(projectRoot, '.claude', 'hooks', PROMPT_REMINDER_HOOK_FILENAME);
+  const settingsPath = join(projectRoot, '.claude', 'settings.json');
+
+  const hookExists = existsSync(hookDestAbs);
+  const entryExists = settingsHasOurEntry(settingsPath, PROMPT_REMINDER_HOOK_FILENAME);
+
+  if (!hookExists && !entryExists) return { status: 'not-found', detail: 'no hook file, no settings entry' };
+  if (dryRun) {
+    return {
+      status: 'dry-run',
+      detail: [hookExists && 'hook file', entryExists && 'settings entry'].filter(Boolean).join(' + '),
+    };
+  }
+
+  const removedParts = [];
+  if (hookExists) {
+    try { unlinkSync(hookDestAbs); removedParts.push('hook file'); }
+    catch (err) { return { status: 'error', detail: `failed to remove hook: ${err.message}` }; }
+  }
+  if (entryExists) {
+    const r = removeUserPromptSubmitEntry({ projectRoot, ownershipFilename: PROMPT_REMINDER_HOOK_FILENAME });
+    if (r.status === 'error') return r;
+    if (r.status === 'removed') removedParts.push('settings entry');
+  }
+  return { status: 'removed', detail: removedParts.join(' + ') };
+}
+
+// ─── Shared helpers (factored so install-tool-enforcement.js can reuse) ─────
+
+/**
+ * Write or update a `.claude/settings.json` `hooks.UserPromptSubmit` entry
+ * sweet-search owns. Find-by-filename so re-running never duplicates.
+ */
+export function writeUserPromptSubmitEntry({ projectRoot, command, ownershipFilename }) {
+  const settingsDir = join(projectRoot, '.claude');
+  const settingsPath = join(settingsDir, 'settings.json');
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); }
+    catch (err) { return { status: 'error', detail: `existing settings.json is not valid JSON: ${err.message}` }; }
+  }
+  settings.hooks = settings.hooks || {};
+  const arr = Array.isArray(settings.hooks.UserPromptSubmit) ? settings.hooks.UserPromptSubmit : [];
+
+  const entry = {
+    hooks: [
+      { type: 'command', command, timeout: 4000, continueOnError: true },
+    ],
+  };
+  const ownedIdx = arr.findIndex(group =>
+    Array.isArray(group?.hooks)
+    && group.hooks.some(h => typeof h?.command === 'string' && h.command.includes(ownershipFilename)),
+  );
+  let detail;
+  if (ownedIdx >= 0) { arr[ownedIdx] = entry; detail = 'updated existing entry'; }
+  else { arr.push(entry); detail = 'added new entry'; }
+  settings.hooks.UserPromptSubmit = arr;
+
+  try {
+    mkdirSync(settingsDir, { recursive: true });
+    const tmp = settingsPath + '.tmp';
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    renameSync(tmp, settingsPath);
+  } catch (err) {
+    return { status: 'error', detail: err.message };
+  }
+  return { status: 'registered', detail };
+}
+
+export function removeUserPromptSubmitEntry({ projectRoot, ownershipFilename }) {
+  const settingsPath = join(projectRoot, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return { status: 'not-found', detail: 'no settings.json' };
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); }
+  catch (err) { return { status: 'error', detail: `settings.json invalid: ${err.message}` }; }
+  const arr = Array.isArray(settings?.hooks?.UserPromptSubmit) ? settings.hooks.UserPromptSubmit : [];
+  const next = arr.filter(group =>
+    !Array.isArray(group?.hooks)
+    || !group.hooks.some(h => typeof h?.command === 'string' && h.command.includes(ownershipFilename)),
+  );
+  if (next.length === arr.length) return { status: 'not-found', detail: 'no sweet-search entry' };
+  if (next.length === 0) {
+    if (settings.hooks) delete settings.hooks.UserPromptSubmit;
+  } else {
+    settings.hooks.UserPromptSubmit = next;
+  }
+  // Drop empty `hooks` to keep settings.json tidy.
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  try {
+    const tmp = settingsPath + '.tmp';
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    renameSync(tmp, settingsPath);
+  } catch (err) {
+    return { status: 'error', detail: err.message };
+  }
+  return { status: 'removed', detail: 'stripped UserPromptSubmit entry' };
+}
+
+function settingsHasOurEntry(settingsPath, ownershipFilename) {
+  if (!existsSync(settingsPath)) return false;
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); }
+  catch { return false; }
+  const arr = Array.isArray(settings?.hooks?.UserPromptSubmit) ? settings.hooks.UserPromptSubmit : [];
+  return arr.some(group =>
+    Array.isArray(group?.hooks)
+    && group.hooks.some(h => typeof h?.command === 'string' && h.command.includes(ownershipFilename)),
+  );
+}