sweet-search 2.5.2 → 2.5.3

package/scripts/init.js

@@ -12,11 +12,13 @@
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative } from 'node:path';
+import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import {
   getModelEntry, getModelsForProfile, getSkippedOptInModels, MODEL_REGISTRY, fetchModel, getModelCacheDir,
+  isNativeAcceleratedModel,
   getPlatformInfo, resolveNativeAddon, resolveNativeBinary,
   detectHardwareCapability,
   getCoremlCascadeState, getCoremlCascadeReport, fetchCoremlCascade,
@@ -35,6 +37,11 @@ import {
 } from '../core/ranking/late-interaction-policy.js';
 import { describeDedupConfig } from '../core/infrastructure/index.js';
 import { verifyRuntime, getMaxsimTier, getRouterType } from './verify-runtime.js';
+import { ALL_HARNESSES, injectAgentInstructions } from './inject-agent-instructions.js';
+import { writeClaudeRules } from './write-claude-rules.js';
+import { installPromptReminderHook } from './install-prompt-reminders.js';
+import { installToolEnforcement } from './install-tool-enforcement.js';
+import { isNativeInferenceAvailable } from '../core/infrastructure/native-inference.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = join(__dirname, '..');
@@ -61,6 +68,21 @@ export function parseInitArgs(args) {
     liModel: null,           // Phase 4: --li-model standard|edge|none (raw user input; 'standard' aliased to 'lateon-code')
     searchReranking: null,   // Phase 4: --search-reranking auto|on|off
     wizard: false,           // Phase 4: --wizard runs interactive prompts
+    // P1 (system-prompt opt) — agent-instruction injection.
+    // Default: only CLAUDE.md (sweet-search is Claude-first).
+    //   --agents / --gemini / --cursor opt INTO additional harness files.
+    //   --no-claude opts OUT of CLAUDE.md *and* every .claude/* write
+    //     (hooks, skills, rules, settings-json mutations).
+    //   --no-agent-instructions is the umbrella: skip the four harness
+    //     instruction files but keep .claude/* hooks unless --no-claude.
+    skipAgentInstructions: false,
+    symlinkInstructionFiles: true,
+    optInHarnesses: new Set(),
+    noClaude: false,
+    skipPromptReminders: false, // P2: --no-prompt-reminders (default OFF)
+    enforceTools: false,        // P3: --enforce-tools (default OFF — opt-in strict mode)
+    codex: false,                // --codex: wire the Codex CLI SessionStart hook
+    codexEnableGlobalHooks: false, // --codex-enable-global-hooks: also enable the flag in ~/.codex/config.toml
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -113,12 +135,86 @@ export function parseInitArgs(args) {
       // native package are present. Equivalent to SWEET_SEARCH_CUDA=0
       // but persisted through init's diagnostic output.
       result.skipCuda = true;
+    } else if (arg === '--no-agent-instructions') {
+      // P1: skip ALL instruction-file writes (CLAUDE.md / AGENTS.md /
+      // GEMINI.md / .cursor/rules/sweet-search.mdc / .claude/rules/sweet-search.md).
+      result.skipAgentInstructions = true;
+    } else if (arg === '--no-symlink-instruction-files') {
+      // P1: write GEMINI.md as a copy with @import rather than a symlink to
+      // the canonical file. Useful on filesystems that don't support symlinks
+      // (e.g. some Windows configurations) or when a tool requires a regular file.
+      result.symlinkInstructionFiles = false;
+    } else if (arg === '--symlink-instruction-files') {
+      // P1: explicit ON — useful for clarity in scripts even though it's the default.
+      result.symlinkInstructionFiles = true;
+    } else if (arg === '--no-claude') {
+      // P1: opt out of CLAUDE.md *and* every other .claude/* write that
+      // init normally performs (rules file, /sweet-index skill,
+      // index-maintainer hook, prewarm SessionStart entry). Universal
+      // gate — the user has signalled they don't use Claude Code.
+      // If `--agents` / `--gemini` / `--cursor` is also set, AGENTS.md
+      // (or whichever opt-in is canonical) carries the policy instead.
+      result.noClaude = true;
+    } else if (arg === '--agents') {
+      // P1: opt INTO writing AGENTS.md, the multi-harness convention
+      // (Codex CLI, OpenCode, and any other tool that adopts AGENTS.md).
+      result.optInHarnesses.add('agents');
+    } else if (arg === '--gemini') {
+      // P1: opt INTO writing GEMINI.md.
+      result.optInHarnesses.add('gemini');
+    } else if (arg === '--cursor') {
+      // P1: opt INTO writing .cursor/rules/sweet-search.mdc.
+      result.optInHarnesses.add('cursor');
+    } else if (arg === '--codex') {
+      // Wire the Codex CLI: write a SessionStart hook into .codex/hooks.json
+      // (Codex's hook surface) reusing the same launcher as the Claude prewarm
+      // hook, and ship AGENTS.md (Codex's instruction file) by implying
+      // --agents. Independent of --no-claude (writes .codex/, not .claude/).
+      result.codex = true;
+      result.optInHarnesses.add('agents');
+    } else if (arg === '--codex-enable-global-hooks') {
+      // Legacy/advanced opt-in: also enable the `[features] hooks` feature flag
+      // in the user-level ~/.codex/config.toml. NOT required for the normal
+      // path — `--codex` already enables the flag in the project config. Off by
+      // default because it writes outside the project into the user's
+      // hand-curated global config.
+      result.codexEnableGlobalHooks = true;
+    } else if (arg === '--no-prompt-reminders') {
+      // P2: skip the UserPromptSubmit reminder hook. Default-on because
+      // the reminder is the cheapest available shift-left for tool
+      // selection (~80 tokens per prompt vs avoided re-search loops).
+      result.skipPromptReminders = true;
+    } else if (arg === '--enforce-tools') {
+      // P3: opt-in strict mode — denies native Grep + installs a Read
+      // hint hook. Opinionated and Claude-specific (per §4D).
+      result.enforceTools = true;
     }
   }
 
   return result;
 }
 
+/**
+ * Resolve the active harness list. Default is `claude-code` only;
+ * `--agents` / `--gemini` / `--cursor` add to that set; `--no-claude`
+ * removes claude-code (and gates every .claude/* write — see init flow).
+ *
+ * @param {object} args
+ * @param {Set<string>|string[]} [args.optInHarnesses] subset of
+ *   {agents, gemini, cursor} to add on top of the default
+ * @param {boolean} [args.noClaude] when true, drops claude-code entirely
+ * @returns {string[]} ordered list matching ALL_HARNESSES order
+ */
+export function resolveActiveHarnesses({ optInHarnesses, noClaude = false } = {}) {
+  const optIn = optInHarnesses instanceof Set
+    ? optInHarnesses
+    : new Set(optInHarnesses ?? []);
+  const active = new Set();
+  if (!noClaude) active.add('claude-code');
+  for (const h of optIn) active.add(h);
+  return ALL_HARNESSES.filter(h => active.has(h));
+}
+
 // ---------------------------------------------------------------------------
 // Node.js version check
 // ---------------------------------------------------------------------------
@@ -495,11 +591,53 @@ export function filterModelKeysForLiChoice(modelKeys, liModel) {
   return modelKeys;
 }
 
+/**
+ * Drop native-accelerated FP32 safetensors keys on CPU-only hosts. Those
+ * artifacts (coderankembed-fp32, lateon-code-fp32, lateon-code-edge-fp32) are
+ * loaded only by the candle/native accelerated indexing path (Metal / CoreML
+ * cascade / CUDA); a no-accelerator host indexes with ORT INT8 CPU and never
+ * loads them, so fetching ~1.2 GB of FP32 weights is pure waste.
+ *
+ * `hasAccelerator` is derived from the hardware-capability snapshot plus
+ * native-inference availability by the caller. Order-preserving +
+ * non-mutating: returns a new array.
+ * Classification of "is this a native FP32 model" lives in the registry
+ * (`isNativeAcceleratedModel`), so this stays a thin policy filter.
+ *
+ * Only an explicit `hasAccelerator: false` triggers filtering — `undefined`
+ * (flag omitted) and `true` both keep every key. That makes an accidental
+ * omission safe (it never silently drops the FP32 backbones).
+ */
+export function filterModelKeysForAccelerator(modelKeys, { hasAccelerator } = {}) {
+  if (hasAccelerator !== false) return modelKeys;
+  return modelKeys.filter((k) => !isNativeAcceleratedModel(k));
+}
+
+/**
+ * Init-time accelerator availability for model shipping. A hardware
+ * accelerator only counts when native inference can actually load it; hosts
+ * with SWEET_SEARCH_NATIVE_INFERENCE=0, no native addon, or a native load
+ * failure index on ORT INT8 CPU and should skip native FP32 safetensors.
+ */
+export function hasUsableIndexAccelerator({
+  capability,
+  nativeInferenceAvailable = true,
+} = {}) {
+  if (nativeInferenceAvailable !== true) return false;
+  return capability?.inferenceBackendPreference === 'coreml-cascade'
+    || capability?.inferenceBackendPreference === 'candle-metal'
+    || capability?.inferenceBackendPreference === 'candle-cuda';
+}
+
 export async function downloadModelsForProfile(profile, options = {}) {
   let modelKeys = getModelsForProfile(profile);
   if (options.liModel) {
     modelKeys = filterModelKeysForLiChoice(modelKeys, options.liModel);
   }
+  // CPU-only hosts skip native FP32 safetensors. The filter only drops keys
+  // when `hasAccelerator` is explicitly false; an unset option (legacy
+  // callers, accelerator hosts) preserves the "fetch everything" behavior.
+  modelKeys = filterModelKeysForAccelerator(modelKeys, { hasAccelerator: options.hasAccelerator });
   if (modelKeys.length === 0) {
     return { results: new Map(), totalDownloaded: 0, totalCached: 0, failures: [] };
   }
@@ -557,7 +695,8 @@ function printReport(report) {
   const {
     profile, maxsimTier, routerType, models, verification, runtimeDownloads,
     capability, cascadeReport, dedupReport, prewarmHookReport, skillReport,
-    liChoices,
+    liChoices, agentInstructionsReport, claudeRulesReport,
+    promptReminderReport, toolEnforcementReport,
   } = report;
 
   console.log('');
@@ -663,6 +802,21 @@ function printReport(report) {
     }
   }
 
+  if (agentInstructionsReport) {
+    const summary = Object.entries(agentInstructionsReport.harnesses)
+      .map(([k, v]) => `${k}=${v}`).join(' ');
+    console.log(`  Agent instructions:   ${summary}`);
+  }
+  if (claudeRulesReport) {
+    console.log(`  Claude rules file:    ${claudeRulesReport.status}`);
+  }
+  if (promptReminderReport && promptReminderReport.status !== 'skipped') {
+    console.log(`  Prompt reminder hook: ${promptReminderReport.status}`);
+  }
+  if (toolEnforcementReport && toolEnforcementReport.status !== 'skipped') {
+    console.log(`  Tool enforcement:     ${toolEnforcementReport.status} (Grep deny + Read hint)`);
+  }
+
   console.log(`  Runtime downloads:    ${runtimeDownloads}`);
 
   const passedCount = verification.checks.filter(c => c.status === 'pass').length;
@@ -839,6 +993,264 @@ export function registerPrewarmSessionStartHook({
   };
 }
 
+// ---------------------------------------------------------------------------
+// Codex CLI SessionStart hook (--codex)
+// ---------------------------------------------------------------------------
+
+export const CODEX_HOOKS_FILENAME = 'hooks.json';
+
+/**
+ * Register (or update) a Codex CLI SessionStart hook in `.codex/hooks.json`
+ * that launches the search server + incremental-index maintainer on every
+ * Codex session — the Codex analogue of `registerPrewarmSessionStartHook`.
+ * Reuses the same harness-agnostic launcher (`session-daemon-prewarm.mjs`,
+ * matched by `PREWARM_HOOK_FILENAME`), which reads only env/cwd and writes
+ * nothing to stdout, so it is safe under Codex's hook contract.
+ *
+ * Codex hook schema (developers.openai.com/codex/hooks):
+ *   { "hooks": { "SessionStart": [ { "hooks": [ { type, command, timeout } ] } ] } }
+ *
+ * Non-destructive + idempotent: preserves other events/entries and replaces
+ * the sweet-search-owned entry (matched by the launcher filename) instead of
+ * appending a duplicate. Refuses to write a machine-specific absolute path
+ * into the (often committed) `.codex/hooks.json`, mirroring the Claude path.
+ *
+ * NOTE: hooks only fire when Codex's `[features] hooks` flag is enabled and the
+ * project `.codex/` layer is trusted (reviewed via `/hooks`) — neither of which
+ * a project init can fully guarantee. `ensureCodexHooksFeatureFlag` handles the
+ * flag (best-effort) and the init report prints the trust caveat.
+ *
+ * @returns {{status:'registered'|'skipped'|'error', detail:string, hookPath?:string}}
+ */
+export function registerCodexSessionStartHook({ projectRoot, packageRoot, skipped = false } = {}) {
+  if (skipped) return { status: 'skipped', detail: '--skip-prewarm-hook flag' };
+
+  const hookScriptAbs = join(packageRoot, 'core', 'search', PREWARM_HOOK_FILENAME);
+  if (!existsSync(hookScriptAbs)) {
+    return { status: 'error', detail: `hook script missing: ${hookScriptAbs}` };
+  }
+
+  const hookPath = relative(projectRoot, hookScriptAbs);
+  if (hookPath.startsWith('..') || isAbsolute(hookPath)) {
+    return {
+      status: 'skipped',
+      detail: 'package lives outside projectRoot (hoisted / linked / global install) — re-run with --skip-prewarm-hook to silence this',
+    };
+  }
+
+  // Codex runs hook commands with the *session* cwd, and per its hooks docs a
+  // session "may be started from a subdirectory", so a bare relative path is
+  // unreliable — the docs explicitly recommend resolving from the git root.
+  // We `cd` to the git toplevel first (falling back to the current dir outside
+  // a repo), which fixes both path resolution AND the launcher's own
+  // `process.cwd()` project-root detection, while staying machine-portable
+  // (no absolute path is written into the often-committed hooks.json).
+  const command = `cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && node ${JSON.stringify(hookPath)}`;
+  const codexDir = join(projectRoot, '.codex');
+  const hooksPath = join(codexDir, CODEX_HOOKS_FILENAME);
+
+  let doc = {};
+  if (existsSync(hooksPath)) {
+    try {
+      doc = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+    } catch (err) {
+      return { status: 'error', detail: `existing .codex/hooks.json is not valid JSON: ${err.message}` };
+    }
+  }
+
+  doc.hooks = doc.hooks || {};
+  const sessionStart = Array.isArray(doc.hooks.SessionStart) ? doc.hooks.SessionStart : [];
+
+  // `matcher` mirrors the official Codex SessionStart example: fire on a new
+  // session and on resume (the cases where the daemon may not be running yet).
+  // `timeout` is in seconds (per Codex's hooks docs); the launcher detaches and
+  // returns in well under a second, so a small budget is plenty.
+  const entry = {
+    matcher: 'startup|resume',
+    hooks: [
+      {
+        type: 'command',
+        command,
+        timeout: 10,
+      },
+    ],
+  };
+
+  const ownedIdx = sessionStart.findIndex((group) =>
+    Array.isArray(group?.hooks) &&
+    group.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(PREWARM_HOOK_FILENAME))
+  );
+
+  if (ownedIdx >= 0) {
+    sessionStart[ownedIdx] = entry;
+  } else {
+    sessionStart.push(entry);
+  }
+  doc.hooks.SessionStart = sessionStart;
+
+  try {
+    mkdirSync(codexDir, { recursive: true });
+    const tmpPath = hooksPath + '.tmp';
+    writeFileSync(tmpPath, JSON.stringify(doc, null, 2) + '\n', 'utf-8');
+    renameSync(tmpPath, hooksPath);
+  } catch (err) {
+    return { status: 'error', detail: err.message };
+  }
+
+  return {
+    status: 'registered',
+    detail: ownedIdx >= 0 ? 'updated existing entry' : 'added new entry',
+    hookPath,
+  };
+}
+
+/**
+ * Ensure the canonical Codex hooks feature flag `[features] hooks = true` is
+ * present in a Codex `config.toml`, preserving the file's existing content +
+ * comments. Targeted text edit (no TOML round-trip) so a hand-curated config is
+ * never reformatted.
+ *
+ * `hooks` is the canonical key as of Codex v0.132+. The earlier `codex_hooks`
+ * key is deprecated (Codex now prints a deprecation warning for it), so this
+ * function also MIGRATES a legacy `codex_hooks` flag to `hooks` instead of
+ * writing the deprecated name. Legacy handling is deliberate: users who ran an
+ * older sweet-search (which wrote `codex_hooks`) or older Codex shouldn't be
+ * left with a deprecated, warning-producing flag.
+ *
+ * Behaviour:
+ *   - `hooks = true` already present → no-op ('already'); if a deprecated
+ *     `codex_hooks` line also lingers, strip it ('migrated')
+ *   - `hooks` present but non-true → respect the user's choice ('present-other')
+ *   - legacy `codex_hooks` present (no `hooks` key) → rename the key to `hooks`
+ *     in place, preserving its value + inline comment ('migrated')
+ *   - a `[features]` table exists → insert `hooks = true` under its header
+ *   - no `[features]` table → append a fresh block at EOF
+ *   - file absent + `create` → create it; absent + no `create` → 'absent'
+ *
+ * @param {string} configPath
+ * @param {{create?:boolean}} [opts]
+ * @returns {{status:'created'|'added'|'migrated'|'already'|'present-other'|'absent'|'error', path:string, detail?:string}}
+ */
+export function ensureCodexHooksFeatureFlag(configPath, { create = false } = {}) {
+  const exists = existsSync(configPath);
+  if (!exists && !create) return { status: 'absent', path: configPath };
+
+  let text = '';
+  if (exists) {
+    try {
+      text = readFileSync(configPath, 'utf-8');
+    } catch (err) {
+      return { status: 'error', path: configPath, detail: `read failed: ${err.message}` };
+    }
+  }
+
+  const write = (next, status) => {
+    try {
+      mkdirSync(dirname(configPath), { recursive: true });
+      const tmp = configPath + '.tmp';
+      writeFileSync(tmp, next, 'utf-8');
+      renameSync(tmp, configPath);
+    } catch (err) {
+      return { status: 'error', path: configPath, detail: `write failed: ${err.message}` };
+    }
+    return { status, path: configPath };
+  };
+
+  // `^[ \t]*hooks` cannot match a `codex_hooks` line (the prefix differs), so
+  // these canonical-key checks never collide with the legacy key.
+  const HOOKS_TRUE = /^[ \t]*hooks[ \t]*=[ \t]*true\b/m;
+  const HOOKS_ANY = /^[ \t]*hooks[ \t]*=/m;
+  const LEGACY_ANY = /^[ \t]*codex_hooks[ \t]*=/m;
+  const LEGACY_LINE = /^[ \t]*codex_hooks[ \t]*=.*(?:\r?\n)?/m;
+
+  // Canonical flag already enabled.
+  if (HOOKS_TRUE.test(text)) {
+    if (LEGACY_ANY.test(text)) {
+      // Strip the deprecated `codex_hooks` line so Codex v0.132+ stops warning.
+      return write(text.replace(LEGACY_LINE, ''), 'migrated');
+    }
+    return { status: 'already', path: configPath };
+  }
+
+  // Canonical flag present but explicitly non-true → respect the user's choice;
+  // don't add a duplicate key (which would make the TOML invalid).
+  if (HOOKS_ANY.test(text)) {
+    return { status: 'present-other', path: configPath };
+  }
+
+  // Deprecated `codex_hooks` present (no canonical key) → migrate the key name
+  // in place, preserving its value and any inline comment.
+  if (LEGACY_ANY.test(text)) {
+    return write(text.replace(/^([ \t]*)codex_hooks([ \t]*=.*)$/m, '$1hooks$2'), 'migrated');
+  }
+
+  // Neither key present → add the canonical flag.
+  let next;
+  if (!exists || text.trim() === '') {
+    next = '[features]\nhooks = true\n';
+  } else if (/^[ \t]*\[features\][ \t]*$/m.test(text)) {
+    next = text.replace(/^([ \t]*\[features\][ \t]*)$/m, '$1\nhooks = true');
+  } else {
+    const sep = text.endsWith('\n') ? '' : '\n';
+    next = `${text}${sep}\n[features]\nhooks = true\n`;
+  }
+  return write(next, exists ? 'added' : 'created');
+}
+
+/**
+ * Build the post-init Codex guidance message (or `null` when the hook wasn't
+ * registered). Pure / string-only so the UX wording can be unit-tested without
+ * spawning init.
+ *
+ * `init --codex` is the COMPLETE normal setup — it has already written the hook
+ * and enabled the canonical `[features] hooks = true` in the project config — so
+ * this message frames `/hooks` trust as the ONLY remaining manual step. It never
+ * tells the user they must pass `--codex-enable-global-hooks` (a legacy/advanced
+ * opt-in), and it never names the deprecated `codex_hooks` key.
+ *
+ * @param {{hookStatus:string, projectFlagStatus:string}} params
+ * @returns {string|null}
+ */
+export function formatCodexSetupGuidance({ hookStatus, projectFlagStatus } = {}) {
+  if (hookStatus !== 'registered') return null;
+
+  // `created` / `added` / `already` / `migrated` all mean the canonical
+  // `[features] hooks = true` is now present in the project config — so init has
+  // done the enable and the only manual step left is project trust via `/hooks`.
+  const projectEnabled = ['created', 'added', 'already', 'migrated'].includes(projectFlagStatus);
+  if (projectEnabled) {
+    return (
+      `[init] Codex is set up. Project hooks are enabled ` +
+      `([features] hooks = true in ./.codex/config.toml).\n` +
+      `         One manual step remains (init can't do it for you):\n` +
+      `           • Run \`/hooks\` inside Codex to review and trust the repo-local\n` +
+      `             .codex/hooks.json before Codex will run it.\n` +
+      `         Notes:\n` +
+      `           • Index freshness does NOT depend on this hook — the sweet-search\n` +
+      `             CLI/warm-server starts the incremental maintainer on first use\n` +
+      `             under any agent. The Codex hook is only an early prewarm.\n` +
+      `           • \`codex exec\` (non-interactive) does not fire SessionStart hooks.\n` +
+      `           • MCP is optional and not required for incremental indexing.\n`
+    );
+  }
+
+  if (projectFlagStatus === 'present-other') {
+    return (
+      `[init] Codex hook written, but ./.codex/config.toml already sets ` +
+      `[features] hooks to a non-true value — left as-is.\n` +
+      `         Set \`hooks = true\` (or run \`codex --enable hooks\`), then trust\n` +
+      `         the hook with \`/hooks\` in Codex. Index freshness still works\n` +
+      `         without it (CLI/warm-server first-use).\n`
+    );
+  }
+
+  return (
+    `[init] Codex hook written, but enabling [features] hooks in ` +
+    `./.codex/config.toml did not succeed (status: ${projectFlagStatus}).\n` +
+    `         Set \`hooks = true\` manually, then trust the hook with \`/hooks\`.\n`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // /sweet-index skill installation
 // ---------------------------------------------------------------------------
@@ -936,7 +1348,71 @@ Options:
   --skip-cuda               Force-disable the CUDA backend even when an
                             NVIDIA GPU and the -cuda native package are
                             detected. Equivalent to SWEET_SEARCH_CUDA=0.
-                            Indexing falls back to candle-cpu.
+                            Indexing falls back to ORT INT8 CPU (and native
+                            FP32 safetensors are skipped at fetch time).
+  --no-agent-instructions   Skip the agent-instruction injection layer
+                            entirely (no CLAUDE.md, no AGENTS.md, no
+                            GEMINI.md, no Cursor rule, no
+                            .claude/rules/sweet-search.md). Use when you
+                            manage your own agent instructions. Idempotent
+                            rewrites use a marker block; re-running init
+                            never duplicates content.
+  --no-claude               Don't ship anything to .claude/. Skips
+                            CLAUDE.md + .claude/rules/sweet-search.md +
+                            .claude/hooks/index-maintainer.mjs +
+                            .claude/skills/sweet-index/ +
+                            .claude/settings.json prewarm SessionStart entry.
+                            Combine with --agents / --gemini / --cursor to
+                            ship the policy through a non-Claude harness.
+  --agents                  Also ship AGENTS.md, the multi-harness
+                            convention read by Codex CLI, OpenCode, and any
+                            other tool that adopts AGENTS.md. Without
+                            --no-claude, AGENTS.md is a thin @CLAUDE.md
+                            import shim; with --no-claude it carries the
+                            full canonical policy body.
+  --gemini                  Also ship GEMINI.md (symlink → canonical, or
+                            an @import file when --no-symlink-instruction-files).
+  --cursor                  Also ship .cursor/rules/sweet-search.mdc with
+                            sweet-search frontmatter.
+  --codex                   Complete Codex CLI setup (the normal path): write a
+                            SessionStart hook into .codex/hooks.json (reusing the
+                            same launcher as the Claude prewarm hook, so Codex
+                            sessions also start the search server + default-on
+                            incremental maintainer), enable [features] hooks = true
+                            in the project .codex/config.toml (migrating a
+                            deprecated codex_hooks flag if present), and ship
+                            AGENTS.md (implies --agents). Independent of
+                            --no-claude. The only remaining manual step is to
+                            review/trust the repo-local hook with /hooks inside
+                            Codex. Index freshness does NOT depend on this hook —
+                            the sweet-search CLI/warm-server starts the maintainer
+                            on first use under any agent; the hook is just an early
+                            prewarm. MCP is optional and not required.
+  --codex-enable-global-hooks
+                            [legacy/advanced] Not needed for normal setup — the
+                            project-level flag written by --codex is sufficient.
+                            Use only to deliberately migrate the user-level
+                            ~/.codex/config.toml: enables [features] hooks = true
+                            there too (append-if-absent, comment-preserving,
+                            migrates a deprecated codex_hooks). Off by default
+                            because it writes outside the project into your global
+                            Codex config.
+  --no-symlink-instruction-files
+                            Write GEMINI.md as a regular file with an @import
+                            line rather than a symlink to the canonical file.
+                            Useful on filesystems / hosts where symlinks
+                            aren't supported. Default is to symlink.
+  --no-prompt-reminders     Skip the UserPromptSubmit reminder hook (default
+                            on). The reminder injects a small (~80 token)
+                            sweet-search tool-routing summary into every
+                            prompt to prevent drift back to native Grep/Read.
+                            Always implied when --no-claude is set.
+  --enforce-tools           (Opt-in strict mode) Deny native Grep entirely
+                            (forces ss-grep) and install a hint hook for
+                            native Read suggesting ss-read / ss-semantic.
+                            Read is hinted, not blocked, because edit
+                            workflows legitimately need Read. Always
+                            implied off when --no-claude is set.
   --verbose, -v             Enable verbose output
   --help, -h                Show this help
 
@@ -999,7 +1475,25 @@ export async function runInit(args) {
   //      and final config write all see the same choices. Uses an early
   //      hardware capability snapshot for the recommendation; the snapshot
   //      is recomputed later for the runtime config (cheap + cacheable).
+  //
+  // --skip-cuda: translate to SWEET_SEARCH_CUDA=0 BEFORE the first
+  // detectHardwareCapability() call below, which caches its result. Setting it
+  // here (not just before step 8) ensures the early snapshot used for model
+  // fetching, the persisted runtime config, and the cascade decision all see
+  // CUDA as disabled — a --skip-cuda host is treated as CPU-only end to end.
+  if (parsed.skipCuda && !process.env.SWEET_SEARCH_CUDA) {
+    process.env.SWEET_SEARCH_CUDA = '0';
+  }
   const earlyCapability = detectHardwareCapability();
+  const nativeInferenceAvailable = isNativeInferenceAvailable();
+  // A host has a usable accelerator only when hardware detection found one AND
+  // native inference can actually load. If native inference is disabled or the
+  // addon is absent/unloadable, init skips native FP32 safetensors because
+  // indexing will stay on ORT INT8 CPU at runtime.
+  const hasAccelerator = hasUsableIndexAccelerator({
+    capability: earlyCapability,
+    nativeInferenceAvailable,
+  });
   let liChoices;
   try {
     liChoices = await resolveLiPolicyChoices({
@@ -1053,13 +1547,26 @@ export async function runInit(args) {
   //    variants; 'edge' skips standard variants. Saves disk + bandwidth on
   //    constrained installs.
   const allModelKeys = getModelsForProfile(profile);
-  const modelKeys = filterModelKeysForLiChoice(allModelKeys, liChoices.liModel);
-  const skippedByLiChoice = allModelKeys.filter((k) => !modelKeys.includes(k));
+  const liFilteredKeys = filterModelKeysForLiChoice(allModelKeys, liChoices.liModel);
+  // CPU-only hosts (no Metal/CoreML/CUDA) skip native FP32 safetensors. Apply
+  // the same filter to the keys handed to verification below, so we only verify
+  // what we actually fetched — verifyRuntime checks on-disk presence and would
+  // otherwise FAIL on the intentionally-absent FP32 artifacts.
+  const modelKeys = filterModelKeysForAccelerator(liFilteredKeys, { hasAccelerator });
+  const skippedByLiChoice = allModelKeys.filter((k) => !liFilteredKeys.includes(k));
+  const skippedByAccelerator = liFilteredKeys.filter((k) => !modelKeys.includes(k));
   if (skippedByLiChoice.length > 0 && parsed.verbose) {
     process.stderr.write(
       `[init]   liModel=${liChoices.liModel} → skipping ${skippedByLiChoice.length} model key(s): ${skippedByLiChoice.join(', ')}\n`,
     );
   }
+  if (skippedByAccelerator.length > 0) {
+    process.stderr.write(
+      `[init]   no inference accelerator (${earlyCapability.inferenceBackendPreference}) → `
+      + `skipping ${skippedByAccelerator.length} native FP32 model key(s): ${skippedByAccelerator.join(', ')} `
+      + `(indexing uses ORT INT8 CPU)\n`,
+    );
+  }
   const skippedOptIns = getSkippedOptInModels(profile);
   let modelResults = new Map();
 
@@ -1082,6 +1589,7 @@ export async function runInit(args) {
     const downloadResult = await downloadModelsForProfile(profile, {
       force: parsed.force,
       liModel: liChoices.liModel,
+      hasAccelerator,
     });
 
     modelResults = downloadResult.results;
@@ -1112,13 +1620,6 @@ export async function runInit(args) {
     process.stderr.write(`[init] No models required for profile "${profile}"\n`);
   }
 
-  // --skip-cuda: translate to SWEET_SEARCH_CUDA=0 so the shared
-  // capability detection on hardware-capability.js honors it. Set before
-  // detectHardwareCapability() runs because that call caches its result.
-  if (parsed.skipCuda && !process.env.SWEET_SEARCH_CUDA) {
-    process.env.SWEET_SEARCH_CUDA = '0';
-  }
-
   // 8. Resolve hardware capability + CoreML cascade state.
   //
   // The cascade is an M3+ Apple Silicon acceleration for native inference.
@@ -1286,55 +1787,194 @@ export async function runInit(args) {
     process.exit(1);
   }
 
-  // 10. Install index-maintainer daemon hook
-  try {
-    const hookDir = join(projectRoot, '.claude', 'hooks');
-    const hookDest = join(hookDir, 'index-maintainer.mjs');
-    const hookSrc = join(PACKAGE_ROOT, 'core', 'indexing', 'index-maintainer.mjs');
-    if (!existsSync(hookDest)) {
-      mkdirSync(hookDir, { recursive: true });
-      copyFileSync(hookSrc, hookDest);
-      process.stderr.write(`[init] Installed index-maintainer daemon to ${hookDir}\n`);
+  // 10. Install index-maintainer daemon hook (Claude-only — gated on
+  //     --no-claude per the universal "don't touch .claude/" contract).
+  let skillReport = null;
+  let prewarmHookReport = null;
+  if (parsed.noClaude) {
+    if (parsed.verbose) {
+      process.stderr.write(`[init] Skipping all .claude/ writes (--no-claude): index-maintainer hook, /sweet-index skill, prewarm SessionStart entry\n`);
+    }
+  } else {
+    try {
+      const hookDir = join(projectRoot, '.claude', 'hooks');
+      const hookDest = join(hookDir, 'index-maintainer.mjs');
+      const hookSrc = join(PACKAGE_ROOT, 'core', 'indexing', 'index-maintainer.mjs');
+      if (!existsSync(hookDest)) {
+        mkdirSync(hookDir, { recursive: true });
+        copyFileSync(hookSrc, hookDest);
+        process.stderr.write(`[init] Installed index-maintainer daemon to ${hookDir}\n`);
+      } else {
+        process.stderr.write(`[init] Index-maintainer daemon already installed\n`);
+      }
+    } catch (e) {
+      process.stderr.write(`[init] Warning: Could not install index-maintainer: ${e.message}\n`);
+    }
+
+    // 11. Install /sweet-index skill — Claude-only artifact, gated on --no-claude.
+    skillReport = installSweetIndexSkill({
+      projectRoot,
+      packageRoot: PACKAGE_ROOT,
+    });
+    if (skillReport.status === 'installed') {
+      process.stderr.write(`[init] Installed /sweet-index skill to ${skillReport.detail}\n`);
+    } else if (skillReport.status === 'already-installed') {
+      process.stderr.write(`[init] /sweet-index skill already installed\n`);
+    } else if (skillReport.status === 'error') {
+      process.stderr.write(`[init] Warning: Could not install /sweet-index skill: ${skillReport.detail}\n`);
+    }
+
+    // 11.5. Register Claude Code SessionStart daemon-prewarm hook.
+    //       Spawns the search daemon detached in the background so the user's
+    //       first `sweet-search <query>` hits a warm daemon (~80ms) instead of
+    //       paying ~2.5s cold-start. The hook exits immediately; the daemon
+    //       loads models + indexes while the user reads Claude's first reply.
+    //       Never blocks init — any write failure collapses to a silent no-op
+    //       on next session start.
+    prewarmHookReport = registerPrewarmSessionStartHook({
+      projectRoot,
+      packageRoot: PACKAGE_ROOT,
+      skipped: parsed.skipPrewarmHook,
+    });
+    if (parsed.verbose || prewarmHookReport.status === 'error') {
+      process.stderr.write(`[init] Prewarm hook: ${prewarmHookReport.status} — ${prewarmHookReport.detail}\n`);
+    }
+  }
+
+  // 11.6. Codex CLI session-start hook + feature flag (opt-in via --codex).
+  //       `--codex` is the COMPLETE normal Codex setup: it writes Codex's hook
+  //       surface (.codex/hooks.json), enables the canonical [features] hooks
+  //       flag in the PROJECT .codex/config.toml (migrating a deprecated
+  //       codex_hooks), and ships AGENTS.md. Independent of --no-claude (it
+  //       touches .codex/, never .claude/). The one thing init can't do for the
+  //       user is project trust — surfaced as a single `/hooks` instruction. The
+  //       user-level global flag is a legacy/advanced opt-in
+  //       (--codex-enable-global-hooks), never required for the normal path. The
+  //       Codex hook is a prewarm convenience only: default index freshness is
+  //       guaranteed by the core CLI/warm-server first-use launcher regardless of
+  //       editor or MCP.
+  let codexHookReport = null;
+  if (parsed.codex) {
+    codexHookReport = registerCodexSessionStartHook({
+      projectRoot,
+      packageRoot: PACKAGE_ROOT,
+      skipped: parsed.skipPrewarmHook,
+    });
+    const projectFlag = ensureCodexHooksFeatureFlag(
+      join(projectRoot, '.codex', 'config.toml'),
+      { create: true },
+    );
+    let globalFlag = null;
+    if (parsed.codexEnableGlobalHooks) {
+      globalFlag = ensureCodexHooksFeatureFlag(
+        join(homedir(), '.codex', 'config.toml'),
+        { create: true },
+      );
+    }
+
+    process.stderr.write(`[init] Codex hook: ${codexHookReport.status} — ${codexHookReport.detail}\n`);
+    process.stderr.write(`[init] Codex [features] hooks flag (project .codex/config.toml): ${projectFlag.status}\n`);
+    if (globalFlag) {
+      process.stderr.write(`[init] Codex [features] hooks flag (~/.codex/config.toml): ${globalFlag.status}\n`);
+    }
+    const guidance = formatCodexSetupGuidance({
+      hookStatus: codexHookReport.status,
+      projectFlagStatus: projectFlag.status,
+    });
+    if (guidance) process.stderr.write(guidance);
+  }
+
+  // 12-15. Inject the sweet-search policy across coding-agent harnesses.
+  //        Default: only CLAUDE.md (sweet-search is Claude-first; the
+  //        existing project CLAUDE.md is where users look). Opt INTO
+  //        additional harnesses with --agents (AGENTS.md) / --gemini /
+  //        --cursor. --no-claude opts OUT of CLAUDE.md AND every other
+  //        .claude/* write (universal gate enforced above).
+  //        Plan §4A + §4B + §10 (the canonical flip from AGENTS.md →
+  //        CLAUDE.md is a user-driven product call — plan doc updated
+  //        in §3.3 / §10).
+  //        Idempotent marker block so re-init never duplicates content.
+  //        `--no-agent-instructions` is the umbrella that skips the
+  //        instruction-file injection layer entirely.
+  let agentInstructionsReport = null;
+  let claudeRulesReport = null;
+  if (!parsed.skipAgentInstructions) {
+    const activeHarnesses = resolveActiveHarnesses({
+      optInHarnesses: parsed.optInHarnesses,
+      noClaude: parsed.noClaude,
+    });
+    if (activeHarnesses.length === 0) {
+      process.stderr.write(
+        `[init] Agent instructions: nothing to write — pass --agents / --gemini / --cursor `
+        + `to opt into additional harness files (claude-code is disabled by --no-claude).\n`,
+      );
     } else {
-      process.stderr.write(`[init] Index-maintainer daemon already installed\n`);
+      try {
+        agentInstructionsReport = injectAgentInstructions({
+          projectRoot,
+          harnesses: activeHarnesses,
+          useSymlinks: parsed.symlinkInstructionFiles,
+        });
+        const summary = Object.entries(agentInstructionsReport.harnesses)
+          .map(([k, v]) => `${k}=${v}`).join(' ');
+        const canonical = agentInstructionsReport.canonical
+          ? ` (canonical=${agentInstructionsReport.canonical})` : '';
+        process.stderr.write(`[init] Agent instructions: ${summary || '(none)'}${canonical}\n`);
+      } catch (err) {
+        process.stderr.write(`[init] Warning: Agent-instruction injection failed: ${err.message}\n`);
+      }
+      // Claude rules file is only useful when claude-code is enabled — the
+      // sole load path is the @.claude/rules/sweet-search.md import line that
+      // injectAgentInstructions writes into CLAUDE.md.
+      if (activeHarnesses.includes('claude-code')) {
+        try {
+          const status = writeClaudeRules({ projectRoot });
+          claudeRulesReport = { status };
+          process.stderr.write(`[init] Claude rules: ${status}\n`);
+        } catch (err) {
+          process.stderr.write(`[init] Warning: Could not write Claude rules: ${err.message}\n`);
+        }
+      }
+    }
+  } else if (parsed.verbose) {
+    process.stderr.write(`[init] Agent instructions: skipped (--no-agent-instructions)\n`);
+  }
+
+  // 16. UserPromptSubmit reminder hook (P2 — plan §4C / §10 step 16).
+  //     Universal `--no-claude` gate already enforced at step 10. Default-on;
+  //     `--no-prompt-reminders` opts out. The hook lives at
+  //     `.claude/hooks/sweet-search-remind-tools.mjs` with a
+  //     `hooks.UserPromptSubmit` entry in `.claude/settings.json` keyed by
+  //     filename so re-init updates rather than duplicates.
+  let promptReminderReport = null;
+  if (!parsed.noClaude) {
+    promptReminderReport = installPromptReminderHook({
+      projectRoot,
+      packageRoot: PACKAGE_ROOT,
+      skipped: parsed.skipPromptReminders,
+    });
+    if (parsed.verbose || promptReminderReport.status === 'error') {
+      process.stderr.write(`[init] Prompt reminder hook: ${promptReminderReport.status} — ${promptReminderReport.detail}\n`);
     }
-  } catch (e) {
-    process.stderr.write(`[init] Warning: Could not install index-maintainer: ${e.message}\n`);
   }
 
-  // 11. Install /sweet-index skill — always, even if .claude/ doesn't exist.
-  //     Users who haven't adopted Claude Code yet still get the skill in place
-  //     the moment they do; we treat the skill as part of the product, not a
-  //     Claude-Code-conditional add-on.
-  const skillReport = installSweetIndexSkill({
-    projectRoot,
-    packageRoot: PACKAGE_ROOT,
-  });
-  if (skillReport.status === 'installed') {
-    process.stderr.write(`[init] Installed /sweet-index skill to ${skillReport.detail}\n`);
-  } else if (skillReport.status === 'already-installed') {
-    process.stderr.write(`[init] /sweet-index skill already installed\n`);
-  } else if (skillReport.status === 'error') {
-    process.stderr.write(`[init] Warning: Could not install /sweet-index skill: ${skillReport.detail}\n`);
-  }
-
-  // 11.5. Register Claude Code SessionStart daemon-prewarm hook.
-  //       Spawns the search daemon detached in the background so the user's
-  //       first `sweet-search <query>` hits a warm daemon (~80ms) instead of
-  //       paying ~2.5s cold-start. The hook exits immediately; the daemon
-  //       loads models + indexes while the user reads Claude's first reply.
-  //       Never blocks init — any write failure collapses to a silent no-op
-  //       on next session start.
-  const prewarmHookReport = registerPrewarmSessionStartHook({
-    projectRoot,
-    packageRoot: PACKAGE_ROOT,
-    skipped: parsed.skipPrewarmHook,
-  });
-  if (parsed.verbose || prewarmHookReport.status === 'error') {
-    process.stderr.write(`[init] Prewarm hook: ${prewarmHookReport.status} — ${prewarmHookReport.detail}\n`);
+  // 17. Tool enforcement (P3 — plan §4D / §10 step 17). Opt-in via
+  //     `--enforce-tools`; universal `--no-claude` gate above. Adds
+  //     `permissions.deny: ["Grep"]` and a PreToolUse hint hook for `Read`
+  //     in `.claude/settings.json`. Strict + opinionated; off by default.
+  let toolEnforcementReport = null;
+  if (!parsed.noClaude) {
+    toolEnforcementReport = installToolEnforcement({
+      projectRoot,
+      packageRoot: PACKAGE_ROOT,
+      skipped: !parsed.enforceTools,
+    });
+    if (parsed.verbose || toolEnforcementReport.status === 'error') {
+      process.stderr.write(`[init] Tool enforcement: ${toolEnforcementReport.status} — ${toolEnforcementReport.detail}\n`);
+    }
   }
 
-  // 12. Print report
+  // 18. Print report
   printReport({
     profile,
     maxsimTier,
@@ -1348,6 +1988,10 @@ export async function runInit(args) {
     prewarmHookReport,
     skillReport,
     liChoices,
+    agentInstructionsReport,
+    claudeRulesReport,
+    promptReminderReport,
+    toolEnforcementReport,
   });
 }