sandoichi 0.4.2 → 0.6.0

package/src/core.mjs

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { stripVTControlCharacters } from 'node:util';
 
 import { planToolRoute, ROUTING_POLICY_VERSION } from './routing.mjs';
 import { loadProjectRedactionProfile } from './redaction-config.mjs';
@@ -9,6 +10,20 @@ const DEFAULT_POLICY = Object.freeze({
   maxColumns: 768, redact: true,
 });
 const POLICY_FIELDS = new Set(Object.keys(DEFAULT_POLICY));
+const SEVERE_DIAGNOSTIC_LINE = /\b(?:error|fail(?:ed|ure)?|exception|fatal|panic|traceback|assertion)\b/i;
+const WARNING_LINE = /\bwarning\b/i;
+// A test runner puts its totals in the middle of its own output as often as at the end — node's
+// TAP summary lands there whenever a second suite follows. Eliding those lines leaves a model
+// reading a plausible but partial count, with nothing to signal that a block went missing.
+const SUMMARY_LINE = /^\s*(?:#\s*(?:tests|pass|fail|skipped|todo|cancelled|suites)\b|test result:|(?:Tests|Test Suites):\s|=+[^=]*\b\d+\s+(?:passed|failed)\b)/i;
+const MAX_DIAGNOSTIC_LINES = 8;
+// Summaries get a reserved share: in a TAP stream most test names contain "error" or "fail", so
+// severe lines would otherwise crowd out the totals that actually answer the question.
+const MAX_SUMMARY_LINES = 4;
+// A TAP block prints seven counters and only three of them answer "did it pass": keeping the
+// block in source order would spend the quota on `cancelled` and `todo`.
+const HEADLINE_SUMMARY_LINE = /^\s*(?:#\s*(?:tests|pass|fail)\b|test result:|Tests:\s)/i;
+const MAX_DIAGNOSTIC_LINE_BYTES = 256;
 
 function sha256(text) {
   return `sha256:${createHash('sha256').update(text).digest('hex')}`;
@@ -76,27 +91,69 @@ function capColumns(text, maxColumns) {
   return text.split('\n').map((line) => truncateLine(line, maxColumns)).join('\n');
 }
 
-function middleView(text, maxBytes, headBytes, tailBytes) {
+function middleView(text, maxBytes, headBytes, tailBytes, salvageDiagnostics) {
   if (Buffer.byteLength(text) <= maxBytes) return text;
   const marker = '[middle elided]';
   const markerBytes = Buffer.byteLength(marker);
   if (maxBytes <= markerBytes) return truncateUtf8(marker, maxBytes);
   const available = maxBytes - markerBytes;
   const requested = Math.max(1, headBytes) + Math.max(1, tailBytes);
-  const head = Math.max(1, Math.floor(available * Math.max(1, headBytes) / requested));
-  const tail = Math.max(1, available - head);
-  return `${truncateUtf8(text, head)}${marker}${suffixUtf8(text, tail)}`;
+  if (!salvageDiagnostics) {
+    const head = Math.max(1, Math.floor(available * Math.max(1, headBytes) / requested));
+    const tail = Math.max(1, available - head);
+    return `${truncateUtf8(text, head)}${marker}${suffixUtf8(text, tail)}`;
+  }
+  const totalBytes = Buffer.byteLength(text);
+  const diagnosticBudget = Math.max(0, Math.floor(available / 2) - 2);
+  const minimumEdgeBytes = available - diagnosticBudget - 2;
+  const minimumHead = Math.max(1, Math.floor(minimumEdgeBytes * Math.max(1, headBytes) / requested));
+  const minimumTail = Math.max(1, minimumEdgeBytes - minimumHead);
+  const summaries = [];
+  const severe = [];
+  const warnings = [];
+  let offset = 0;
+  const lines = text.split('\n');
+  for (const [index, line] of lines.entries()) {
+    const lineBytes = Buffer.byteLength(line);
+    if (offset >= minimumHead && offset + lineBytes <= totalBytes - minimumTail) {
+      if (SUMMARY_LINE.test(line)) summaries.push(line);
+      else if (SEVERE_DIAGNOSTIC_LINE.test(line)) severe.push(line);
+      else if (WARNING_LINE.test(line)) warnings.push(line);
+    }
+    offset += lineBytes + (index < lines.length - 1 ? 1 : 0);
+  }
+  const keptSummaries = [
+    ...summaries.filter((line) => HEADLINE_SUMMARY_LINE.test(line)),
+    ...summaries.filter((line) => !HEADLINE_SUMMARY_LINE.test(line)),
+  ].slice(0, MAX_SUMMARY_LINES);
+  const diagnostics = [];
+  let diagnosticBytes = 0;
+  for (const line of [...keptSummaries, ...severe, ...warnings].slice(0, MAX_DIAGNOSTIC_LINES)) {
+    const separatorBytes = diagnostics.length ? 1 : 0;
+    const remaining = diagnosticBudget - diagnosticBytes - separatorBytes;
+    if (remaining < 1) break;
+    const salvaged = truncateLine(line, Math.min(MAX_DIAGNOSTIC_LINE_BYTES, remaining));
+    diagnostics.push(salvaged);
+    diagnosticBytes += separatorBytes + Buffer.byteLength(salvaged);
+  }
+  const diagnosticBlock = diagnostics.length ? `\n${diagnostics.join('\n')}\n` : '';
+  const edgeBytes = available - Buffer.byteLength(diagnosticBlock);
+  const head = Math.max(1, Math.floor(edgeBytes * Math.max(1, headBytes) / requested));
+  const tail = Math.max(1, edgeBytes - head);
+  return `${truncateUtf8(text, head)}${marker}${diagnosticBlock}${suffixUtf8(text, tail)}`;
 }
 
-function inlineView(text, maxBytes, headBytes, tailBytes, maxColumns) {
-  return middleView(capColumns(text, maxColumns), maxBytes, headBytes, tailBytes);
+function inlineView(text, maxBytes, headBytes, tailBytes, maxColumns, salvageDiagnostics) {
+  return middleView(capColumns(text, maxColumns), maxBytes, headBytes, tailBytes, salvageDiagnostics);
 }
 
+const DECLARATION_REGEX = /^\s*(?:import\b|from\b|export\b|use\b|package\b|(?:async\s+)?(?:def|function)\b|class\b|interface\b|trait\b|impl\b|struct\b|enum\b|namespace\b|module\b|type\b|(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=|func\b|(?:pub(?:\([^)]+\))?\s+)?fn\b|(?:(?:public|private|protected|static|abstract|async|get|set)\s+)+[A-Za-z_$][\w$]*\s*\(|@[A-Za-z_])/;
+
 function structuralRead(text) {
   const lines = text.split('\n');
-  const declaration = /^\s*(?:import\b|export\b|(?:async\s+)?function\b|class\b|interface\b|type\s+[A-Za-z_$][\w$]*\s*=|enum\b|namespace\b|module\b|(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=|(?:(?:public|private|protected|static|abstract|async|get|set)\s+)+[A-Za-z_$][\w$]*\s*\()/;
-  const selected = lines.flatMap((line, index) => declaration.test(line) ? [`${index + 1}:${line}`] : []);
+  const selected = lines.flatMap((line, index) => DECLARATION_REGEX.test(line) ? [`${index + 1}:${line}`] : []);
   if (!selected.length) return null;
+  if (lines.length >= 100 && selected.length < 2) return null;
   const outline = `[sando read structure: ${selected.length}/${lines.length} lines]\n${selected.join('\n')}`;
   return Buffer.byteLength(outline) + 64 < Buffer.byteLength(text) ? outline : null;
 }
@@ -125,6 +182,134 @@ function readSelector(toolInput) {
     .some((key) => Object.hasOwn(toolInput, key));
 }
 
+const SOURCE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.jsx',
+  '.ts', '.mts', '.cts', '.tsx',
+  '.py', '.pyw',
+  '.go',
+  '.rs',
+  '.c', '.h', '.cpp', '.hpp', '.cc', '.cxx',
+  '.java', '.kt', '.kts', '.scala',
+  '.cs', '.fs',
+  '.rb',
+  '.php',
+  '.swift',
+  '.sh', '.bash', '.zsh',
+  '.sql',
+  '.html', '.htm', '.css', '.scss', '.sass', '.less',
+  '.vue', '.svelte',
+  '.lua', '.zig', '.nim',
+]);
+
+const STRUCTURED_EXTENSIONS = new Set([
+  '.json', '.yaml', '.yml', '.toml', '.xml', '.csv',
+]);
+
+function parseReadCommand(command) {
+  if (typeof command !== 'string') return null;
+  const trimmed = command.trim();
+  const match = /^(?:cat|head|tail|sed)\b\s*(.*)$/.exec(trimmed);
+  if (!match) return null;
+  const rest = match[1];
+  if (/[|><;]/.test(rest)) return null;
+  const tokens = rest.split(/\s+/).filter(Boolean);
+  if (!tokens.length) return null;
+  const last = tokens[tokens.length - 1];
+  const cleanedPath = last.replace(/^['"]|['"]$/g, '');
+  const isSedSelector = /^sed\b/.test(trimmed) && /-n\b/.test(trimmed);
+  const isHeadOrTail = /^(?:head|tail)\b/.test(trimmed);
+  return {
+    filePath: cleanedPath,
+    selector: isSedSelector || isHeadOrTail,
+  };
+}
+
+function resolveSourceClass({ toolName, toolInput }) {
+  const name = typeof toolName === 'string' ? toolName.toLowerCase() : '';
+  if (name === 'grep') return { sourceClass: 'structured', selector: false, filePath: null };
+  let filePath = null;
+  let isSelector = false;
+  if (name === 'read') {
+    filePath = toolInput?.file_path ?? toolInput?.filePath ?? toolInput?.path ?? null;
+    isSelector = readSelector(toolInput);
+  } else if (name === 'bash') {
+    const cmd = typeof toolInput?.command === 'string' ? toolInput.command : null;
+    const parsed = cmd ? parseReadCommand(cmd) : null;
+    if (parsed) {
+      filePath = parsed.filePath;
+      isSelector = parsed.selector;
+    } else {
+      return { sourceClass: 'process-output', selector: false, filePath: null };
+    }
+  } else {
+    return { sourceClass: 'generic', selector: false, filePath: null };
+  }
+
+  if (filePath) {
+    const dotIndex = filePath.lastIndexOf('.');
+    if (dotIndex !== -1) {
+      const ext = filePath.slice(dotIndex).toLowerCase();
+      if (STRUCTURED_EXTENSIONS.has(ext)) return { sourceClass: 'structured-data', selector: isSelector, filePath };
+      if (ext === '.log' || filePath.endsWith('.min.js') || ext === '.map') return { sourceClass: 'bulk', selector: isSelector, filePath };
+      if (SOURCE_EXTENSIONS.has(ext)) return { sourceClass: 'source', selector: isSelector, filePath };
+    }
+  }
+  return { sourceClass: 'source', selector: isSelector, filePath };
+}
+
+const SOURCE_CLASS_LIMITS = Object.freeze({
+  source: Object.freeze({
+    maxInlineBytes: 32 * 1024,
+    headBytes: 20 * 1024,
+    tailBytes: 10 * 1024,
+  }),
+  'structured-data': Object.freeze({
+    maxInlineBytes: 8 * 1024,
+    headBytes: 5 * 1024,
+    tailBytes: 2 * 1024,
+  }),
+  'process-output': Object.freeze({
+    maxInlineBytes: 4 * 1024,
+    headBytes: 2457,
+    tailBytes: 1024,
+  }),
+  bulk: Object.freeze({
+    maxInlineBytes: 4 * 1024,
+    headBytes: 2048,
+    tailBytes: 1024,
+  }),
+  generic: Object.freeze({
+    maxInlineBytes: 4 * 1024,
+    headBytes: 2457,
+    tailBytes: 1024,
+  }),
+});
+
+// Appends the recovery command to the `[sando] artifact ...` line so the model reading a bounded
+// result can see how to get the rest back. Space for it was reserved before the view was cut.
+function withRecoveryHint(inline, artifact, elidedRange) {
+  const header = `[sando] artifact ${artifact.ref} ${artifact.bytes}B`;
+  if (!inline.startsWith(header)) return inline;
+  const range = elidedRange && Number.isInteger(elidedRange.startLine) && Number.isInteger(elidedRange.endLine)
+    ? ` --start-line ${elidedRange.startLine} --end-line ${elidedRange.endLine}`
+    : ' --max-bytes 65536';
+  return `${header} recover: sando artifact get --ref ${artifact.ref}${range}${inline.slice(header.length)}`;
+}
+
+function calculateElidedRange(fullText, inlineText) {
+  const marker = '[middle elided]';
+  const markerIndex = inlineText.indexOf(marker);
+  if (markerIndex === -1) return null;
+  const headPart = inlineText.slice(0, markerIndex);
+  const tailPart = inlineText.slice(markerIndex + marker.length);
+  const totalLines = fullText.split('\n').length;
+  const headLines = headPart.split('\n').length;
+  const tailLines = tailPart.split('\n').length;
+  const startLine = Math.max(1, headLines);
+  const endLine = Math.max(startLine, totalLines - tailLines + 1);
+  return { startLine, endLine };
+}
+
 export function estimateTokens(text) {
   if (typeof text !== 'string') throw new TypeError('text must be a string');
   return text.length === 0 ? 0 : Math.ceil(Buffer.byteLength(text) / 4);
@@ -156,40 +341,80 @@ export function optimizeToolOutput({
   const normalizedPolicy = normalizePolicy(policy);
   const input = textOutput(output);
   const name = toolName.toLowerCase();
+  const { sourceClass, selector: detectedSelector } = resolveSourceClass({ toolName, toolInput });
+  const isTargetedSelector = selector ?? (detectedSelector || readSelector(toolInput));
+  let baseInlineBudget = normalizedPolicy.maxInlineBytes;
+  let baseHeadBytes = normalizedPolicy.headBytes;
+  let baseTailBytes = normalizedPolicy.tailBytes;
+
+  if (sourceClass === 'source' || sourceClass === 'structured-data') {
+    const classLimit = SOURCE_CLASS_LIMITS[sourceClass];
+    const hasCustomInline = policy !== undefined && policy !== null
+      && Object.hasOwn(policy, 'maxInlineBytes')
+      && policy.maxInlineBytes !== DEFAULT_POLICY.maxInlineBytes;
+    if (!hasCustomInline) {
+      baseInlineBudget = classLimit.maxInlineBytes;
+      if (!policy || !Object.hasOwn(policy, 'headBytes')) baseHeadBytes = classLimit.headBytes;
+      if (!policy || !Object.hasOwn(policy, 'tailBytes')) baseTailBytes = classLimit.tailBytes;
+    }
+  }
   const derivedLineCount = lineCount ?? (name === 'read' ? input.split(/\r?\n/).length : lineCount);
   const derivedFileBytes = fileBytes ?? (name === 'read' ? Buffer.byteLength(input) : fileBytes);
   let route = planToolRoute({
-    toolName, selector: selector ?? readSelector(toolInput), raw: raw ?? toolInput?.raw === true,
+    toolName, selector: isTargetedSelector, raw: raw ?? toolInput?.raw === true,
     lineCount: derivedLineCount, fileBytes: derivedFileBytes, prose, summarizeProse, summarizeEnabled, grepScope,
     outputBytes: outputBytes ?? Buffer.byteLength(input),
   });
   const profile = normalizedPolicy.redact ? resolveRedactionProfile(cwd, redactionProfile) : null;
   const redacted = profile ? profile.redact(input) : { text: input, count: 0 };
+  const cleanedPreview = name === 'bash' ? stripVTControlCharacters(redacted.text) : redacted.text;
+  const previewRedacted = profile && name === 'bash'
+    ? profile.redact(cleanedPreview)
+    : { text: cleanedPreview, count: 0 };
+  const previewText = previewRedacted.text;
+  const sourceText = previewRedacted.count ? previewText : redacted.text;
   let modelText = name === 'bash' && normalizedPolicy.maxColumns >= 32
-    ? collapseRepeatedLines(redacted.text)
-    : redacted.text;
-  if (route.route === 'summary') {
-    const outline = structuralRead(redacted.text);
-    if (outline) modelText = outline;
-    else route = { route: 'passthrough', modelVisible: 'bounded-output', source: 'sando-read-bounded' };
-  }
+    ? collapseRepeatedLines(previewText)
+    : previewText;
   const routePolicy = route.route === 'artifact' || route.route === 'structured'
     ? {
       ...normalizedPolicy,
+      maxInlineBytes: Math.min(baseInlineBudget, route.route === 'artifact' ? (route.limits.headBytes + route.limits.tailBytes) : baseInlineBudget),
       ...(route.route === 'artifact' ? {
-        maxInlineBytes: Math.min(normalizedPolicy.maxInlineBytes, route.limits.headBytes + route.limits.tailBytes),
-        headBytes: Math.min(normalizedPolicy.headBytes, route.limits.headBytes),
-        tailBytes: Math.min(normalizedPolicy.tailBytes, route.limits.tailBytes),
-      } : {}),
+        headBytes: Math.min(baseHeadBytes, route.limits.headBytes),
+        tailBytes: Math.min(baseTailBytes, route.limits.tailBytes),
+      } : {
+        headBytes: baseHeadBytes,
+        tailBytes: baseTailBytes,
+      }),
       maxColumns: Math.min(normalizedPolicy.maxColumns, route.limits.maxColumns),
     }
-    : normalizedPolicy;
-  const sourceBytes = Buffer.byteLength(redacted.text);
+    : {
+      ...normalizedPolicy,
+      maxInlineBytes: baseInlineBudget,
+      headBytes: baseHeadBytes,
+      tailBytes: baseTailBytes,
+    };
+  const shouldSummarize = route.route === 'summary'
+    || (sourceClass === 'source' && !isTargetedSelector && (derivedLineCount ?? 0) >= 100 && (outputBytes ?? Buffer.byteLength(input)) > routePolicy.maxInlineBytes);
+  if (shouldSummarize) {
+    const outline = structuralRead(previewText);
+    if (outline) {
+      modelText = outline;
+      if (route.route !== 'summary') {
+        route = { route: 'summary', modelVisible: 'elided-structure', source: 'sando-read-summarize' };
+      }
+    } else if (route.route === 'summary') {
+      route = { route: 'passthrough', modelVisible: 'bounded-output', source: 'sando-read-bounded' };
+    }
+  }
+  const sourceBytes = Buffer.byteLength(sourceText);
   let inline = modelText;
   let artifact;
   const artifactAdmitted = sourceBytes <= normalizedPolicy.maxArtifactBytes;
   const hasLongLine = routePolicy.maxColumns > 0
     && modelText.split('\n').some((line) => Buffer.byteLength(line) > routePolicy.maxColumns);
+  let recoveryHintAffordable = false;
   if (!artifactAdmitted && (route.route === 'summary' || route.route === 'artifact'
     || sourceBytes > routePolicy.maxInlineBytes || hasLongLine)) {
     route = { route: 'passthrough', modelVisible: 'bounded-output', source: 'artifact-admission-limit' };
@@ -199,29 +424,48 @@ export function optimizeToolOutput({
       routePolicy.headBytes,
       routePolicy.tailBytes,
       routePolicy.maxColumns,
+      name === 'bash',
     ), normalizedPolicy.maxInlineBytes);
   } else if (route.route === 'summary' || route.route === 'artifact' || sourceBytes > routePolicy.maxInlineBytes || hasLongLine) {
-    const sourceDigest = sha256(redacted.text);
+    const sourceDigest = sha256(sourceText);
     artifact = {
       schema: 'sando-artifact/v1',
       ref: `sando:${sourceDigest.slice(0, 23)}`,
       digest: sourceDigest,
       sourceDigest,
       mediaType: 'text/plain; charset=utf-8',
-      content: redacted.text,
+      content: sourceText,
       bytes: sourceBytes,
       sourceBytes,
       truncated: false,
     };
+    // The recovery command has to reach the model, not just the disclosure object: on the CLI
+    // surface the structured disclosure is never rendered, so a bare artifact path leaves the
+    // model to improvise its way back to the elided middle. The exact line range is only known
+    // after the view is cut, so reserve the widest header the range could need and rewrite it
+    // once the range is settled -- reserving after the fact would push the payload over the cap.
     const header = `[sando] artifact ${artifact.ref} ${artifact.bytes}B\n`;
-    const viewBudget = Math.max(1, routePolicy.maxInlineBytes - Buffer.byteLength(header));
-    inline = `${truncateUtf8(header, routePolicy.maxInlineBytes)}${inlineView(
-      modelText,
-      viewBudget,
-      routePolicy.headBytes,
-      routePolicy.tailBytes,
-      routePolicy.maxColumns,
-    )}`;
+    const widestLineNumber = String(sourceText.split('\n').length).length;
+    const reservedHeader = Buffer.byteLength(header)
+      + Buffer.byteLength(` recover: sando artifact get --ref ${artifact.ref} --start-line  --end-line `)
+      + (widestLineNumber * 2);
+    // Under a tight cap the hint would cost more room than the content it points at, so it is
+    // only affordable when the whole header stays a small fraction of the budget.
+    recoveryHintAffordable = reservedHeader * 4 <= routePolicy.maxInlineBytes;
+    const viewBudget = Math.max(1, routePolicy.maxInlineBytes - (recoveryHintAffordable ? reservedHeader : Buffer.byteLength(header)));
+    const isOutline = typeof modelText === 'string' && modelText.startsWith('[sando read structure:');
+    if (isOutline && Buffer.byteLength(modelText) <= viewBudget) {
+      inline = `${truncateUtf8(header, routePolicy.maxInlineBytes)}${modelText}`;
+    } else {
+      inline = `${truncateUtf8(header, routePolicy.maxInlineBytes)}${inlineView(
+        modelText,
+        viewBudget,
+        routePolicy.headBytes,
+        routePolicy.tailBytes,
+        routePolicy.maxColumns,
+        name === 'bash',
+      )}`;
+    }
     inline = truncateUtf8(inline, routePolicy.maxInlineBytes);
   }
   const stats = {
@@ -232,15 +476,20 @@ export function optimizeToolOutput({
     artifactBytes: artifact?.bytes ?? 0,
     estimatedInputTokens: estimateTokens(input),
     estimatedInlineTokens: estimateTokens(inline),
-    redactions: redacted.count,
+    redactions: redacted.count + previewRedacted.count,
     artifactTruncated: artifact?.truncated ?? false,
   };
+  const elidedRange = artifact && inline.includes('[middle elided]')
+    ? calculateElidedRange(sourceText, inline)
+    : undefined;
+  if (artifact && recoveryHintAffordable) inline = withRecoveryHint(inline, artifact, elidedRange);
   const result = {
     inline, route: route.route, reason: route.source, policyVersion: ROUTING_POLICY_VERSION,
     redactionProfileDigest: profile?.digest ?? null, stats,
     disclosure: buildResultDisclosure({
       toolName, route: route.route, reason: route.source, inline,
-      redactedText: redacted.text, inputBytes: Buffer.byteLength(input), redactedBytes: sourceBytes, artifact,
+      redactedText: sourceText, inputBytes: Buffer.byteLength(input), redactedBytes: sourceBytes, artifact,
+      elidedRange,
     }),
   };
   if (artifact) result.artifact = artifact;

package/src/history-archive.mjs

@@ -0,0 +1,80 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function safeDirectory(target) {
+  const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error('history artifact directory is unsafe');
+  if (!stat) fs.mkdirSync(target, { mode: 0o700 });
+}
+
+function storedBytes(directory, destination) {
+  let total = 0;
+  for (const name of fs.readdirSync(directory)) {
+    if (!/^[a-f0-9]{64}\.txt$/.test(name)) continue;
+    const target = path.join(directory, name);
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || fs.realpathSync(target) !== target) {
+      throw new Error('history artifact directory contains an unsafe entry');
+    }
+    if (target !== destination) total += stat.size;
+  }
+  return total;
+}
+
+export function prepareHistoryArtifact({ root, content } = {}) {
+  if (typeof root !== 'string' || !path.isAbsolute(root)) throw new TypeError('history archive root must be an absolute path');
+  if (typeof content !== 'string') throw new TypeError('history artifact content is invalid');
+  const canonicalRoot = fs.realpathSync(root);
+  if (!fs.statSync(canonicalRoot).isDirectory()) throw new TypeError('history archive root is not a directory');
+  const bytes = Buffer.byteLength(content);
+  if (bytes > MAX_ARTIFACT_BYTES) throw new RangeError('history artifact exceeds recovery limit');
+  const digest = `sha256:${createHash('sha256').update(content).digest('hex')}`;
+  const ref = `sando:${digest}`;
+  const artifactPath = path.join(canonicalRoot, '.sando', 'sando', 'artifacts', `${digest.slice('sha256:'.length)}.txt`);
+  const lines = content.split('\n').length;
+  const firstPageEnd = Math.min(80, lines);
+  return {
+    root: canonicalRoot,
+    content,
+    bytes,
+    digest,
+    ref,
+    marker: `[sando archived result ${ref}; ${bytes}B, ${lines} lines; use rtk grep -n on archive ${shellQuote(artifactPath)}; full exact text: use native Read on the archive file; optional first page: sando artifact get --root ${shellQuote(canonicalRoot)} --ref ${ref} --start-line 1 --end-line ${firstPageEnd} --max-bytes 8192; bounded, continue with valid line ranges up to ${lines}]`,
+  };
+}
+
+export function persistHistoryArtifact(artifact) {
+  if (!artifact || typeof artifact.root !== 'string' || typeof artifact.content !== 'string'
+    || !/^sha256:[a-f0-9]{64}$/.test(artifact.digest ?? '') || artifact.ref !== `sando:${artifact.digest}`) {
+    throw new TypeError('history artifact is invalid');
+  }
+  const stateRoot = path.join(artifact.root, '.sando');
+  const privateRoot = path.join(stateRoot, 'sando');
+  const directory = path.join(privateRoot, 'artifacts');
+  for (const target of [stateRoot, privateRoot, directory]) safeDirectory(target);
+  const name = `${artifact.digest.slice('sha256:'.length)}.txt`;
+  const destination = path.join(directory, name);
+  if (storedBytes(directory, destination) + artifact.bytes > MAX_ARCHIVE_BYTES) {
+    throw new Error('history artifact archive is full');
+  }
+  const temporary = path.join(directory, `.${name}.${process.pid}.${randomUUID()}`);
+  try {
+    fs.writeFileSync(temporary, artifact.content, { flag: 'wx', mode: 0o600 });
+    try { fs.linkSync(temporary, destination); }
+    catch (error) {
+      if (error?.code !== 'EEXIST' || fs.readFileSync(destination, 'utf8') !== artifact.content) throw error;
+    }
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  fs.chmodSync(destination, 0o600);
+  return artifact;
+}

package/src/hook-cli.mjs

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 import { createReceipt, normalizeEvent, normalizePolicy, optimizeToolOutput } from './core.mjs';
+import { cleanupArtifacts } from './artifact-lifecycle.mjs';
 import { loadProjectRedactionProfile } from './redaction-config.mjs';
 import { defaultMetricsPath, recordMetrics } from './metrics.mjs';
 import {
@@ -12,6 +13,13 @@ import { PLUGIN_VERSION } from './version.mjs';
 
 function todayUtc() { return new Date().toISOString().slice(0, 10); }
 
+function artifactPresent(target) {
+  let stat;
+  try { stat = fs.lstatSync(target); } catch { return false; }
+  if (!stat.isFile() || stat.isSymbolicLink()) return false;
+  try { return fs.realpathSync(target) === target; } catch { return false; }
+}
+
 /** Only counts (never content, paths, or IDs). */
 function recordHookTelemetry({ host, env, policy, optimization }) {
   try {
@@ -23,6 +31,7 @@ function recordHookTelemetry({ host, env, policy, optimization }) {
     incrementCounter({
       statePaths,
       day: todayUtc(),
+      pluginVersion: PLUGIN_VERSION,
       event: 'hook_summary',
       host,
       mode: policy.mode === 'apply' ? 'enforce' : policy.mode === 'dry-run' ? 'dry_run' : 'observe',
@@ -46,7 +55,7 @@ function recordHookFailure({ host, env, failureStage }) {
     const statePaths = defaultTelemetryStatePaths(env);
     const day = todayUtc();
     recordActiveDay({ statePaths, day, pluginVersion: PLUGIN_VERSION, host });
-    recordFailure({ statePaths, day, event: 'hook_failure_summary', host, failureStage });
+    recordFailure({ statePaths, day, pluginVersion: PLUGIN_VERSION, event: 'hook_failure_summary', host, failureStage });
     closeFinishedDays({ statePaths, configPath, day, pluginVersion: PLUGIN_VERSION });
   } catch { /* telemetry is best-effort and must never affect hook output */ }
 }
@@ -69,6 +78,7 @@ function artifactPath(cwd, artifact) {
     if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error('artifact directory is unsafe');
     if (!stat) fs.mkdirSync(target, { mode: 0o700 });
   }
+  cleanupArtifacts(directory);
   const name = `${artifact.sourceDigest.slice('sha256:'.length)}.txt`;
   const destination = path.join(directory, name);
   const temporary = path.join(directory, `.${name}.${process.pid}.${randomUUID()}`);
@@ -82,6 +92,8 @@ function artifactPath(cwd, artifact) {
     fs.rmSync(temporary, { force: true });
   }
   fs.chmodSync(destination, 0o600);
+  cleanupArtifacts(directory, { preserveName: name });
+  if (!artifactPresent(destination)) throw new Error('artifact storage limit removed the new artifact');
   return path.posix.join('.sando/sando', 'artifacts', name);
 }
 
@@ -101,6 +113,10 @@ export function runHookCli({ host, env = process.env } = {}) {
     const eventName = input.hook_event_name ?? input.hookEventName ?? input.event_name ?? input.eventName;
     if (eventName === 'PostToolUse') {
       const event = normalizeEvent(input);
+      if (host === 'claude' && event.toolName.startsWith('mcp__')) {
+        process.stdout.write('{}\n');
+        return;
+      }
       failureStage = 'redaction';
       const redactionProfile = policy.redact ? loadProjectRedactionProfile(event.cwd).profile : undefined;
       failureStage = 'optimization';

package/src/lazy-mcp-gateway.mjs

@@ -4,11 +4,13 @@ export const LAZY_MCP_GATEWAY_SCHEMA = 'sando-lazy-mcp-gateway/v1';
 export const GATEWAY_CATALOG_TOOL = 'sando_catalog';
 export const GATEWAY_CALL_TOOL = 'sando_call';
 const MAX_CATALOG_RESULTS = 50;
+const DESCRIBED_CATALOG_RESULTS = 10;
 const GATEWAY_CATALOG_SCHEMA = {
   type: 'object', additionalProperties: false,
   properties: {
     query: { type: 'string' },
     limit: { type: 'integer', minimum: 1, maximum: MAX_CATALOG_RESULTS },
+    describe: { type: 'boolean' },
   },
 };
 const GATEWAY_CALL_SCHEMA = {
@@ -182,7 +184,9 @@ export function createLazyMcpGateway(config) {
       tools.set(`${name}/${descriptor.name}`, { ...descriptor, server: name, capability: descriptor.name });
     }
   }
-  async function catalog(query = '', limit = MAX_CATALOG_RESULTS) {
+  async function catalog(query = '', limit, describe = false) {
+    // Schemas are far heavier than names, so describe gets a smaller default.
+    const effectiveLimit = limit ?? (describe ? DESCRIBED_CATALOG_RESULTS : MAX_CATALOG_RESULTS);
     const startedAt = Date.now();
     if (!options.enabled) {
       emitF4Event({ operation: 'catalog', outcome: 'rejected', startedAt });
@@ -197,10 +201,10 @@ export function createLazyMcpGateway(config) {
         for (const [qualified, descriptor] of tools) if (descriptor.server === name) {
           const text = tokens(`${qualified} ${descriptor.description ?? ''} ${name} ${(options.servers.get(name).capabilities ?? []).join(' ')}`);
           const score = queryTokens.reduce((total, token) => total + (text.includes(token) ? 1 : 0), 0);
-          if (!queryTokens.length || score) records.push({ namespace: name, description: String(descriptor.description ?? '').slice(0, 160), server: name, capability: descriptor.capability, name: qualified, score });
+          if (!queryTokens.length || score) records.push({ namespace: name, description: String(descriptor.description ?? '').slice(0, 160), server: name, capability: descriptor.capability, name: qualified, score, ...(describe && descriptor.inputSchema ? { inputSchema: descriptor.inputSchema } : {}) });
         }
       }
-      const result = records.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, Math.min(limit, MAX_CATALOG_RESULTS)).map(({ score, ...record }) => record);
+      const result = records.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, Math.min(effectiveLimit, MAX_CATALOG_RESULTS)).map(({ score, ...record }) => record);
       emitF4Event({ operation: 'catalog', outcome: 'success', startedAt, resultCount: result.length });
       return result;
     } catch (error) {
@@ -261,10 +265,10 @@ export function createLazyMcpGateway(config) {
         emitF4Event({ operation: 'catalog', outcome: 'rejected', startedAt: Date.now() });
         return rpcError(message.id, -32602, `Invalid catalog arguments: ${validation.message}`);
       }
-      return response(message.id, { schema: LAZY_MCP_GATEWAY_SCHEMA, entries: await catalog(arguments_.query, arguments_.limit) });
+      return response(message.id, { schema: LAZY_MCP_GATEWAY_SCHEMA, entries: await catalog(arguments_.query, arguments_.limit, arguments_.describe) });
     }
     if (message.method === 'tools/list') return response(message.id, { tools: [
-      { name: GATEWAY_CATALOG_TOOL, description: 'Search the explicit allowlisted MCP catalog.', inputSchema: GATEWAY_CATALOG_SCHEMA },
+      { name: GATEWAY_CATALOG_TOOL, description: 'Search the explicit allowlisted MCP catalog. Pass describe:true to include each tool argument schema, needed before sando_call.', inputSchema: GATEWAY_CATALOG_SCHEMA },
       { name: GATEWAY_CALL_TOOL, description: 'Call one exact qualified name returned by sando_catalog.', inputSchema: GATEWAY_CALL_SCHEMA },
     ] });
     if (message.method === 'tools/call' && message.params?.name === GATEWAY_CATALOG_TOOL) {
@@ -274,7 +278,7 @@ export function createLazyMcpGateway(config) {
         emitF4Event({ operation: 'catalog', outcome: 'rejected', startedAt: Date.now() });
         return rpcError(message.id, -32602, `Invalid catalog arguments: ${validation.message}`);
       }
-      return response(message.id, { content: [{ type: 'text', text: JSON.stringify(await catalog(arguments_.query, arguments_.limit)) }] });
+      return response(message.id, { content: [{ type: 'text', text: JSON.stringify(await catalog(arguments_.query, arguments_.limit, arguments_.describe)) }] });
     }
     if (message.method === 'tools/call' && message.params?.name === GATEWAY_CALL_TOOL) {
       const validation = validateJsonSchema(GATEWAY_CALL_SCHEMA, message.params?.arguments);