sweet-search 2.6.17 → 2.7.0

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -18,7 +18,24 @@ import {
   buildGrepPattern, stripInertFlags, normalizeArgs, extractPositional,
   parseLineRange, looksLikeOption, renderSufficiency,
 } from './_ss-argparse.mjs';
-import { renderGrepBody } from '../../../core/search/grep-output-shaping.js';
+import {
+  reallocateGrepTailForManifest,
+  renderGrepBody,
+} from '../../../core/search/grep-output-shaping.js';
+import { formatRouteMetadata } from '../../../core/search/search-format.js';
+import { renderRegexDialectHint } from '../../../core/search/regex-dialect.js';
+import {
+  applyReadOmissionDecisions,
+  collectAgentShownSpans,
+  collectReadShownSpans,
+  collectSemanticShownSpans,
+  exactRereadOmissionEnabled,
+  renderReadOmission,
+  renderShownFullTrailer,
+  resolveAgentSessionId,
+  shownSpanTrailerEnabled,
+} from '../../../core/search/agent-span-ledger.js';
+import { sendAgentSpanOperation } from '../../../core/search/agent-span-client.js';
 
 // Diagnostic-log isolation (agent-facing tools). The Sweet Search engine emits
 // model/index load banners via console.log → stdout ("LateInteraction: Loaded…",
@@ -54,6 +71,29 @@ if (!existsSync(path.join(PROJECT_ROOT, '.sweet-search', 'codebase.db'))) {
 }
 process.env.SWEET_SEARCH_PROJECT_ROOT = PROJECT_ROOT;
 
+const AGENT_SESSION_ID = resolveAgentSessionId();
+const EXACT_REREAD_OMISSION = exactRereadOmissionEnabled();
+const SHOWN_SPAN_TRAILER = shownSpanTrailerEnabled();
+const SPAN_POLICY_ENABLED = EXACT_REREAD_OMISSION || SHOWN_SPAN_TRAILER;
+
+async function recordAgentToolCall({
+  operation = 'observe',
+  spans = [],
+  force = false,
+  query,
+  regex,
+} = {}) {
+  if (!EXACT_REREAD_OMISSION || !AGENT_SESSION_ID) return null;
+  return sendAgentSpanOperation({
+    operation,
+    spans,
+    force,
+    sessionId: AGENT_SESSION_ID,
+    query,
+    regex,
+  });
+}
+
 const subcommand = process.argv[2];
 const rest = process.argv.slice(3);
 
@@ -114,6 +154,26 @@ async function ensureWarmServerReady({ timeoutMs = 60000, intervalMs = 500 } = {
   return false;
 }
 
+async function queryWarmSearch(query, options) {
+  if (!await ensureWarmServerReady({ timeoutMs: 5000 })) {
+    throw new Error('warm server is not ready');
+  }
+  const { queryServer } = await import(path.join(REPO_ROOT, 'core/search/search-server.js'));
+  const response = await queryServer(query, {
+    ...options,
+    projectRoot: PROJECT_ROOT,
+    trackAgentSpans: false,
+    _isAgentFormat: options._isAgentFormat ?? true,
+  });
+  if (response?.error) throw new Error(response.error);
+  return response;
+}
+
+function writeRegexDialectHint(stats) {
+  const note = renderRegexDialectHint(stats?.regexDialectHint);
+  if (note) process.stdout.write(`${note}\n`);
+}
+
 // --- subcommands ----------------------------------------------------------
 
 const GREP_USAGE = 'Usage: ss-grep <regex> [-i|--ignore-case] [-w|--word-regexp] [-F|--fixed-strings] [--in <file>] [-k N]';
@@ -132,14 +192,27 @@ async function cmdGrep(rawArgs) {
     process.stderr.write(GREP_USAGE + '\n');
     process.exit(2);
   }
-  const s = await getSweetSearch();
-
   if (inFile) {
     // Single-file scope: flat output, depth up to k within that file.
-    const result = await s.bareGrep(regex, null, {
-      regex, maxMatches: k, contextLines: 0, fileFilter: inFile,
-    });
+    let result;
+    try {
+      result = await queryWarmSearch(regex, {
+        mode: 'grep', regex, maxMatches: k, contextLines: 0,
+        fileFilter: inFile, expand: false, rerank: false, useLateInteraction: false,
+        _isAgentFormat: !fixedString,
+      });
+    } catch {
+      const s = await getSweetSearch();
+      result = await s.bareGrep(regex, null, {
+        regex, maxMatches: k, contextLines: 0, fileFilter: inFile,
+        _isAgentFormat: !fixedString,
+      });
+    }
     const total = result.stats?.totalMatches ?? result.results.length;
+    await recordAgentToolCall({
+      query: fixedString ? undefined : regex,
+      regex: fixedString ? undefined : regex,
+    });
     process.stdout.write(`# ss-grep: ${total} total match(es) for /${regex}/ (scope: --in ${inFile})\n`);
     result.results.forEach((r, i) => {
       const text = (r.matchText || '').replace(/\s+/g, ' ').trim().slice(0, 140);
@@ -148,6 +221,7 @@ async function cmdGrep(rawArgs) {
       process.stdout.write(`${r.file}:${r.line}: ${text}${marker}\n`);
     });
     if (result.results.length === 0) process.stdout.write('(no matches)\n');
+    writeRegexDialectHint(result.stats);
     process.exit(0);
   }
 
@@ -157,14 +231,31 @@ async function cmdGrep(rawArgs) {
   // flooded file can never hide every other matching file (the gradethis-161
   // failure). Rendering stays grouped per file; truncation is marked inline
   // and drillable via --in.
-  const result = await s.bareGrep(regex, null, {
-    regex, maxMatches: 0, contextLines: 0,
-    perFileCap: Math.min(k, 100), maxFiles: k,
-  });
+  let result;
+  try {
+    result = await queryWarmSearch(regex, {
+      mode: 'grep', regex, maxMatches: 0, contextLines: 0,
+      perFileCap: Math.min(k, 100), maxFiles: k,
+      expand: false, rerank: false, useLateInteraction: false,
+      _isAgentFormat: !fixedString,
+    });
+  } catch {
+    const s = await getSweetSearch();
+    result = await s.bareGrep(regex, null, {
+      regex, maxMatches: 0, contextLines: 0,
+      perFileCap: Math.min(k, 100), maxFiles: k,
+      _isAgentFormat: !fixedString,
+    });
+  }
   const total = result.stats?.totalMatches ?? result.results.length;
   const fileSummary = result.fileSummary
     || { files: [], hiddenFileCount: 0, hiddenMatchCount: 0, hiddenSample: [] };
   const body = renderGrepBody(result.results, fileSummary, k);
+  const completed = reallocateGrepTailForManifest(body.lines, result.familyManifest);
+  await recordAgentToolCall({
+    query: fixedString ? undefined : regex,
+    regex: fixedString ? undefined : regex,
+  });
 
   // Sibling-surface signal (E6, 2026-07-08 trace audit): when a symbol/stem
   // matches in more than one file, say so unconditionally in the header —
@@ -176,9 +267,11 @@ async function cmdGrep(rawArgs) {
     process.stdout.write(`# (+N more in this file)=truncated — ` +
       `see the rest: ss-grep "<regex>" --in <file>\n`);
   }
-  for (const line of body.lines) process.stdout.write(line + '\n');
+  for (const line of completed.lines) process.stdout.write(line + '\n');
+  if (completed.familyManifest) process.stdout.write(`${completed.familyManifest.rendered}\n`);
   if (body.hiddenLine) process.stdout.write(body.hiddenLine + '\n');
   if (body.shownMatches === 0) process.stdout.write('(no matches)\n');
+  writeRegexDialectHint(result.stats);
   process.exit(0);
 }
 
@@ -210,16 +303,33 @@ async function cmdFind(rawArgs) {
   const envFindBudget = Number(process.env.SS_SMOKE_FIND_BUDGET || '') || null;
   // Pattern flags apply to the regex candidate generator; the NL query is untouched.
   const effectiveRegex = buildGrepPattern(regex || '', { ignoreCase, wordBound, fixedString });
-  const s = await getSweetSearch();
-  if (!s.hasLateInteractionIndex) {
-    process.stderr.write(`[ss-find] no late-interaction index — falling back to ss-grep\n`);
-    return cmdGrep([effectiveRegex || query, '-k', String(k)]);
+  let response;
+  try {
+    response = await queryWarmSearch(query, {
+      mode: 'pattern', regex: effectiveRegex || `\\b\\w+\\b`, topK: k, format,
+      _isAgentFormat: !fixedString,
+      ...(envFindBudget ? { tokenBudget: envFindBudget } : {}),
+    });
+  } catch {
+    const s = await getSweetSearch();
+    if (!s.hasLateInteractionIndex) {
+      process.stderr.write(`[ss-find] no late-interaction index — falling back to ss-grep\n`);
+      return cmdGrep([effectiveRegex || query, '-k', String(k)]);
+    }
+    response = await s.patternSearch(query, null, {
+      regex: effectiveRegex || `\\b\\w+\\b`,
+      k,
+      format,
+      _isAgentFormat: !fixedString,
+      ...(envFindBudget ? { tokenBudget: envFindBudget } : {}),
+    });
   }
-  const response = await s.patternSearch(query, null, {
-    regex: effectiveRegex || `\\b\\w+\\b`,
-    k,
-    format,
-    ...(envFindBudget ? { tokenBudget: envFindBudget } : {}),
+  const shownSpans = SPAN_POLICY_ENABLED
+    ? collectAgentShownSpans(response.results, { projectRoot: PROJECT_ROOT }) : [];
+  await recordAgentToolCall({
+    spans: shownSpans,
+    query: fixedString ? undefined : query,
+    regex: fixedString ? undefined : effectiveRegex,
   });
 
   // Header (visible to agent)
@@ -252,12 +362,22 @@ async function cmdFind(rawArgs) {
     if (r.sameFile && r.sameFile.rendered) {
       process.stdout.write(`${r.sameFile.rendered}\n`);
     }
+    if (r.continuation?.rendered) {
+      process.stdout.write(`${r.continuation.rendered}\n`);
+      if (r.continuation.kind === 'symbol' && r.continuation.code) {
+        process.stdout.write(`\`\`\`\n${r.continuation.code}\n\`\`\`\n`);
+      }
+    }
+    if (r.familyManifest?.rendered) process.stdout.write(`${r.familyManifest.rendered}\n`);
   }
   if (!response.results || response.results.length === 0) process.stdout.write('(no matches)\n');
+  writeRegexDialectHint(response.stats);
+  const shownTrailer = SHOWN_SPAN_TRAILER ? renderShownFullTrailer(shownSpans) : '';
+  if (shownTrailer) process.stdout.write(`\n${shownTrailer}\n`);
   process.exit(0);
 }
 
-// ss-read takes NO flags — only positional <file> [start] [end] (or a single
+// ss-read takes one recovery flag plus positional <file> [start] [end] (or a single
 // "start-end" / "start:end" / "start,end" range token). Unlike ss-grep, a stray
 // flag here can never silently corrupt the result: the line slots are validated
 // as numbers, so a misuse is already a loud error. These hints exist only to
@@ -268,8 +388,10 @@ const READ_USAGE =
   '       ss-read <file> <start>    # ONE line\n' +
   '       ss-read <file> <start> <end>\n' +
   '       ss-read <file> 10-20      # range (also 10:20, 10,20)\n' +
-  'Note: ss-read has no flags (no -n/--limit/-r); line selection is positional.';
-async function cmdRead(args) {
+  'Option: --force shows content again after an unchanged-content omission.';
+async function cmdRead(rawArgs) {
+  const args = [...rawArgs];
+  const force = parseBoolFlag(args, ['--force']);
   const file = args[0];
   if (!file) {
     process.stderr.write(READ_USAGE + '\n');
@@ -307,19 +429,59 @@ async function cmdRead(args) {
       }
     }
   }
+  // L4a (2026-07-09) — default read window. An unbounded whole-file read (no range
+  // given) delivers the ENTIRE file, which then sits RESIDENT in the agent's context
+  // and is re-sent every subsequent turn. P1 measured this read-mass resident tax at
+  // ~$11/200 (whole-file/large reads are the tail: p90=180, max=900 lines). So when
+  // the agent gives NO range, cap the default to READ_WINDOW lines and let the
+  // existing "what remains" trailer advertise the exact continue command — the agent
+  // widens on demand instead of paying for the whole file up front. Only the no-range
+  // case is capped: an EXPLICIT range is the agent's deliberate choice and capping it
+  // would cause widen-thrash (the RETUNE hazard). GCSN-neutral by construction (reads
+  // are never ranked). Gated for the standing ON-vs-OFF A/B: SS_NO_READ_WINDOW=1 → OFF
+  // (legacy whole-file); SS_READ_WINDOW=<n> retunes the tier. Prod/human ss-read is a
+  // separate wrapper and is untouched (byte-identical).
+  // PARKED default-OFF (2026-07-09 smoke): the mechanism works (−39% delivered read
+  // tokens vs off) and is accuracy-safe (no resolved→unresolved flips), but the ~$11/200
+  // pool is too small to show a net idealCost win at n=2 and one read-thrash instance
+  // appeared at window=150. Opt-in via SS_READ_WINDOW=<n> pending a larger-n confirmation.
+  const READ_WINDOW = Number(process.env.SS_READ_WINDOW) || 0;
+  const cappedDefault = (start === null && end === null && READ_WINDOW > 0);
+  if (cappedDefault) { start = 1; end = READ_WINDOW; }
+
   const { readFile, renderUnreadBelow } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
   const r = await readFile({ path: file, projectRoot: PROJECT_ROOT, startLine: start ?? undefined, endLine: end ?? undefined });
   if (!r.ok) {
     process.stderr.write(`[ss-read] error: ${r.error}\n`);
     process.exit(1);
   }
-  const range = r.range ? ` (lines ${r.range.startLine}-${r.range.endLine} of ${r.totalLines})` : ` (${r.totalLines} lines)`;
+  const readBatch = { files: [r], totalMs: r.timings?.totalMs ?? 0 };
+  const shownSpans = EXACT_REREAD_OMISSION
+    ? collectReadShownSpans(readBatch, { projectRoot: PROJECT_ROOT }) : [];
+  const receiptResponse = await recordAgentToolCall({
+    operation: 'read',
+    spans: shownSpans,
+    force,
+  });
+  if (receiptResponse?.ok && Array.isArray(receiptResponse.decisions)) {
+    applyReadOmissionDecisions(readBatch, receiptResponse.decisions);
+  }
+  // If the window happened to cover the whole file (file ≤ READ_WINDOW, clamped by
+  // readFile), present it EXACTLY like an uncapped whole-file read — no synthetic
+  // range, no continue trailer — so small-file reads stay byte-identical to legacy.
+  const coveredWholeFile = (start === null && end === null) || (cappedDefault && r.range && r.range.endLine >= r.totalLines);
+  const range = (r.range && !coveredWholeFile) ? ` (lines ${r.range.startLine}-${r.range.endLine} of ${r.totalLines})` : ` (${r.totalLines} lines)`;
   const fence = r.language ? '```' + r.language : '```';
   // "What remains" trailer: on a range read that stops before EOF, one final
   // line names the symbols in the unread remainder + the exact continue
   // command (last line for recency — the actionable form of truncation).
-  const remainder = renderUnreadBelow(r, { command: 'ss-read' });
-  process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`${remainder ? '\n' + remainder : ''}\n`);
+  const remainder = coveredWholeFile ? '' : renderUnreadBelow(r, {
+    command: 'ss-read',
+    queryEvidence: receiptResponse?.queryEvidence,
+  });
+  const omitted = renderReadOmission(r, { surface: 'ss-read' });
+  if (omitted) process.stdout.write(`# ss-read ${r.file}${range}\n${omitted}\n`);
+  else process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`${remainder ? '\n' + remainder : ''}\n`);
   process.exit(0);
 }
 
@@ -336,9 +498,9 @@ async function cmdAgentSearch(rawArgs) {
   //   ss-search "<query>" --mode hybrid                    → force a mode (default: auto/CatBoost)
   //
   // Output is agent-readable: a meta header with routed mode + budget,
-  // followed by per-result blocks with file/line + fenced code. A trailing
-  // structured marker line `<<SS_ROUTE_META>>{...json...}` lets the bench
-  // post-process parse routing/budget telemetry without affecting the agent.
+  // followed by per-result blocks with file/line + fenced code and one compact
+  // actionable route trailer. SWEET_SEARCH_ROUTE_META_DEBUG=1 restores the
+  // complete JSON trailer for routing diagnostics.
   let format = 'agent';
   if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
   if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
@@ -350,7 +512,6 @@ async function cmdAgentSearch(rawArgs) {
     process.exit(2);
   }
 
-  const { queryServer } = await import(path.join(REPO_ROOT, 'core/search/search-server.js'));
   const serverUsed = await ensureWarmServerReady();
   if (!serverUsed) {
     process.stderr.write('[ss-search] warm server is not ready; refusing cold direct search in benchmark wrapper\n');
@@ -360,7 +521,11 @@ async function cmdAgentSearch(rawArgs) {
   // Budget-sweep experiment hook: per-request explicit budget (overrides the
   // auto-tier on the warm server; flows as the `budget` URL param).
   const envSearchBudget = Number(process.env.SS_SMOKE_SEARCH_BUDGET || '') || null;
-  const response = await queryServer(query, { topK: k, mode, format, ...(envSearchBudget ? { tokenBudget: envSearchBudget } : {}) });
+  const { queryServer } = await import(path.join(REPO_ROOT, 'core/search/search-server.js'));
+  const response = await queryServer(query, {
+    topK: k, mode, format, projectRoot: PROJECT_ROOT, trackAgentSpans: false,
+    ...(envSearchBudget ? { tokenBudget: envSearchBudget } : {}),
+  });
   if (response?.error) {
     process.stderr.write(`[ss-search] server error: ${response.error}\n`);
     process.exit(1);
@@ -380,7 +545,7 @@ async function cmdAgentSearch(rawArgs) {
       `but server reports serverProjectRoot=${serverProjectRoot ?? '<null>'}. ` +
       `Refusing to surface cross-repo results.\n`
     );
-    // Emit a structured trailer anyway so the bench can capture the failure.
+    // Emit a route trailer so the mismatch remains explicit in agent output.
     const failMeta = {
       query,
       queryHash: shortQueryHash(query),
@@ -397,9 +562,15 @@ async function cmdAgentSearch(rawArgs) {
       repoMatches: false,
       error: 'repo-isolation-mismatch',
     };
-    process.stdout.write(`\n<<SS_ROUTE_META>>${JSON.stringify(failMeta)}\n`);
+    process.stdout.write(`\n${formatRouteMetadata(failMeta, {
+      _isAgentFormat: true,
+      debug: process.env.SWEET_SEARCH_ROUTE_META_DEBUG === '1',
+    })}\n`);
     process.exit(3);
   }
+  const shownSpans = SPAN_POLICY_ENABLED
+    ? collectAgentShownSpans(response.results, { projectRoot: PROJECT_ROOT }) : [];
+  await recordAgentToolCall({ spans: shownSpans, query });
 
   // The packaged response shape comes from packageForAgent (or pattern's own
   // packager when CatBoost routes to pattern). Both include:
@@ -460,16 +631,23 @@ async function cmdAgentSearch(rawArgs) {
     if (r.sameFile && r.sameFile.rendered) {
       process.stdout.write(`${r.sameFile.rendered}\n`);
     }
+    if (r.continuation?.rendered) {
+      process.stdout.write(`${r.continuation.rendered}\n`);
+      if (r.continuation.kind === 'symbol' && r.continuation.code) {
+        process.stdout.write(`\`\`\`\n${r.continuation.code}\n\`\`\`\n`);
+      }
+    }
+    if (r.familyManifest?.rendered) process.stdout.write(`${r.familyManifest.rendered}\n`);
   }
 
   if (!response.results || response.results.length === 0) {
     process.stdout.write('(no matches)\n');
   }
+  const shownTrailer = SHOWN_SPAN_TRAILER ? renderShownFullTrailer(shownSpans) : '';
+  if (shownTrailer) process.stdout.write(`\n${shownTrailer}\n`);
 
-  // Structured trailer for bench post-processing (audit/summariseRun can parse).
-  // Route attribution fields (queryHash, routeMethod, routerLatency_us, query)
-  // let downstream analysis link a routing decision to its query and
-  // attribute failures to fast-path vs WASM vs fallback.
+  // Keep complete metadata available to the debug serializer, while normal
+  // agent output receives only the fields that can change its next action.
   const meta = {
     query,                     // exact query text (already bounded by SEARCH_SERVER_MAX_QUERY_LENGTH)
     queryHash: shortQueryHash(query),
@@ -501,7 +679,10 @@ async function cmdAgentSearch(rawArgs) {
     sameFileMapTokens: response.results?.[0]?.sameFile?.tokens ?? null,
     sameFileNeighborCount: response.results?.[0]?.sameFile?.neighbors?.length ?? null,
   };
-  process.stdout.write(`\n<<SS_ROUTE_META>>${JSON.stringify(meta)}\n`);
+  process.stdout.write(`\n${formatRouteMetadata(meta, {
+    _isAgentFormat: true,
+    debug: process.env.SWEET_SEARCH_ROUTE_META_DEBUG === '1',
+  })}\n`);
   process.exit(0);
 }
 
@@ -520,21 +701,36 @@ async function cmdSemantic(rawArgs) {
     process.stderr.write(SEMANTIC_USAGE + '\n');
     process.exit(2);
   }
-  const { readSemantic } = await import(path.join(REPO_ROOT, 'core/search/search-read-semantic.js'));
-  const r = await readSemantic({
-    path: file, query, projectRoot: PROJECT_ROOT,
-    maxChars: maxTokens * 4, verbose: false,
-  });
+  let r;
+  try {
+    if (!await ensureWarmServerReady({ timeoutMs: 5000 })) throw new Error('warm server is not ready');
+    const { queryReadSemanticServer } = await import(path.join(REPO_ROOT, 'core/search/search-server.js'));
+    r = await queryReadSemanticServer({
+      path: file, query, projectRoot: PROJECT_ROOT, maxChars: maxTokens * 4,
+    });
+    if (r?.error) throw new Error(r.error);
+  } catch {
+    const { readSemantic } = await import(path.join(REPO_ROOT, 'core/search/search-read-semantic.js'));
+    r = await readSemantic({
+      path: file, query, projectRoot: PROJECT_ROOT,
+      maxChars: maxTokens * 4, verbose: false,
+    });
+  }
   if (!r.ok) {
     process.stderr.write(`[ss-semantic] error: ${r.reason || 'unknown'}\n`);
     process.exit(1);
   }
+  const shownSpans = SPAN_POLICY_ENABLED
+    ? collectSemanticShownSpans(r, { projectRoot: PROJECT_ROOT }) : [];
+  await recordAgentToolCall({ spans: shownSpans, query });
   process.stdout.write(`# ss-semantic ${r.file} | "${query}" | spans=${r.spans?.length ?? 0} | ~tokens=${r.approxTokensReturned}${r.fellBack ? ' [FALLBACK]' : ''}\n`);
   for (const span of r.spans || []) {
     const fence = r.language ? '```' + r.language : '```';
     const sym = span.symbols?.length ? ` [${span.symbols.join(', ')}]` : '';
     process.stdout.write(`### ${r.file}:${span.startLine}-${span.endLine}${sym}\n${fence}\n${span.text}\n\`\`\`\n`);
   }
+  const shownTrailer = SHOWN_SPAN_TRAILER ? renderShownFullTrailer(shownSpans) : '';
+  if (shownTrailer) process.stdout.write(`${shownTrailer}\n`);
   process.exit(0);
 }
 
@@ -566,6 +762,9 @@ async function cmdTrace(rawArgs) {
   else if (Number(process.env.SS_SMOKE_TRACE_BUDGET || '') > 0) opts.tokenBudget = Number(process.env.SS_SMOKE_TRACE_BUDGET);
 
   const response = traceSymbol(symbol, opts);
+  await recordAgentToolCall({
+    query: json ? undefined : `${symbol} ${queryHint}`.trim(),
+  });
   if (json) process.stdout.write(JSON.stringify(response, null, 2) + '\n');
   else process.stdout.write(formatStructuralContext(response) + '\n');
 

package/mcp/read-tool.js

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+import {
+  applyReadOmissionDecisions,
+  collectReadShownSpans,
+  exactRereadOmissionEnabled,
+} from '../core/search/agent-span-ledger.js';
+import { sendAgentSpanOperation } from '../core/search/agent-span-client.js';
 
 const ReadFileResultSchema = z.object({
   file: z.string(),
@@ -33,6 +39,12 @@ const ReadFileResultSchema = z.object({
     })),
     moreCount: z.number().int(),
   }).nullable().optional(),
+  omitted: z.object({
+    file: z.string(),
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+    callsAgo: z.number().int(),
+  }).optional(),
   error: z.string().optional(),
   timings: z.object({ totalMs: z.number() }).optional(),
 });
@@ -70,8 +82,8 @@ export const ReadSemanticOutputSchema = z.object({
 });
 
 /**
- * @param {{ files: Array<{path: string, startLine?: number, endLine?: number}>, includeMetadata?: boolean }} args
- * @param {{ PROJECT_ROOT: string }} deps
+ * @param {{ files: Array<{path: string, startLine?: number, endLine?: number}>, includeMetadata?: boolean, force?: boolean }} args
+ * @param {{ PROJECT_ROOT: string, agentSessionId?: string }} deps
  */
 export async function handleRead(args, deps) {
   try {
@@ -80,8 +92,27 @@ export async function handleRead(args, deps) {
       projectRoot: deps.PROJECT_ROOT,
       includeMetadata: args.includeMetadata !== false,
     });
+    let queryEvidence = null;
+    if (exactRereadOmissionEnabled() && deps.agentSessionId) {
+      const spans = collectReadShownSpans(result, { projectRoot: deps.PROJECT_ROOT });
+      const response = await sendAgentSpanOperation({
+        operation: 'read',
+        sessionId: deps.agentSessionId,
+        spans,
+        force: args.force === true,
+      });
+      if (response?.ok && Array.isArray(response.decisions)) {
+        const decisions = Array.from({ length: result.files.length }, () => ({ omit: false }));
+        spans.forEach((span, index) => { decisions[span.resultIndex] = response.decisions[index]; });
+        applyReadOmissionDecisions(result, decisions);
+      }
+      queryEvidence = response?.queryEvidence || null;
+    }
     return {
-      content: [{ type: 'text', text: formatReadResults(result, 'agent') }],
+      content: [{
+        type: 'text',
+        text: formatReadResults(result, 'agent', { surface: 'mcp', queryEvidence }),
+      }],
       structuredContent: result,
     };
   } catch (err) {

package/mcp/server.js

@@ -12,6 +12,12 @@ 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 {
+  collectSemanticShownSpans,
+  exactRereadOmissionEnabled,
+  validAgentSessionId,
+} from '../core/search/agent-span-ledger.js';
+import { sendAgentSpanOperation } from '../core/search/agent-span-client.js';
 
 import {
   SearchOutputSchema,
@@ -104,13 +110,26 @@ async function getConfig() {
 
 const coreDir = path.join(__dirname, '..', 'core');
 
-const searchDeps = { getSearcher };
+const searchDeps = { getSearcher, PROJECT_ROOT };
 const traceDeps = { PROJECT_ROOT };
 const indexDeps = { PROJECT_ROOT, coreDir };
 const healthDeps = { getConfig, PROJECT_ROOT };
 const repoMapDeps = { coreDir, PROJECT_ROOT };
 const vocabDeps = { coreDir };
 
+function requestAgentSessionId(extra) {
+  // A long-lived MCP process does not receive later shell-environment rotation
+  // after clear/compact. Never fall back to inherited process session ids.
+  return validAgentSessionId(extra?.sessionId) ? extra.sessionId : null;
+}
+
+async function touchAgentCall(extra, spans = [], { query, regex } = {}) {
+  if (!exactRereadOmissionEnabled()) return;
+  const sessionId = requestAgentSessionId(extra);
+  if (!sessionId) return;
+  await sendAgentSpanOperation({ operation: 'observe', sessionId, spans, query, regex });
+}
+
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
@@ -171,7 +190,10 @@ server.registerTool('search', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async (args) => handleSearch(args, searchDeps));
+}, async (args, extra) => handleSearch(args, {
+  ...searchDeps,
+  agentSessionId: requestAgentSessionId(extra),
+}));
 
 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.',
@@ -194,7 +216,12 @@ server.registerTool('trace', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async (args) => handleTrace(args, traceDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra, [], {
+    query: `${args.symbol} ${args.query || ''}`.trim(),
+  });
+  return handleTrace(args, traceDeps);
+});
 
 server.registerTool('index', {
   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.',
@@ -209,7 +236,10 @@ server.registerTool('index', {
     idempotentHint: false,
     openWorldHint: false,
   },
-}, async (args) => handleIndex(args, indexDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra);
+  return handleIndex(args, indexDeps);
+});
 
 server.registerTool('health', {
   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.',
@@ -220,7 +250,8 @@ server.registerTool('health', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async () => {
+}, async (_args, extra) => {
+  await touchAgentCall(extra);
   const structured = await checkHealth(healthDeps);
 
   const statusLines = Object.entries(structured.subsystems).map(
@@ -251,7 +282,10 @@ server.registerTool('repo-map', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async (args) => handleRepoMap(args, repoMapDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra);
+  return handleRepoMap(args, repoMapDeps);
+});
 
 server.registerTool('vocab-prewarm', {
   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.',
@@ -272,7 +306,10 @@ server.registerTool('vocab-prewarm', {
     idempotentHint: true,
     openWorldHint: true,
   },
-}, async (args) => handleVocabPrewarm(args, vocabDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra);
+  return handleVocabPrewarm(args, vocabDeps);
+});
 
 server.registerTool('read', {
   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).',
@@ -284,10 +321,14 @@ server.registerTool('read', {
     })).min(1).max(20).describe('Files to read (1-20)'),
     includeMetadata: z.boolean().default(true).optional()
       .describe('Attach symbol-aware chunk metadata when the file is indexed'),
+    force: z.boolean().default(false).optional(),
   },
   outputSchema: ReadOutputSchema,
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-}, async (args) => handleRead(args, { PROJECT_ROOT }));
+}, async (args, extra) => handleRead(args, {
+  PROJECT_ROOT,
+  agentSessionId: requestAgentSessionId(extra),
+}));
 
 server.registerTool('read-semantic', {
   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.',
@@ -309,7 +350,12 @@ server.registerTool('read-semantic', {
   },
   outputSchema: ReadSemanticOutputSchema,
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-}, async (args) => handleReadSemantic(args, { PROJECT_ROOT }));
+}, async (args, extra) => {
+  const result = await handleReadSemantic(args, { PROJECT_ROOT });
+  const spans = collectSemanticShownSpans(result.structuredContent, { projectRoot: PROJECT_ROOT });
+  await touchAgentCall(extra, spans, { query: args.query });
+  return result;
+});
 
 // ---------------------------------------------------------------------------
 // Resources