troxy-cli 1.29.23 → 1.29.25

package/bin/troxy.js

@@ -277,6 +277,13 @@ switch (command) {
     break;
   }
 
+  // posttooluse-hook.js for tool-output sandboxing.
+  case 'posttooluse-hook': {
+    const { runPostToolUseHook } = await import('../src/sandbox/posttooluse-hook.js');
+    await runPostToolUseHook();
+    break;
+  }
+
   // ── Heartbeat daemon (background service) ─────────────────────
   case 'daemon': {
     const { runDaemon } = await import('../src/daemon.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "troxy-cli",
-  "version": "1.29.23",
+  "version": "1.29.25",
   "description": "A secure control layer for AI agents: policies across payments, messages, logins, destructive actions, model usage, and secrets, all enforceable from the CLI",
   "homepage": "https://troxy.io",
   "bugs": {

package/src/init.js

@@ -142,7 +142,7 @@ export async function reprovisionKeyConsumers(key, agentName, proxyOptIn = null,
     }
     if (hasClaude || hasDesktop) {
       try {
-        patchClaudeCodeHooks(claudeCodeSettingsPath());
+        _patchClaudeCodeHooksFile(claudeCodeSettingsPath());
         console.log(`    • Claude Code usage capture (all projects)  ✓`);
       } catch (err) {
         console.log(`    • Claude Code usage capture  ✗  (${err.message})`);
@@ -174,16 +174,24 @@ export async function reprovisionKeyConsumers(key, agentName, proxyOptIn = null,
 
   console.log('\n  Setting up background service...');
   const viaEphemeralNpx = ranViaEphemeralNpx();
-  try {
-    installService(key, agentName);
-    console.log('  Background service installed  ✓');
-    if (viaEphemeralNpx) printPersistentInstallHint();
-  } catch (err) {
-    console.log(`  Background service  ✗  (${err.message})`);
-    if (viaEphemeralNpx) {
-      printPersistentInstallHint();
-    } else {
-      console.log('  You can start it manually with: troxy daemon &');
+  // Test-only escape hatch: lets tests exercise reprovisionKeyConsumers's
+  // hook-patching logic end to end without installService ever running -
+  // i.e. without touching the real launchd/systemd service on the host
+  // machine. Never set in production; see init-sandbox-hook.test.js.
+  if (process.env.TROXY_TEST_SKIP_SERVICE_INSTALL === '1') {
+    console.log('  Background service  ✗  (skipped: TROXY_TEST_SKIP_SERVICE_INSTALL=1)');
+  } else {
+    try {
+      installService(key, agentName);
+      console.log('  Background service installed  ✓');
+      if (viaEphemeralNpx) printPersistentInstallHint();
+    } catch (err) {
+      console.log(`  Background service  ✗  (${err.message})`);
+      if (viaEphemeralNpx) {
+        printPersistentInstallHint();
+      } else {
+        console.log('  You can start it manually with: troxy daemon &');
+      }
     }
   }
 
@@ -793,6 +801,10 @@ export function troxyPreToolUseCommand() {
   return `${_resolveTroxyBin()} pretooluse-hook`;
 }
 
+export function troxyPostToolUseCommand() {
+  return `${_resolveTroxyBin()} posttooluse-hook`;
+}
+
 // Shared by patchClaudeCodeHooks and unpatchClaudeCodeHooks, so "what counts
 // as a Troxy-owned hook entry" has exactly one definition.
 function _isTroxyStopEntry(matcherEntry) {
@@ -803,14 +815,18 @@ function _isTroxyPreToolUseEntry(matcherEntry) {
   return Array.isArray(matcherEntry?.hooks) &&
     matcherEntry.hooks.some(h => typeof h?.command === 'string' && h.command.includes('pretooluse-hook'));
 }
+export function _isTroxyPostToolUseEntry(matcherEntry) {
+  return Array.isArray(matcherEntry?.hooks) &&
+    matcherEntry.hooks.some(h => typeof h?.command === 'string' && h.command.includes('posttooluse-hook'));
+}
 
 export function patchClaudeCodeHooks(
-  configPath,
+  config,
+  options = {},
+  // legacy parameters for backward compat (unused; stopCommand and preToolUseCommand defaulted previously)
   stopCommand = troxyHookCommand(),
   preToolUseCommand = troxyPreToolUseCommand(),
 ) {
-  let config = {};
-  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
   if (!config.hooks) config.hooks = {};
 
   if (!Array.isArray(config.hooks.Stop)) config.hooks.Stop = [];
@@ -832,22 +848,49 @@ export function patchClaudeCodeHooks(
   if (preIdx >= 0) config.hooks.PreToolUse[preIdx] = preToolUseEntry;
   else config.hooks.PreToolUse.push(preToolUseEntry);
 
-  fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  // PostToolUse hook for tool-output sandboxing - always installed, unconditional
+  // (no opt-out: the `options` param is kept only for legacy call-signature compat).
+  if (!Array.isArray(config.hooks.PostToolUse)) config.hooks.PostToolUse = [];
+  const postToolUseCommand = troxyPostToolUseCommand();
+  const postToolUseEntry = { matcher: '*', hooks: [{ type: 'command', command: postToolUseCommand, timeout: 5 }] };
+  const postIdx = config.hooks.PostToolUse.findIndex(_isTroxyPostToolUseEntry);
+  if (postIdx >= 0) config.hooks.PostToolUse[postIdx] = postToolUseEntry;
+  else config.hooks.PostToolUse.push(postToolUseEntry);
+
+  return config;
 }
 
 // Uninstall symmetry (fail-open layer 6 in the plan doc): removes exactly
-// the Troxy-owned Stop/PreToolUse entries, leaving any of the user's own
+// the Troxy-owned Stop/PreToolUse/PostToolUse entries, leaving any of the user's own
 // unrelated hooks in the same file untouched.
-export function unpatchClaudeCodeHooks(configPath) {
-  let config = {};
-  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch { return; }
+export function unpatchClaudeCodeHooks(config) {
   if (Array.isArray(config.hooks?.Stop)) {
     config.hooks.Stop = config.hooks.Stop.filter(e => !_isTroxyStopEntry(e));
   }
   if (Array.isArray(config.hooks?.PreToolUse)) {
     config.hooks.PreToolUse = config.hooks.PreToolUse.filter(e => !_isTroxyPreToolUseEntry(e));
   }
+  if (Array.isArray(config.hooks?.PostToolUse)) {
+    config.hooks.PostToolUse = config.hooks.PostToolUse.filter(e => !_isTroxyPostToolUseEntry(e));
+  }
+  return config;
+}
+
+// File-based wrappers (for call sites that operate directly on file paths,
+// e.g. uninstall.js's symmetrical teardown). The exported pure functions
+// above (operating on an in-memory config object) are what's unit-tested.
+export function _patchClaudeCodeHooksFile(configPath, options = {}) {
+  let config = {};
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  config = patchClaudeCodeHooks(config, options);
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+export function _unpatchClaudeCodeHooksFile(configPath) {
+  let config = {};
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch { return; }
+  config = unpatchClaudeCodeHooks(config);
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 }
 

package/src/interceptor.js

@@ -30,6 +30,10 @@ import net from 'node:net';
 import tls from 'node:tls';
 import http from 'node:http';
 import https from 'node:https';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { sessionArmPath } from './sandbox/posttooluse-hook.js';
 
 // Found live 2026-09-08, first real terminal validation of this whole
 // mechanism: a real `claude` process opens a burst of ~15 concurrent
@@ -93,7 +97,45 @@ export function detectSurface(incomingHeaders) {
  * rides the side channel app.py already knows how to consume
  * (X-Troxy-Upstream-Authorization), while Authorization itself becomes the
  * Troxy key, matching how app.py authenticates every other proxied call. */
-export function buildTroxyForwardHeaders(incomingHeaders, troxyKey) {
+// Freshness window for the sandbox holdout/treatment state file written by
+// the Task 3 hook after each tool call - a stale file (daemon restarted,
+// hook not firing, clock skew) must never be reported as live state, so the
+// header is omitted entirely rather than forwarding a stale value.
+const _SANDBOX_STATE_FRESHNESS_MS = 2 * 60 * 1000;
+const _DEFAULT_SANDBOX_STATE_DIR = path.join(os.homedir(), '.troxy', 'sandbox');
+
+// Returns the hook's last recorded state ('treated' | 'holdout' | 'skipped')
+// if the state file exists, parses, and was written within the freshness
+// window - null otherwise (missing file, stale, unreadable, malformed).
+// Never throws: this is a best-effort read on the hot request path.
+function _readFreshSandboxState(sandboxStateDir) {
+  try {
+    const filePath = path.join(sandboxStateDir, 'last-state.json');
+    const stat = fs.statSync(filePath);
+    if (Date.now() - stat.mtimeMs > _SANDBOX_STATE_FRESHNESS_MS) return null;
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed.state || null;
+  } catch {
+    return null;
+  }
+}
+
+// The session's A/B arm written by the PostToolUse hook, keyed by the
+// X-Claude-Code-Session-Id header Claude Code sends on every API request.
+// A session property, so no freshness window. null when the header is
+// missing/invalid or the session hasn't run a tool yet.
+function _readSessionArm(sandboxStateDir, sessionId) {
+  try {
+    const file = sessionArmPath(sandboxStateDir, sessionId);
+    if (!file) return null;
+    const arm = JSON.parse(fs.readFileSync(file, 'utf8')).arm;
+    return arm === 'treated' || arm === 'holdout' ? arm : null;
+  } catch {
+    return null;
+  }
+}
+
+export function buildTroxyForwardHeaders(incomingHeaders, troxyKey, sandboxStateDir = _DEFAULT_SANDBOX_STATE_DIR) {
   const headers = {};
   for (const [k, v] of Object.entries(incomingHeaders)) {
     if (_HOP_BY_HOP_HEADERS.has(k) || k === 'authorization' || k === 'accept-encoding') continue;
@@ -104,6 +146,14 @@ export function buildTroxyForwardHeaders(incomingHeaders, troxyKey) {
   }
   const surface = detectSurface(incomingHeaders);
   if (surface) headers['x-troxy-surface'] = surface;
+  // With a session header, only that session's own arm counts (a session
+  // with no tool call yet stays untagged rather than borrowing another
+  // session's state). Legacy shared last-state only when there's no header.
+  const sessionFile = sessionArmPath(sandboxStateDir, incomingHeaders['x-claude-code-session-id']);
+  const sandboxState = sessionFile
+    ? _readSessionArm(sandboxStateDir, incomingHeaders['x-claude-code-session-id'])
+    : _readFreshSandboxState(sandboxStateDir);
+  if (sandboxState) headers['x-troxy-tool-sandbox'] = sandboxState;
   headers.authorization = `Bearer ${troxyKey}`;
   return headers;
 }

package/src/mcp-server.js

@@ -6,6 +6,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { loadConfig }      from './config.js';
 import { evaluatePayment, api } from './api.js';
+import { get as sandboxGet, storeDir } from './sandbox/store.js';
 const confirmPayment = (auditId, body, apiKey) => api.confirmPayment(auditId, body, apiKey);
 const evaluateEmail   = (body, apiKey) => api.evaluateEmail(body, apiKey);
 const evaluateLogin   = (body, apiKey) => api.evaluateLogin(body, apiKey);
@@ -20,6 +21,14 @@ const reportModelUsage = (body, apiKey) => api.reportModelUsage(body, apiKey);
 // agent whose only way to reach Troxy is through the tools listed here.
 const evaluateSecrets = (body, apiKey) => api.evaluateSecrets(body, apiKey);
 
+export async function handleRecall(args, dir = storeDir()) {
+  const content = await sandboxGet(args.handle, dir);
+  if (content === null) {
+    return { content: [{ type: 'text', text: `Troxy error: handle "${args.handle}" not found (it may have expired).` }], isError: true };
+  }
+  return { content: [{ type: 'text', text: content }], isError: false };
+}
+
 export async function runMcp() {
   const config    = loadConfig();
   const apiKey    = process.env.TROXY_API_KEY || config?.apiKey;
@@ -279,6 +288,20 @@ export async function runMcp() {
           },
         },
       },
+      {
+        name: 'troxy_recall',
+        description:
+          'Fetch the full content behind a troxy_recall(...) handle shown after a large tool ' +
+          'output was compressed. Use this when the summary you were shown doesn\'t have the ' +
+          'detail you need.',
+        inputSchema: {
+          type: 'object',
+          required: ['handle'],
+          properties: {
+            handle: { type: 'string', description: 'The handle shown in the compressed output, e.g. "a1b2c3d4e5f6a7b8"' },
+          },
+        },
+      },
       {
         name: 'evaluate_login',
         description:
@@ -565,6 +588,10 @@ export async function runMcp() {
       return { content: [{ type: 'text', text: actionText }], isError: decision === 'BLOCK' };
     }
 
+    if (toolName === 'troxy_recall') {
+      return handleRecall(args);
+    }
+
     if (toolName === 'evaluate_model') {
       if (agentName && !args.agent) args.agent = agentName;
       let result;

package/src/sandbox/compress.js

@@ -0,0 +1,52 @@
+const SANDBOX_THRESHOLD = 2000;
+const MAX_SIGNAL_LINES = 20;
+const CHAR_EDGE = 250;
+
+// Covers: pytest failures (FAILED), jest failures (FAIL file summary + ✕ marker),
+// go test failures (--- FAIL:), git/docker fatal errors, generic + fused
+// exception names (ValueError:, NullPointerException - no word boundary
+// required before the keyword since real exceptions fuse it to a prefix),
+// python traceback headers and frame lines, and go/rust panics.
+const SIGNAL_PATTERNS = [
+  /\bFAILED\b/,
+  /^FAIL\b/,
+  /✕/,
+  /--- FAIL:/,
+  /Error:/,
+  /Exception\b/i,
+  /\bfatal:/i,
+  /Traceback \(most recent call last\)/,
+  /File ".*", line \d+/,
+  /panic:/,
+  /panicked at/,
+];
+
+export function shouldSandbox(output) {
+  return typeof output === 'string' && output.length > SANDBOX_THRESHOLD;
+}
+
+export function summarize(output) {
+  const lines = output.split('\n');
+  const signalLines = lines.filter((line) => SIGNAL_PATTERNS.some((p) => p.test(line)));
+
+  if (signalLines.length > 0) {
+    const kept = signalLines.slice(0, MAX_SIGNAL_LINES).join('\n');
+    const truncationNote = signalLines.length > MAX_SIGNAL_LINES
+      ? ` (showing ${MAX_SIGNAL_LINES} of ${signalLines.length} matching lines)`
+      : '';
+    return `${kept}\n\n(${lines.length} lines, ${output.length} chars total - use troxy_recall to see the rest)${truncationNote}`;
+  }
+
+  // Line-based head+tail slicing duplicates content when there are few
+  // enough lines for the two slices to overlap (e.g. one giant minified-JSON
+  // line) - fall back to character-based truncation of the raw string.
+  if (lines.length <= 6) {
+    const head = output.slice(0, CHAR_EDGE);
+    const tail = output.slice(-CHAR_EDGE);
+    return `${head}\n...\n${tail}\n\n(${output.length} chars omitted - use troxy_recall to see all of it)`;
+  }
+
+  const head = lines.slice(0, 3).join('\n');
+  const tail = lines.slice(-3).join('\n');
+  return `${head}\n...\n${tail}\n\n(${lines.length} lines, ${output.length} chars omitted - use troxy_recall to see all of it)`;
+}

package/src/sandbox/posttooluse-hook.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import fs   from 'node:fs';
+import path from 'node:path';
+import { shouldSandbox, summarize } from './compress.js';
+import { put, storeDir as defaultStoreDir } from './store.js';
+
+const STDIN_TIMEOUT_MS = 2000;
+
+// Per-session A/B arm. The measurement compares whole sessions, so the
+// holdout draw happens once per Claude Code session_id, not per tool call:
+// a per-call draw leaves both arms with near-identical context (every
+// "holdout" request still carries earlier compressed outputs), which
+// measures ~0 whatever the real effect is. The interceptor reads this same
+// file by the X-Claude-Code-Session-Id request header to tag each request
+// with its own session's arm.
+// ponytail: one tiny file per session, never pruned; add cleanup if ~/.troxy/sandbox/sessions gets large.
+const SESSION_ID_RE = /^[A-Za-z0-9-]{8,128}$/;
+
+export function sessionArmPath(dir, sessionId) {
+  if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) return null;
+  return path.join(dir, 'sessions', `${sessionId}.json`);
+}
+
+function sessionArm(dir, sessionId, holdoutFraction, randomFn) {
+  const file = sessionArmPath(dir, sessionId);
+  if (!file) return null;
+  try {
+    const arm = JSON.parse(fs.readFileSync(file, 'utf8')).arm;
+    if (arm === 'treated' || arm === 'holdout') return arm;
+  } catch { /* first tool call of this session, or unreadable: draw below */ }
+  const arm = randomFn() < holdoutFraction ? 'holdout' : 'treated';
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ arm }));
+  } catch {
+    return null; // can't persist the arm, so fall back to the per-call path
+  }
+  return arm;
+}
+
+function writeState(dir, state) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'last-state.json'), JSON.stringify({ state }));
+  } catch {
+    // Fails open - a state-file write failure must never surface as a hook error.
+  }
+}
+
+// Real tool_response shapes, confirmed against this machine's own
+// ~/.claude/projects/*/*.jsonl transcripts (not the invented `.output`
+// field this file originally assumed - that field does not exist on any
+// real tool result; see the 2026-10-05 whole-branch review for the
+// incident this fixes). Bash/Bash-like tools dominate real traffic and
+// carry the text in `stdout`; Read nests it under `file.content`; Write/
+// Edit-created-file results carry it directly on `content`. Anything else
+// (Grep's `matches` list, bare strings from MCP tools, structured Edit
+// diffs, etc.) is left untouched rather than guessed at, since a wrong
+// guess here means Claude Code rejects updatedToolOutput against the
+// tool's own schema and reverts to the original output anyway - a correct
+// no-op is strictly better than an incorrect one that also surfaces a
+// visible hook error.
+function extractText(toolResponse) {
+  if (typeof toolResponse === 'string') return toolResponse;
+  if (toolResponse && typeof toolResponse === 'object') {
+    if (typeof toolResponse.stdout === 'string') return toolResponse.stdout;
+    if (toolResponse.file && typeof toolResponse.file.content === 'string') return toolResponse.file.content;
+    if (typeof toolResponse.content === 'string') return toolResponse.content;
+  }
+  return null;
+}
+
+// Mirrors extractText's shape-matching exactly, replacing only the text
+// field so the rest of the real object (stderr, filePath, structuredPatch,
+// etc.) reaches Claude unchanged and passes the tool's own output schema.
+function rebuildWithText(toolResponse, text) {
+  if (typeof toolResponse === 'string') return text;
+  if (toolResponse.file && typeof toolResponse.file.content === 'string') {
+    return { ...toolResponse, file: { ...toolResponse.file, content: text } };
+  }
+  if (typeof toolResponse.stdout === 'string') {
+    return { ...toolResponse, stdout: text };
+  }
+  return { ...toolResponse, content: text };
+}
+
+export async function buildHookResponse(toolUseBlock, {
+  sandboxFraction = 1,
+  holdoutFraction = 0.2,
+  randomFn = Math.random,
+  storeDir = defaultStoreDir(),
+} = {}) {
+  const toolResponse = toolUseBlock?.tool_response;
+  const arm = sessionArm(storeDir, toolUseBlock?.session_id, holdoutFraction, randomFn);
+  if (arm === 'holdout') {
+    writeState(storeDir, 'holdout');
+    return undefined;
+  }
+  const output = extractText(toolResponse);
+  if (output === null || !shouldSandbox(output)) {
+    writeState(storeDir, 'skipped');
+    return undefined;
+  }
+
+  // No session arm (hook input without session_id): legacy per-call draw.
+  if (!arm && randomFn() < sandboxFraction && randomFn() < holdoutFraction) {
+    writeState(storeDir, 'holdout');
+    return undefined;
+  }
+  if (!arm && randomFn() >= sandboxFraction) {
+    writeState(storeDir, 'skipped');
+    return undefined;
+  }
+
+  try {
+    const summary = summarize(output);
+    const { handle } = await put(output, { summary, tags: [] }, storeDir);
+    writeState(storeDir, 'treated');
+    const updatedText = `${summary}\n\n(troxy_recall("${handle}") to fetch the full output)`;
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        updatedToolOutput: rebuildWithText(toolResponse, updatedText),
+      },
+    };
+  } catch {
+    // Fail open: storage broke, show the real output rather than losing it.
+    writeState(storeDir, 'skipped');
+    return undefined;
+  }
+}
+
+async function readStdin(timeoutMs) {
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+  });
+}
+
+// Exported entry point - invoked both by bin/troxy.js's dynamic import
+// (`troxy posttooluse-hook`, registered via patchClaudeCodeHooks in
+// init.js) and, below, by this file's own direct-execution guard.
+export async function runPostToolUseHook() {
+  try {
+    const raw = await readStdin(STDIN_TIMEOUT_MS);
+    const input = JSON.parse(raw);
+    const response = await buildHookResponse(input);
+    if (response) process.stdout.write(JSON.stringify(response));
+  } catch {
+    // Fail open on any parse/unexpected error - never block the real tool output.
+  }
+  process.exit(0);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) runPostToolUseHook();

package/src/sandbox/store.js

@@ -0,0 +1,90 @@
+import fs   from 'node:fs';
+import os   from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export function storeDir() {
+  return path.join(os.homedir(), '.troxy', 'sandbox');
+}
+
+function indexPath(dir) {
+  return path.join(dir, 'index.json');
+}
+
+// A plain exclusive-create lockfile, retried with backoff - no new dependency,
+// good enough for a handful of concurrent Claude Code sessions on one machine.
+async function withIndexLock(dir, fn) {
+  const lockPath = path.join(dir, 'index.lock');
+  fs.mkdirSync(dir, { recursive: true });
+  let acquired = false;
+  for (let attempt = 0; attempt < 50; attempt++) {
+    try {
+      fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      await new Promise((r) => setTimeout(r, 10 + Math.random() * 20));
+      if (attempt === 49) {
+        fs.rmSync(lockPath, { force: true }); // stale lock (original holder presumed dead) - steal it
+        try {
+          fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+          acquired = true;
+        } catch (err2) {
+          // ponytail: another process won the just-stolen slot - rare double-steal race.
+          // Proceed unprotected rather than hang forever; upgrade to a PID-liveness check if this bites.
+          if (err2.code !== 'EEXIST') throw err2;
+        }
+      }
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    if (acquired) fs.rmSync(lockPath, { force: true });
+  }
+}
+
+function readIndex(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(indexPath(dir), 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+export async function put(content, { summary, tags = [] }, dir = storeDir()) {
+  fs.mkdirSync(dir, { recursive: true });
+  const handle = crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+  fs.writeFileSync(path.join(dir, `${handle}.txt`), content, 'utf8');
+  await withIndexLock(dir, () => {
+    const index = readIndex(dir);
+    index.push({ handle, summary, tags, createdAt: new Date().toISOString(), size: content.length });
+    fs.writeFileSync(indexPath(dir), JSON.stringify(index));
+  });
+  return { handle, bytesSaved: Math.max(0, content.length - summary.length) };
+}
+
+// The handle is agent-controlled (the model supplies it as a troxy_recall
+// argument), so it must be validated before touching the filesystem - a
+// handle like "../../../etc/passwd" would otherwise let a prompt-injected
+// tool call read any file the process can see. Real handles are always a
+// 16-char lowercase hex digest (see put()); reject anything else outright.
+const HANDLE_PATTERN = /^[0-9a-f]{16}$/;
+
+export async function get(handle, dir = storeDir()) {
+  if (typeof handle !== 'string' || !HANDLE_PATTERN.test(handle)) return null;
+  try {
+    return fs.readFileSync(path.join(dir, `${handle}.txt`), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export async function search(query, dir = storeDir()) {
+  const needle = query.toLowerCase();
+  const index = readIndex(dir);
+  const hits = index.filter((e) =>
+    e.summary.toLowerCase().includes(needle) || e.tags.some((t) => t.toLowerCase().includes(needle)));
+  return hits.slice(-5).reverse().map(({ handle, summary }) => ({ handle, summary }));
+}