sandoichi 0.1.0

package/src/core.mjs

@@ -0,0 +1,258 @@
+import { createHash } from 'node:crypto';
+
+import { planToolRoute, ROUTING_POLICY_VERSION } from './routing.mjs';
+import { redact } from './secret-redaction.mjs';
+
+const DEFAULT_POLICY = Object.freeze({
+  mode: 'apply', maxInlineBytes: 4096, maxArtifactBytes: 65536, headBytes: undefined, tailBytes: undefined,
+  maxColumns: 768, redact: true,
+});
+const POLICY_FIELDS = new Set(Object.keys(DEFAULT_POLICY));
+
+function sha256(text) {
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+function stableJson(value, seen = new Set()) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (seen.has(value)) throw new Error('output must not be cyclic');
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) result = `[${value.map((item) => stableJson(item, seen)).join(',')}]`;
+  else result = `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key], seen)}`).join(',')}}`;
+  seen.delete(value);
+  return result;
+}
+
+function textOutput(output) {
+  if (typeof output === 'string') return output;
+  const value = stableJson(output);
+  if (value === undefined) throw new Error('output must be a string or JSON value');
+  return value;
+}
+
+function truncateUtf8(text, maxBytes) {
+  if (Buffer.byteLength(text) <= maxBytes) return text;
+  let bytes = 0;
+  let output = '';
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > maxBytes) break;
+    output += character;
+    bytes += size;
+  }
+  return output;
+}
+
+function suffixUtf8(text, maxBytes) {
+  let bytes = 0;
+  const characters = [];
+  for (const character of [...text].reverse()) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > maxBytes) break;
+    characters.push(character);
+    bytes += size;
+  }
+  return characters.reverse().join('');
+}
+
+function truncateLine(text, maxBytes) {
+  if (Buffer.byteLength(text) <= maxBytes) return text;
+  if (maxBytes <= 1) return '~';
+  return `${truncateUtf8(text, maxBytes - 1)}~`;
+}
+
+function capColumns(text, maxColumns) {
+  if (!maxColumns) return text;
+  return text.split('\n').map((line) => truncateLine(line, maxColumns)).join('\n');
+}
+
+function middleView(text, maxBytes, headBytes, tailBytes) {
+  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)}`;
+}
+
+function inlineView(text, maxBytes, headBytes, tailBytes, maxColumns) {
+  return middleView(capColumns(text, maxColumns), maxBytes, headBytes, tailBytes);
+}
+
+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}`] : []);
+  if (!selected.length) 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;
+}
+
+function collapseRepeatedLines(text) {
+  const lines = text.split('\n');
+  const compacted = [];
+  for (let index = 0; index < lines.length;) {
+    let end = index + 1;
+    while (end < lines.length && lines[end] === lines[index]) end += 1;
+    const count = end - index;
+    if (count >= 3 && lines[index] !== '') {
+      compacted.push(lines[index], `[sando repeated x${count}]`);
+    } else {
+      compacted.push(...lines.slice(index, end));
+    }
+    index = end;
+  }
+  const result = compacted.join('\n');
+  return Buffer.byteLength(result) + 32 < Buffer.byteLength(text) ? result : text;
+}
+
+function readSelector(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) return false;
+  return ['offset', 'limit', 'line_start', 'line_end', 'start_line', 'end_line']
+    .some((key) => Object.hasOwn(toolInput, key));
+}
+
+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);
+}
+
+export function normalizePolicy(policy = {}) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)
+    || Object.keys(policy).some((key) => !POLICY_FIELDS.has(key))) throw new Error('invalid policy');
+  const result = { ...DEFAULT_POLICY, ...policy };
+  result.headBytes = result.headBytes ?? Math.floor(result.maxInlineBytes * 0.6);
+  result.tailBytes = result.tailBytes ?? Math.floor(result.maxInlineBytes * 0.25);
+  if (!['apply', 'dry-run', 'observe'].includes(result.mode)
+    || !Number.isInteger(result.maxInlineBytes) || result.maxInlineBytes < 64 || result.maxInlineBytes > 1_048_576
+    || !Number.isInteger(result.maxArtifactBytes) || result.maxArtifactBytes < 256 || result.maxArtifactBytes > 16_777_216
+    || !Number.isInteger(result.headBytes) || result.headBytes < 1
+    || !Number.isInteger(result.tailBytes) || result.tailBytes < 1
+    || result.headBytes + result.tailBytes > result.maxInlineBytes
+    || !Number.isInteger(result.maxColumns) || result.maxColumns < 1 || result.maxColumns > 1_048_576
+    || typeof result.redact !== 'boolean') throw new Error('invalid policy');
+  return result;
+}
+
+export function optimizeToolOutput({
+  toolName, output, cwd, policy, selector, raw, lineCount, fileBytes, prose, summarizeProse,
+  summarizeEnabled, grepScope, outputBytes, toolInput,
+} = {}) {
+  if (typeof toolName !== 'string' || !toolName.trim() || toolName.length > 128) throw new Error('toolName is invalid');
+  if (typeof cwd !== 'string' || !cwd) throw new Error('cwd is invalid');
+  const normalizedPolicy = normalizePolicy(policy);
+  const input = textOutput(output);
+  const name = toolName.toLowerCase();
+  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,
+    lineCount: derivedLineCount, fileBytes: derivedFileBytes, prose, summarizeProse, summarizeEnabled, grepScope,
+    outputBytes: outputBytes ?? Buffer.byteLength(input),
+  });
+  const redacted = normalizedPolicy.redact ? redact(input) : { text: input, count: 0 };
+  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' };
+  }
+  const routePolicy = route.route === 'artifact' || route.route === 'structured'
+    ? {
+      ...normalizedPolicy,
+      ...(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),
+      } : {}),
+      maxColumns: Math.min(normalizedPolicy.maxColumns, route.limits.maxColumns),
+    }
+    : normalizedPolicy;
+  const sourceBytes = Buffer.byteLength(redacted.text);
+  let inline = modelText;
+  let artifact;
+  const hasLongLine = routePolicy.maxColumns > 0
+    && modelText.split('\n').some((line) => Buffer.byteLength(line) > routePolicy.maxColumns);
+  if (route.route === 'summary' || route.route === 'artifact' || sourceBytes > routePolicy.maxInlineBytes || hasLongLine) {
+    const sourceDigest = sha256(redacted.text);
+    artifact = {
+      schema: 'sando-artifact/v1',
+      ref: `sando:${sourceDigest.slice(0, 23)}`,
+      digest: sourceDigest,
+      sourceDigest,
+      mediaType: 'text/plain; charset=utf-8',
+      content: redacted.text,
+      bytes: sourceBytes,
+      sourceBytes,
+      truncated: false,
+    };
+    const header = `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,
+    )}`;
+    inline = truncateUtf8(inline, routePolicy.maxInlineBytes);
+  }
+  const stats = {
+    mode: normalizedPolicy.mode,
+    inputBytes: Buffer.byteLength(input),
+    redactedBytes: sourceBytes,
+    inlineBytes: Buffer.byteLength(inline),
+    artifactBytes: artifact?.bytes ?? 0,
+    estimatedInputTokens: estimateTokens(input),
+    estimatedInlineTokens: estimateTokens(inline),
+    redactions: redacted.count,
+    artifactTruncated: artifact?.truncated ?? false,
+  };
+  const result = { inline, route: route.route, reason: route.source, policyVersion: ROUTING_POLICY_VERSION, stats };
+  if (artifact) result.artifact = artifact;
+  return result;
+}
+
+export function normalizeEvent(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('event must be an object');
+  const event = {
+    eventName: input.hook_event_name ?? input.hookEventName ?? input.event_name ?? input.eventName,
+    toolName: input.tool_name ?? input.toolName,
+    toolInput: input.tool_input ?? input.toolInput,
+    output: input.tool_response ?? input.toolResponse ?? input.tool_output ?? input.toolOutput ?? input.output,
+    cwd: input.cwd,
+    sessionId: input.session_id ?? input.sessionId ?? input.thread_id ?? input.threadId
+      ?? input.conversation_id ?? input.conversationId,
+    eventId: input.event_id ?? input.eventId ?? input.uuid ?? input.id,
+    client: input.client ?? input.client_name ?? input.clientName,
+    clientVersion: input.client_version ?? input.clientVersion,
+    model: input.model ?? input.model_name ?? input.modelName,
+    timestamp: input.timestamp ?? input.event_timestamp ?? input.eventTimestamp
+      ?? input.occurred_at ?? input.occurredAt,
+    providerUsage: input.provider_usage ?? input.providerUsage,
+  };
+  if (typeof event.eventName !== 'string' || typeof event.toolName !== 'string'
+    || event.output === undefined || typeof event.cwd !== 'string' || !event.cwd) throw new Error('event is incomplete');
+  for (const field of ['toolInput', 'sessionId', 'eventId', 'client', 'clientVersion', 'model', 'timestamp', 'providerUsage']) {
+    if (event[field] === undefined) delete event[field];
+  }
+  return event;
+}
+
+export function createReceipt({ host, event, optimization, replacement } = {}) {
+  if (typeof host !== 'string' || !host || !event || !optimization?.stats) throw new Error('receipt input is invalid');
+  const body = {
+    schema: 'sando-receipt/v1', host, eventName: event.eventName, toolName: event.toolName,
+    sessionId: event.sessionId ?? null, inputDigest: sha256(textOutput(event.output)),
+    inlineDigest: sha256(textOutput(replacement === undefined ? optimization.inline : replacement)), artifactRef: optimization.artifact?.ref ?? null,
+    route: optimization.route ?? 'passthrough', reason: optimization.reason ?? 'spike-default',
+    policyVersion: optimization.policyVersion ?? ROUTING_POLICY_VERSION, stats: optimization.stats,
+  };
+  return { ...body, digest: sha256(stableJson(body)) };
+}

package/src/history-budget.mjs

@@ -0,0 +1,36 @@
+const INVALID_BUDGET = 'maxHistoryTokens must be a positive safe integer';
+
+export function validateMaxHistoryTokens(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(INVALID_BUDGET);
+  return value;
+}
+
+export function selectHistoryCandidates({ bodyTokens, maxHistoryTokens, candidates } = {}) {
+  validateMaxHistoryTokens(maxHistoryTokens);
+  if (!Number.isSafeInteger(bodyTokens) || bodyTokens < 0 || !Array.isArray(candidates)) return [];
+  if (BigInt(bodyTokens) * 5n <= BigInt(maxHistoryTokens) * 4n) return [];
+
+  const idCounts = new Map();
+  for (const candidate of candidates) {
+    if (typeof candidate?.id === 'string' && candidate.id.length > 0) {
+      idCounts.set(candidate.id, (idCounts.get(candidate.id) ?? 0) + 1);
+    }
+  }
+
+  return candidates.filter((candidate) =>
+    candidate !== null
+    && typeof candidate === 'object'
+    && typeof candidate.id === 'string'
+    && candidate.id.length > 0
+    && idCounts.get(candidate.id) === 1
+    && candidate.safe === true
+    && candidate.historical === true
+    && candidate.error !== true
+    && candidate.current !== true
+    && Number.isSafeInteger(candidate.position)
+    && candidate.position >= 0
+    && Number.isSafeInteger(candidate.estimatedTokens)
+    && candidate.estimatedTokens > 0)
+    .sort((left, right) =>
+      left.position - right.position || right.estimatedTokens - left.estimatedTokens);
+}

package/src/history-dedupe.mjs

@@ -0,0 +1,98 @@
+const DUPLICATE = '[sando duplicate historical result]';
+const TOOLS = new Set(['read', 'exec', 'grep', 'bash']);
+
+function canonical(value, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number') return Number.isFinite(value) ? JSON.stringify(value) : null;
+  if (typeof value !== 'object' || seen.has(value)) return null;
+
+  seen.add(value);
+  let result = null;
+  if (Array.isArray(value)) {
+    const items = [];
+    for (let index = 0; index < value.length; index += 1) {
+      if (!Object.hasOwn(value, index)) return null;
+      const item = canonical(value[index], seen);
+      if (item === null) return null;
+      items.push(item);
+    }
+    result = `[${items.join(',')}]`;
+  } else if ([Object.prototype, null].includes(Object.getPrototypeOf(value))
+    && Object.getOwnPropertySymbols(value).length === 0) {
+    const items = [];
+    for (const key of Object.keys(value).sort()) {
+      const item = canonical(value[key], seen);
+      if (item === null) return null;
+      items.push(`${JSON.stringify(key)}:${item}`);
+    }
+    result = `{${items.join(',')}}`;
+  }
+  seen.delete(value);
+  return result;
+}
+
+function outputText(output) {
+  if (typeof output === 'string') return output;
+  if (!Array.isArray(output) || output.length === 0
+    || !output.every((block) => ['text', 'input_text'].includes(block?.type) && typeof block.text === 'string')) return null;
+  return output.map((block) => block.text).join('');
+}
+
+function error(entry, text) {
+  return entry.isError === true || Object.hasOwn(entry, 'error')
+    || ['error', 'failed'].includes(entry.status)
+    || /^\s*(?:error|failed|failure)\b[:\s-]*/i.test(text);
+}
+
+function identity(entry) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return null;
+  if (typeof entry.id !== 'string' || entry.id.length === 0 || typeof entry.toolName !== 'string') return null;
+  const tool = entry.toolName.toLowerCase();
+  if (!TOOLS.has(tool)) return null;
+  if (entry.input === null || (typeof entry.input !== 'object' && typeof entry.input !== 'string') || Array.isArray(entry.input)) return null;
+  const input = canonical(entry.input);
+  const output = canonical(entry.output);
+  const text = outputText(entry.output);
+  if (input === null || output === null || text === null || error(entry, text)) return null;
+  return `${tool}\0${input}\0${output}`;
+}
+
+function elide(output) {
+  if (typeof output === 'string') return DUPLICATE;
+  return output.map((block, index) => ({ ...block, text: index === 0 ? DUPLICATE : '' }));
+}
+
+function serializedBytes(value) {
+  const serialized = JSON.stringify(value);
+  return serialized === undefined ? Infinity : Buffer.byteLength(serialized);
+}
+
+export function dedupeHistory(entries) {
+  if (!Array.isArray(entries)) return { entries, deduplicated: 0 };
+
+  const idCounts = new Map();
+  for (const entry of entries) {
+    if (typeof entry?.id === 'string' && entry.id.length > 0) {
+      idCounts.set(entry.id, (idCounts.get(entry.id) ?? 0) + 1);
+    }
+  }
+
+  const seen = new Set();
+  const result = [...entries];
+  let deduplicated = 0;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (idCounts.get(entry?.id) !== 1) continue;
+    const key = identity(entry);
+    if (key === null) continue;
+    if (seen.has(key) && entry.current !== true) {
+      const replacement = elide(entry.output);
+      if (serializedBytes(replacement) >= serializedBytes(entry.output)) continue;
+      result[index] = { ...entry, output: replacement };
+      deduplicated += 1;
+    } else {
+      seen.add(key);
+    }
+  }
+  return { entries: result, deduplicated };
+}

package/src/history-shake.mjs

@@ -0,0 +1,66 @@
+import { estimateTokens } from './core.mjs';
+
+const SUPPORTED_TOOLS = new Set(['bash', 'exec', 'grep', 'log']);
+const DEFAULT_MIN_TOKENS = 400;
+const HEAD_LINES = 3;
+const TAIL_LINES = 3;
+const MAX_SIGNAL_LINES = 12;
+const SIGNAL_LINE = /\b(?:error|failed|failure|fatal|panic|exception|warning|todo|fixme)\b/i;
+
+function result(text, changed = false, compactedText = text) {
+  return {
+    text: compactedText,
+    changed,
+    originalTokens: estimateTokens(text),
+    compactedTokens: estimateTokens(compactedText),
+    originalLines: text.split('\n').length,
+    compactedLines: compactedText.split('\n').length,
+  };
+}
+
+function selectedLines(lines) {
+  const selected = new Set();
+  for (let index = 0; index < Math.min(HEAD_LINES, lines.length); index += 1) selected.add(index);
+  for (let index = Math.max(0, lines.length - TAIL_LINES); index < lines.length; index += 1) selected.add(index);
+
+  let signalCount = 0;
+  for (let index = 0; index < lines.length && signalCount < MAX_SIGNAL_LINES; index += 1) {
+    if (!SIGNAL_LINE.test(lines[index])) continue;
+    selected.add(index);
+    signalCount += 1;
+  }
+  return selected;
+}
+
+function compact(lines, selected) {
+  const output = [];
+  for (let index = 0; index < lines.length;) {
+    if (selected.has(index)) {
+      output.push(lines[index]);
+      index += 1;
+      continue;
+    }
+    const start = index;
+    while (index < lines.length && !selected.has(index)) index += 1;
+    output.push(`[sando history shake: ${index - start} lines elided; rerun tool if needed]`);
+  }
+  return output.join('\n');
+}
+
+export function shakeHistoricalResult({ toolName, text, historical, isError, minTokens = DEFAULT_MIN_TOKENS } = {}) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  if (!Number.isSafeInteger(minTokens) || minTokens <= 0) throw new TypeError('minTokens must be a positive safe integer');
+  const normalizedTool = typeof toolName === 'string' ? toolName.toLowerCase() : '';
+  const originalTokens = estimateTokens(text);
+  if (!historical || isError === true || !SUPPORTED_TOOLS.has(normalizedTool) || originalTokens < minTokens) {
+    return result(text);
+  }
+
+  const lines = text.split('\n');
+  const selected = selectedLines(lines);
+  if (selected.size >= lines.length) return result(text);
+
+  const compacted = compact(lines, selected);
+  if (Buffer.byteLength(compacted) >= Buffer.byteLength(text)) return result(text);
+  return result(text, true, compacted);
+}

package/src/history-structure.mjs

@@ -0,0 +1,28 @@
+// Matches history-shake.mjs's SUPPORTED_TOOLS. These two modules do variants of the
+// same job — collapsing repetitive historical line output — and previously disagreed
+// on which tools qualify: shake allowed exec/grep, this one did not. Codex reports
+// tool results as `exec`/`grep`, so structural collapse could never run there, which
+// is the whole reason the recorded Claude and Codex proxy runs show mirrored
+// compactedStructures/shakenResults counts. This transform is the more conservative
+// of the two (identical consecutive lines only, and it returns the original unless
+// the result is strictly smaller), so anything shake may touch it may touch too.
+const SUPPORTED_TOOLS = new Set(['bash', 'exec', 'grep', 'log']);
+
+export function compactHistoricalStructure({ toolName, text, historical, isError }) {
+  const normalizedTool = typeof toolName === 'string' ? toolName.toLowerCase() : '';
+  if (!historical || isError || !SUPPORTED_TOOLS.has(normalizedTool)) return text;
+
+  const lines = text.split('\n');
+  const compacted = [];
+  for (let index = 0; index < lines.length;) {
+    let end = index + 1;
+    while (end < lines.length && lines[end] === lines[index]) end += 1;
+    const count = end - index;
+    if (lines[index] && count > 1) compacted.push(lines[index], `[sando repeated x${count}]`);
+    else compacted.push(...lines.slice(index, end));
+    index = end;
+  }
+
+  const result = compacted.join('\n');
+  return Buffer.byteLength(result) < Buffer.byteLength(text) ? result : text;
+}

package/src/hook-cli.mjs

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+import { createReceipt, normalizeEvent, normalizePolicy, optimizeToolOutput } from './core.mjs';
+import { defaultMetricsPath, recordMetrics } from './metrics.mjs';
+
+function hookPolicy(env, host) {
+  const policy = env.SANDO_POLICY
+    ? JSON.parse(env.SANDO_POLICY)
+    : { mode: env.SANDO_MODE || (host === 'claude' ? 'apply' : 'observe') };
+  if (/^(1|true|yes)$/i.test(env.SANDO_OBSERVE_ONLY || '')) policy.mode = 'observe';
+  return normalizePolicy(policy);
+}
+
+function artifactPath(cwd, artifact) {
+  const root = fs.realpathSync(cwd);
+  const stateRoot = path.join(root, '.sando');
+  const privateRoot = path.join(stateRoot, 'sando');
+  const directory = path.join(privateRoot, 'artifacts');
+  for (const target of [stateRoot, privateRoot, directory]) {
+    const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error('artifact directory is unsafe');
+    if (!stat) fs.mkdirSync(target, { mode: 0o700 });
+  }
+  const name = `${artifact.sourceDigest.slice('sha256:'.length)}.txt`;
+  const destination = path.join(directory, name);
+  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 path.posix.join('.sando/sando', 'artifacts', name);
+}
+
+export function runHookCli({ host, env = process.env } = {}) {
+  let policy;
+  try {
+    policy = hookPolicy(env, host);
+  } catch (error) {
+    process.stderr.write(`sando invalid policy: ${error instanceof Error ? error.message : 'invalid input'}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  try {
+    const input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+    const eventName = input.hook_event_name ?? input.hookEventName ?? input.event_name ?? input.eventName;
+    if (eventName === 'PostToolUse') {
+      const event = normalizeEvent(input);
+      const optimization = optimizeToolOutput({ toolName: event.toolName, toolInput: event.toolInput, output: event.output, cwd: event.cwd, policy });
+      let shaped;
+      if (host === 'claude' && policy.mode === 'apply') {
+        shaped = shapeForClaude({
+          original: event.output,
+          optimization,
+          toolName: event.toolName,
+          toolInput: event.toolInput,
+          cwd: event.cwd,
+          policy,
+        });
+      }
+      const receipt = createReceipt({ host, event, optimization, replacement: shaped });
+      try {
+        recordMetrics({ storagePath: defaultMetricsPath(env), host, event, optimization, receipt });
+      } catch {}
+      if (host === 'codex' && policy.mode === 'apply' && env.SANDO_CODEX_FALLBACK === 'feedback') {
+        process.stdout.write(`${JSON.stringify(buildCodexFallback({ optimization, cwd: event.cwd }))}\n`);
+        return;
+      }
+      if (host === 'claude' && policy.mode === 'apply') {
+        if (shaped !== undefined) {
+          process.stdout.write(`${JSON.stringify({ hookSpecificOutput: {
+            hookEventName: 'PostToolUse', updatedToolOutput: shaped,
+          } })}\n`);
+          return;
+        }
+      }
+    }
+  } catch {}
+  process.stdout.write('{}\n');
+}
+
+function materialize(optimization, cwd) {
+  if (!optimization.artifact) return optimization.inline;
+  return optimization.inline.replace(optimization.artifact.ref, artifactPath(cwd, optimization.artifact));
+}
+
+export function buildCodexFallback({ optimization, cwd }) {
+  const reference = optimization.artifact ? artifactPath(cwd, optimization.artifact) : 'inline output';
+  return {
+    continue: false,
+    stopReason: 'Sando fallback: Codex cannot transparently rewrite tool output',
+    systemMessage: `Sando fallback prepared ${reference}; tool output was not rewritten.`,
+  };
+}
+
+function shapeForClaude({ original, optimization, toolName, toolInput, cwd, policy }) {
+  if (typeof original === 'string') return materialize(optimization, cwd);
+  if (!original || typeof original !== 'object' || Array.isArray(original)
+    || !Object.hasOwn(original, 'stdout') || !Object.hasOwn(original, 'stderr')
+    || typeof original.stdout !== 'string' || typeof original.stderr !== 'string'
+    || (Object.hasOwn(original, 'interrupted') && typeof original.interrupted !== 'boolean')
+    || (Object.hasOwn(original, 'isImage') && typeof original.isImage !== 'boolean')) return undefined;
+  const result = { ...original };
+  if (typeof original.stdout === 'string') {
+    result.stdout = materialize(optimizeToolOutput({ toolName, toolInput, output: original.stdout, cwd, policy }), cwd);
+  }
+  if (typeof original.stderr === 'string') {
+    result.stderr = materialize(optimizeToolOutput({ toolName, toolInput, output: original.stderr, cwd, policy }), cwd);
+  }
+  return result;
+}

package/src/mcp-server.mjs

@@ -0,0 +1,45 @@
+import readline from 'node:readline';
+
+import { optimizeToolOutput } from './core.mjs';
+
+const TOOL = {
+  name: 'prepare_tool_output',
+  description: 'Prepare deterministic bounded inline output and an optional redacted artifact payload. Performs no writes or network access.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['toolName', 'output', 'cwd'],
+    properties: { toolName: { type: 'string', minLength: 1, maxLength: 128 }, output: {}, cwd: { type: 'string', minLength: 1 }, policy: { type: 'object' } },
+  },
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+
+function response(id, result) { return { jsonrpc: '2.0', id, result }; }
+function error(id, code, message) { return { jsonrpc: '2.0', id: id ?? null, error: { code, message } }; }
+
+function dispatch(message) {
+  if (!message || message.jsonrpc !== '2.0' || typeof message.method !== 'string') return error(message?.id, -32600, 'Invalid Request');
+  if (message.id === undefined) return null;
+  if (message.method === 'initialize') return response(message.id, {
+    protocolVersion: message.params?.protocolVersion || '2025-06-18', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'sando', version: '0.1.0' },
+  });
+  if (message.method === 'ping') return response(message.id, {});
+  if (message.method === 'tools/list') return response(message.id, { tools: [TOOL] });
+  if (message.method === 'tools/call') {
+    if (message.params?.name !== TOOL.name) return error(message.id, -32602, 'Unknown tool');
+    try {
+      const result = optimizeToolOutput(message.params.arguments);
+      return response(message.id, { content: [{ type: 'text', text: result.inline }], structuredContent: result, isError: false });
+    } catch (cause) {
+      return response(message.id, { content: [{ type: 'text', text: cause instanceof Error ? cause.message : 'invalid tool input' }], isError: true });
+    }
+  }
+  return error(message.id, -32601, 'Method not found');
+}
+
+export function startMcpServer() {
+  const lines = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  lines.on('line', (line) => {
+    let output;
+    try { output = dispatch(JSON.parse(line)); } catch { output = error(null, -32700, 'Parse error'); }
+    if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
+  });
+}