sweet-search 2.5.2 → 2.5.4

package/mcp/server.js

@@ -11,6 +11,7 @@ import { z } from 'zod';
 import { existsSync, statSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { launchMaintainer } from '../core/indexing/maintainer-launcher.mjs';
 
 import {
   SearchOutputSchema,
@@ -18,16 +19,19 @@ import {
   HealthOutputSchema,
   RepoMapOutputSchema,
   VocabPrewarmOutputSchema,
-  ReadOutputSchema,
-  ReadSemanticOutputSchema,
   handleSearch,
   handleIndex,
   checkHealth,
   handleRepoMap,
   handleVocabPrewarm,
+} from './tool-handlers.js';
+import { TraceOutputSchema, handleTrace } from './trace-tool.js';
+import {
+  ReadOutputSchema,
+  ReadSemanticOutputSchema,
   handleRead,
   handleReadSemantic,
-} from './tool-handlers.js';
+} from './read-tool.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -101,9 +105,10 @@ async function getConfig() {
 const coreDir = path.join(__dirname, '..', 'core');
 
 const searchDeps = { getSearcher };
+const traceDeps = { PROJECT_ROOT };
 const indexDeps = { PROJECT_ROOT, coreDir };
 const healthDeps = { getConfig, PROJECT_ROOT };
-const repoMapDeps = { coreDir };
+const repoMapDeps = { coreDir, PROJECT_ROOT };
 const vocabDeps = { coreDir };
 
 // ---------------------------------------------------------------------------
@@ -126,7 +131,7 @@ const server = new McpServer({
 // ---------------------------------------------------------------------------
 
 server.registerTool('search', {
-  description: 'Search the codebase using hybrid semantic/lexical/structural search. Use format="agent" with a regex for ColGrep pattern search that returns self-contained code blocks — eliminates follow-up file reads.',
+  description: 'Hybrid code search (semantic + lexical + structural). USE INSTEAD OF native Grep for code-discovery tasks. Returns ranked, auto-expanded, self-contained code blocks by default (`format="agent"`) — no follow-up Read needed. Pass `regex` for ColGrep pattern search (regex anchor + semantic re-rank), `structural=true` for callers/callees/impact, or omit for hybrid auto-routing. Pass `format="benchmark"` only for retrieval-quality measurement, not agent consumption.',
   inputSchema: {
     query: z.string().min(1).max(1000).describe('Search query (1-1000 chars)'),
     k: z.number().int().min(1).max(200).default(10).describe('Number of results (1-200)'),
@@ -136,10 +141,10 @@ server.registerTool('search', {
       .describe('Force structural graph search mode (callers, callees, implementations)'),
     regex: z.string().max(4096).optional()
       .describe('Regex pattern for ColGrep pattern search (implies mode=pattern)'),
-    format: z.enum(['benchmark', 'agent', 'agent_preview', 'agent_full']).default('benchmark').optional()
-      .describe('Output format. "agent"/"agent_preview" returns bounded code blocks (4K budget). "agent_full" returns expanded code for top-3 (8K budget).'),
-    tokenBudget: z.number().int().min(500).max(16000).default(4000).optional()
-      .describe('Agent mode: total token budget for all results (default: 4000)'),
+    format: z.enum(['benchmark', 'agent', 'agent_preview', 'agent_full']).default('agent').optional()
+      .describe('Output format. Default "agent" returns ranked, self-contained code blocks for agent consumption. Use "benchmark" only for retrieval-quality measurement.'),
+    tokenBudget: z.number().int().min(500).max(16000).optional()
+      .describe('Agent mode: optional token budget override. Omit to let the tool pick.'),
   },
   outputSchema: SearchOutputSchema,
   annotations: {
@@ -150,8 +155,31 @@ server.registerTool('search', {
   },
 }, async (args) => handleSearch(args, searchDeps));
 
+server.registerTool('trace', {
+  description: 'Trace callers, callees, and transitive impact paths for one specific symbol — returns a single structural-context package adapted to the token budget. USE WHEN the question is "who calls X", "what does X depend on", or "what would break if I changed X". For general code discovery use `search` instead; for navigation around an unfamiliar repo use `repo-map` first.',
+  inputSchema: {
+    symbol: z.string().min(1).max(256)
+      .describe('Symbol/entity name to trace, e.g. processOrder or EmployeeService.processOrder'),
+    file: z.string().max(1000).optional()
+      .describe('Optional indexed file path to disambiguate duplicate symbol names'),
+    query: z.string().max(1000).optional()
+      .describe('Optional natural-language hint used only to rank structural context'),
+    maxDepth: z.number().int().min(1).max(4).default(3).optional()
+      .describe('Maximum transitive impact depth (default: 3, capped at 4)'),
+    tokenBudget: z.number().int().min(1000).max(16000).optional()
+      .describe('Optional token budget. Omit for adaptive 4k/8k/12k selection.'),
+  },
+  outputSchema: TraceOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+}, async (args) => handleTrace(args, traceDeps));
+
 server.registerTool('index', {
-  description: 'Index or re-index the codebase',
+  description: 'Index or re-index the codebase. USE BEFORE first search if the project has not been indexed yet, or after large source changes (`mode="full"`). The Claude Code SessionStart hook installed by `sweet-search init` keeps the incremental index fresh during normal sessions, so manual re-indexing is rarely needed.',
   inputSchema: {
     mode: z.enum(['incremental', 'full']).default('incremental')
       .describe('Indexing mode'),
@@ -166,7 +194,7 @@ server.registerTool('index', {
 }, async (args) => handleIndex(args, indexDeps));
 
 server.registerTool('health', {
-  description: 'Check health status of all search subsystems',
+  description: 'Check health of every sweet-search subsystem (index, embedding model, late-interaction reranker, structural graph, daemon). USE WHEN searches return empty unexpectedly, results look stale, or latency is unusual — diagnoses missing index, model load failures, daemon issues. Read-only, fast.',
   outputSchema: HealthOutputSchema,
   annotations: {
     readOnlyHint: true,
@@ -189,7 +217,7 @@ server.registerTool('health', {
 });
 
 server.registerTool('repo-map', {
-  description: 'Generate a PageRank-scored repository map showing the most important symbols in the codebase, fitted to a token budget. Useful for giving LLMs a compressed structural overview.',
+  description: 'Compressed structural overview of the codebase as a PageRank-scored symbol list, fitted to a token budget. USE FIRST when exploring an unfamiliar repo to orient yourself, or to brief a delegated agent before handing off a task. Not for targeted lookups — use `search` for that. Pass `focusFiles` / `focusEntities` to bias the map toward the area you care about.',
   inputSchema: {
     tokenBudget: z.number().int().min(100).max(100000).default(1024)
       .describe('Maximum token budget for the output (default: 1024)'),
@@ -208,7 +236,7 @@ server.registerTool('repo-map', {
 }, async (args) => handleRepoMap(args, repoMapDeps));
 
 server.registerTool('vocab-prewarm', {
-  description: 'Mine the codebase for search vocabulary and warm all search modes (lexical, semantic, hybrid) with project-specific terms',
+  description: 'Pre-warm sweet-search caches by mining the codebase for project-specific vocabulary across lexical / semantic / hybrid modes. USE ONCE after a fresh index to make the first batch of searches faster; generally not needed for one-off queries because the daemon-prewarm hook handles cold-start warmup automatically.',
   inputSchema: {
     depth: z.enum(['light', 'medium', 'deep']).default('medium').describe('Mining depth'),
     modes: z.array(z.enum(['lexical', 'semantic', 'hybrid'])).default(['lexical', 'semantic', 'hybrid']).describe('Search modes to warm'),
@@ -229,7 +257,7 @@ server.registerTool('vocab-prewarm', {
 }, async (args) => handleVocabPrewarm(args, vocabDeps));
 
 server.registerTool('read', {
-  description: 'Read one or more files for exact code understanding. Replaces the default Read tool for most code-reading workflows. Uses the filesystem as ground truth, supports line ranges and batching, and attaches symbol-aware chunk metadata when the file is indexed.',
+  description: 'Read 1-20 files (with optional line ranges) for exact code understanding. USE INSTEAD OF the native Read tool for code-discovery reads — batches multiple files in one call, attaches symbol-aware chunk metadata when the file is indexed, and returns the exact bytes from disk. Native Read remains fine for files you are about to Edit (Edit needs a prior Read of that exact file).',
   inputSchema: {
     files: z.array(z.object({
       path: z.string().describe('File path relative to project root (or absolute)'),
@@ -244,7 +272,7 @@ server.registerTool('read', {
 }, async (args) => handleRead(args, { PROJECT_ROOT }));
 
 server.registerTool('read-semantic', {
-  description: 'Read only the spans of a file relevant to a query. Selects spans via hybrid retrieval (lexical + symbol + ColBERT-style late-interaction MaxSim) with RRF fusion and LI re-rank, then re-reads exact lines from disk. Returns 1-N small spans instead of the full file. Falls back to a plain read if the file is not indexed.',
+  description: 'Read only the spans of a file relevant to a question. USE WHEN you know the file but the relevant span is unclear — selects spans via hybrid retrieval (lexical + symbol + ColBERT MaxSim, RRF-fused and LI-reranked), then re-reads exact lines from disk. Returns 1-N small spans instead of the full file. Avoid running this on multiple files unless the task is explicitly multi-file — call `search` with the question instead. Falls back to a plain read when the file is not indexed.',
   inputSchema: {
     file: z.string().describe('File path (project-relative or absolute)'),
     query: z.string().min(1).max(500).describe('What you want to understand about this file'),
@@ -368,6 +396,18 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(`[sweet-search-mcp] Server started (project: ${PROJECT_ROOT})`);
+
+  // MCP is opt-in (only runs when the user configures it). When it IS running,
+  // reuse the SAME shared launcher so the default-on maintainer starts here too
+  // — but MCP is never REQUIRED for incremental indexing (the warm search-server
+  // path is the durable guarantee). stdout is the MCP protocol channel, so the
+  // launcher's stdout-clean contract is load-bearing; never let it break MCP.
+  try {
+    const result = launchMaintainer({ cwd: PROJECT_ROOT });
+    if (result.spawned) console.error(`[sweet-search-mcp] incremental maintainer started (pid ${result.pid})`);
+  } catch (err) {
+    console.error(`[sweet-search-mcp] maintainer launch (non-fatal): ${err?.message || err}`);
+  }
 }
 
 main().catch((err) => {

package/mcp/tool-handlers.js

@@ -88,65 +88,6 @@ export const VocabPrewarmOutputSchema = z.object({
   dryRun: z.boolean().optional(),
 });
 
-const ReadFileResultSchema = z.object({
-  file: z.string(),
-  absolutePath: z.string().optional(),
-  ok: z.boolean(),
-  exact: z.boolean().optional(),
-  indexed: z.boolean().optional(),
-  language: z.string().nullable().optional(),
-  totalLines: z.number().int().optional(),
-  bytes: z.number().int().optional(),
-  mtimeMs: z.number().optional(),
-  range: z.object({
-    startLine: z.number().int(),
-    endLine: z.number().int(),
-  }).nullable().optional(),
-  text: z.string().optional(),
-  chunks: z.array(z.object({
-    id: z.string(),
-    symbol: z.string().nullable().optional(),
-    type: z.string().nullable().optional(),
-    startLine: z.number().int().nullable().optional(),
-    endLine: z.number().int().nullable().optional(),
-    signature: z.string().nullable().optional(),
-  })).optional(),
-  error: z.string().optional(),
-  timings: z.object({ totalMs: z.number() }).optional(),
-});
-
-export const ReadOutputSchema = z.object({
-  files: z.array(ReadFileResultSchema),
-  totalMs: z.number(),
-});
-
-const ReadSemanticSpanSchema = z.object({
-  startLine: z.number().int(),
-  endLine: z.number().int(),
-  score: z.number(),
-  symbols: z.array(z.string()).optional(),
-  types: z.array(z.string()).optional(),
-  chunkIds: z.array(z.string()).optional(),
-  text: z.string(),
-  truncated: z.boolean().optional(),
-});
-
-export const ReadSemanticOutputSchema = z.object({
-  file: z.string(),
-  query: z.string(),
-  ok: z.boolean(),
-  indexed: z.boolean(),
-  fellBack: z.boolean(),
-  reason: z.string().optional(),
-  language: z.string().nullable().optional(),
-  totalLines: z.number().int().optional(),
-  spans: z.array(ReadSemanticSpanSchema),
-  charsReturned: z.number().int().optional(),
-  approxTokensReturned: z.number().int().optional(),
-  signals: z.record(z.string(), z.any()).optional(),
-  timings: z.record(z.string(), z.number()).optional(),
-});
-
 // ---------------------------------------------------------------------------
 // Internal state for health DB cache (module-scoped, not exported)
 // ---------------------------------------------------------------------------
@@ -419,19 +360,25 @@ export async function checkHealth({ getConfig, PROJECT_ROOT }) {
 
 /**
  * @param {{ tokenBudget: number, focusFiles?: string[], focusEntities?: string[] }} args
- * @param {{ coreDir: string }} deps
+ * @param {{ coreDir: string, PROJECT_ROOT?: string }} deps
  */
-export async function handleRepoMap({ tokenBudget, focusFiles, focusEntities }, { coreDir }) {
+export async function handleRepoMap({ tokenBudget, focusFiles, focusEntities }, { coreDir, PROJECT_ROOT }) {
   try {
-    const { generateRepoMap } = await import(
-      path.join(coreDir, 'graph', 'index.js')
-    );
-
-    const result = generateRepoMap({
+    const [{ generateRepoMap }, { withPinnedRead }] = await Promise.all([
+      import(path.join(coreDir, 'graph', 'index.js')),
+      import(path.join(coreDir, 'search', 'search-reader-pin.js')),
+    ]);
+
+    const result = await withPinnedRead({
+      projectRoot: PROJECT_ROOT,
+      meta: { tool: 'repo-map' },
+    }, (manifestEpoch, pin) => generateRepoMap({
       tokenBudget,
       focusFiles,
       focusEntities,
-    });
+      manifest: pin?.manifest,
+      manifestEpoch: manifestEpoch ?? undefined,
+    }));
 
     const summary = `Repo map: ${result.entityCount}/${result.totalEntities} entities across ${result.fileCount} files (${result.pageRankTimeMs}ms)`;
     const text = `${summary}\n\n${result.text}`;
@@ -528,60 +475,3 @@ export async function handleVocabPrewarm({ depth, modes, top, incremental, dryRu
     };
   }
 }
-
-// ---------------------------------------------------------------------------
-// read — filesystem-grounded reader
-// ---------------------------------------------------------------------------
-
-/**
- * @param {{ files: Array<{path: string, startLine?: number, endLine?: number}>, includeMetadata?: boolean }} args
- * @param {{ PROJECT_ROOT: string }} deps
- */
-export async function handleRead(args, deps) {
-  try {
-    const { readFiles, formatReadResults } = await import('../core/search/index.js');
-    const result = await readFiles(args.files || [], {
-      projectRoot: deps.PROJECT_ROOT,
-      includeMetadata: args.includeMetadata !== false,
-    });
-    return {
-      content: [{ type: 'text', text: formatReadResults(result, 'agent') }],
-      structuredContent: result,
-    };
-  } catch (err) {
-    const msg = (err.message || 'read failed').split('\n')[0];
-    return { content: [{ type: 'text', text: `read error: ${msg}` }], isError: true };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// read-semantic — hybrid span selection + filesystem-grounded re-read
-// ---------------------------------------------------------------------------
-
-/**
- * @param {{ file: string, query: string, topK?: number, threshold?: number, contextLines?: number, maxChars?: number, maxTokens?: number, verbose?: boolean }} args
- * @param {{ PROJECT_ROOT: string }} deps
- */
-export async function handleReadSemantic(args, deps) {
-  try {
-    const { readSemantic, formatReadSemanticResult } = await import('../core/search/index.js');
-    const result = await readSemantic({
-      path: args.file,
-      query: args.query,
-      topK: args.topK,
-      threshold: args.threshold,
-      contextLines: args.contextLines,
-      maxChars: args.maxChars,
-      maxTokens: args.maxTokens,
-      projectRoot: deps.PROJECT_ROOT,
-      verbose: args.verbose,
-    });
-    return {
-      content: [{ type: 'text', text: formatReadSemanticResult(result, 'agent') }],
-      structuredContent: result,
-    };
-  } catch (err) {
-    const msg = (err.message || 'read-semantic failed').split('\n')[0];
-    return { content: [{ type: 'text', text: `read-semantic error: ${msg}` }], isError: true };
-  }
-}

package/mcp/trace-tool.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+const TraceEntitySchema = z.object({
+  id: z.union([z.string(), z.number()]).optional(),
+  name: z.string(),
+  type: z.string(),
+  filePath: z.string().nullable().optional(),
+  file: z.string().nullable().optional(),
+  startLine: z.number().int().nullable().optional(),
+  endLine: z.number().int().nullable().optional(),
+  contextLine: z.number().int().nullable().optional(),
+  relationship: z.string().nullable().optional(),
+  depth: z.number().int().optional(),
+  importance: z.number().optional(),
+  presentation: z.enum(['full', 'preview', 'summary']).optional(),
+  summary: z.string().optional(),
+  code: z.string().nullable().optional(),
+  codeTokens: z.number().int().optional(),
+});
+
+export const TraceOutputSchema = z.object({
+  format: z.literal('structural_context'),
+  tool: z.literal('trace'),
+  symbol: z.string(),
+  target: z.any().nullable(),
+  disambiguation: z.array(z.any()),
+  budgetTier: z.string(),
+  budgetReason: z.string(),
+  tokenBudget: z.number().int(),
+  tokensUsed: z.number().int(),
+  maxDepth: z.number().int(),
+  answerCues: z.object({
+    targetTerms: z.array(z.string()),
+    keySymbols: z.array(z.string()).optional(),
+    branchTerms: z.array(z.string()).optional(),
+    branchSnippets: z.array(z.string()).optional(),
+    citationFocus: z.string().nullable().optional(),
+    relatedDefinitions: z.array(z.string()).optional(),
+    topCallers: z.array(z.string()),
+    topCallees: z.array(z.string()),
+    criticalPaths: z.array(z.string()),
+  }).optional(),
+  stats: z.record(z.string(), z.any()),
+  sections: z.object({
+    callers: z.object({ total: z.number().int(), shown: z.number().int(), items: z.array(TraceEntitySchema) }),
+    callees: z.object({ total: z.number().int(), shown: z.number().int(), items: z.array(TraceEntitySchema) }),
+    impact: z.object({ total: z.number().int(), shown: z.number().int(), paths: z.array(z.any()) }),
+  }),
+});
+
+/**
+ * @param {{ symbol: string, file?: string, query?: string, tokenBudget?: number, maxDepth?: number }} args
+ * @param {{ PROJECT_ROOT: string }} deps
+ */
+export async function handleTrace({ symbol, file, query, tokenBudget, maxDepth }, { PROJECT_ROOT }) {
+  try {
+    const { traceSymbol, formatStructuralContext } = await import('../core/search/search-trace.js');
+    const result = traceSymbol(symbol, {
+      projectRoot: PROJECT_ROOT,
+      filePath: file,
+      queryHint: query,
+      tokenBudget,
+      maxDepth,
+    });
+    return {
+      content: [{ type: 'text', text: formatStructuralContext(result) }],
+      structuredContent: result,
+      isError: !result.target,
+    };
+  } catch (err) {
+    const safeMessage = (err.message || 'Trace failed')
+      .split('\n')[0]
+      .replace(/\/[^\s:]+/g, '<path>')
+      .replace(/[A-Z]:\\[^\s:]+/gi, '<path>')
+      .replace(/\\\\[^\s:]+/g, '<path>');
+    return {
+      content: [{ type: 'text', text: `Trace error: ${safeMessage}` }],
+      isError: true,
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweet-search",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
   "type": "module",
   "main": "core/search/sweet-search.js",
@@ -40,6 +40,7 @@
   "files": [
     "core/*.js",
     "core/infrastructure/",
+    "core/incremental-indexing/",
     "core/embedding/",
     "core/indexing/",
     "core/search/",
@@ -55,9 +56,22 @@
     "scripts/uninstall.js",
     "scripts/verify-runtime.js",
     "scripts/smoke-test.js",
+    "scripts/inject-agent-instructions.js",
+    "scripts/write-claude-rules.js",
+    "scripts/install-prompt-reminders.js",
+    "scripts/install-tool-enforcement.js",
+    "scripts/hooks/",
     "core/training/query-router/features/",
     "core/training/query-router/output/v45_router_d4.js",
     "core/training/query-router/output/v46_router_d4.js",
+    "core/prompt-optimization/data/p7-final/",
+    "eval/agent-read-workflows/bin/ss-search",
+    "eval/agent-read-workflows/bin/ss-find",
+    "eval/agent-read-workflows/bin/ss-grep",
+    "eval/agent-read-workflows/bin/ss-semantic",
+    "eval/agent-read-workflows/bin/ss-trace",
+    "eval/agent-read-workflows/bin/ss-read",
+    "eval/agent-read-workflows/bin/_ss-helpers.mjs",
     "crates/wasm-router/pkg/",
     "LICENSE",
     "NOTICE"
@@ -89,8 +103,6 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:bench": "vitest bench",
-    "eval": "node evaluation/run-evaluation.js",
-    "eval:by-lang": "node evaluation/run-evaluation.js --by-language",
     "eval:bench": "node eval/run_all.js",
     "eval:bench:check": "node eval/run_all.js --regression-check",
     "eval:bench:baseline": "node eval/run_all.js --save-baseline",
@@ -101,7 +113,9 @@
     "eval:multirepo:test": "node eval/scripts/multirepo-bench.js --split=test",
     "bench:read-workflows": "node eval/read-workflows/run-bench.js",
     "bench:agent-read-workflows": "node eval/agent-read-workflows/run-bench.js",
+    "bench:structural-context": "node eval/structural-context/run-bench.js",
     "eval:fetch-repos": "node eval/scripts/fetch-benchmark-repos.js",
+    "eval:prompt": "node scripts/eval-prompt-evolution.mjs",
     "features": "node core/training/query-router/features/extractor.js",
     "features:benchmark": "node core/training/query-router/features/extractor.js --benchmark",
     "features:names": "node core/training/query-router/features/extractor.js --names",
@@ -119,9 +133,11 @@
   "dependencies": {
     "@babel/helper-validator-identifier": "^7.28.5",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@node-rs/xxhash": "^1.7.6",
     "better-sqlite3": "^11.7.0",
     "fast-glob": "^3.3.3",
     "franc-min": "^6.2.0",
+    "minimatch": "^10.1.1",
     "onnxruntime-node": "^1.24.3",
     "p-limit": "^6.2.0",
     "sharp": "^0.34.5",
@@ -136,18 +152,17 @@
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^9.39.4",
     "fast-check": "^4.5.3",
-    "minimatch": "^10.1.1",
     "p-map": "^7.0.4",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
   },
   "optionalDependencies": {
-    "@sweet-search/native-darwin-arm64": "2.5.2",
-    "@sweet-search/native-darwin-x64": "2.5.2",
-    "@sweet-search/native-linux-arm64-gnu": "2.5.2",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.2",
-    "@sweet-search/native-linux-x64-gnu": "2.5.2",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.2"
+    "@sweet-search/native-darwin-arm64": "2.5.4",
+    "@sweet-search/native-darwin-x64": "2.5.4",
+    "@sweet-search/native-linux-arm64-gnu": "2.5.4",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.4",
+    "@sweet-search/native-linux-x64-gnu": "2.5.4",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.4"
   },
   "engines": {
     "node": ">=18.0.0"

package/scripts/hooks/intercept-read.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * sweet-search PreToolUse hook for `Read`.
+ *
+ * Plan reference: §4D. Hints — never blocks. Edit workflows legitimately
+ * require `Read` before `Edit`, so a hard deny would break tooling. The
+ * hint nudges the agent toward `ss-read` (exact range) or `ss-semantic`
+ * (when the relevant span is unclear) for code-understanding reads.
+ *
+ * Per Claude Code hook contract for PreToolUse:
+ *   - To surface text into the model's context (so the agent sees the hint
+ *     and may adjust): stdout JSON with hookSpecificOutput.additionalContext.
+ *   - Plain stderr reaches the user only — NOT the model. (We did this in
+ *     the first cut and the hint never landed where it mattered.)
+ *   - Exit 0 + permissionDecision='allow' → tool runs AND context is
+ *     injected. Exit 2 would deny.
+ *
+ * Reference: https://code.claude.com/docs/en/hooks.md (PreToolUse output).
+ *
+ * The hint is universal (doesn't depend on which file is being Read), so
+ * we drain stdin without parsing it. Always exits 0 — the Read continues.
+ */
+
+const HINT = (
+  '[sweet-search] Tip: prefer `ss-read <file> <start> <end>` for exact ranges, '
+  + 'or `ss-semantic <file> "<question>" --max-tokens 800` when the relevant '
+  + 'span is unclear. Native `Read` is best for files you already know precisely '
+  + '(e.g. before `Edit`). See AGENTS.md / CLAUDE.md for the full tool-routing tree.'
+);
+
+function emitDecision() {
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      additionalContext: HINT,
+    },
+  };
+  process.stdout.write(JSON.stringify(payload));
+  process.exit(0);
+}
+
+// Claude Code passes the tool invocation as JSON on stdin. We don't parse
+// it because the hint is universal. Drain to keep the pipe clean, then
+// emit the decision.
+let _drained = '';
+process.stdin.on('data', (c) => { _drained += c; });
+process.stdin.on('end', emitDecision);
+process.stdin.on('error', emitDecision);
+
+// Edge case: no stdin attached (running the script standalone for debug).
+// `isTTY === undefined` on a piped stdin; truthy when stdin is the terminal.
+if (process.stdin.isTTY) {
+  emitDecision();
+}

package/scripts/hooks/remind-tools.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * sweet-search UserPromptSubmit reminder hook.
+ *
+ * Claude Code surfaces this hook's stdout as additional context on every
+ * user prompt. The reminder keeps sweet-search tool selection fresh in
+ * the agent's working memory — the largest measured failure mode (May
+ * 2026) is the agent drifting back to native `Grep` / `Read` even after
+ * sweet-search has provided a `sufficient=YES` pack.
+ *
+ * Plan reference: §4C. Token cost is intentionally minimal because this
+ * fires every prompt; the wins come from avoided re-search loops, not
+ * from longer guidance.
+ *
+ * Installed by `sweet-search init` into `.claude/hooks/sweet-search-remind-tools.mjs`
+ * with a `.claude/settings.json` `hooks.UserPromptSubmit` entry that
+ * sweet-search owns by filename match. `sweet-search uninstall` removes
+ * both the file and the settings entry.
+ */
+
+// Tool surface mirrors the shipped M++ policy (the ss-* tools). Kept terse —
+// the full decision tree lives in CLAUDE.md/AGENTS.md; this is just a nudge to
+// stop the agent drifting back to raw grep/read between prompts.
+const REMINDER = [
+  '<sweet-search-reminder>',
+  'Use the index-backed ss-* tools for code search/navigation, not raw grep/find/cat:',
+  '- Exact symbol/literal/error string:  ss-grep "<regex>" -k 5   (trust the top hit)',
+  '- Known symbol, NL underperforms:     ss-find "<query>" --regex "\\b<symbol>\\b" -k 5',
+  '- Concept/behavior (no exact symbol): ss-search "<query>"',
+  '- Callers/callees/impact of a symbol: ss-trace <symbol>',
+  '- Known file, unclear span:           ss-semantic <file> "<query>"',
+  '- Known file + line range:            ss-read <file> <start> <end>',
+  'STOP the instant your evidence answers the query — one confirmed file+symbol is enough;',
+  'a second call costs more than it saves. Multi-file flow questions get one follow-up.',
+  '</sweet-search-reminder>',
+  '',
+].join('\n');
+
+process.stdout.write(REMINDER);
+process.exit(0);