troxy-cli 1.29.24 → 1.29.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "troxy-cli",
-  "version": "1.29.24",
+  "version": "1.29.26",
   "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

@@ -11,6 +11,32 @@ import { enabledProviders, interceptHostsFor } from './providers.js';
 import { probePort } from './proxy.js';
 import { launchdUserDomain } from './launchd.js';
 import { reclaimOwnership } from './sudo-ownership.js';
+import { fileURLToPath } from 'url';
+import { detectInstalledClaudeCodeVersion, supportsMods } from './mods/version-check.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TROXY_GUARD_MOD_SOURCE_DIR = path.join(__dirname, 'mods', 'troxy-guard');
+
+// mods-policy-engine plan (2026-10-06), Task 4. Mods need Claude Code >=2.1.287
+// - installing unconditionally would silently do nothing (or worse, leave an
+// inert directory) on anyone still on an older version (e.g. the Homebrew
+// cask, which was still frozen at 2.1.285 as of 2026-10-06 even after
+// `brew update` - see project_claude_code_mods_investigation memory). A
+// plugin dropped into ~/.claude/skills/<name>/ loads automatically with zero
+// flags and zero settings.json edits - verified directly against a real
+// session, not assumed from docs.
+export async function installTroxyGuardMod(home = os.homedir(), detectFn = detectInstalledClaudeCodeVersion) {
+  const version = await detectFn();
+  if (!version || !supportsMods(`${version.major}.${version.minor}.${version.patch}`)) return false;
+  const destDir = path.join(home, '.claude', 'skills', 'troxy-guard');
+  fs.rmSync(destDir, { recursive: true, force: true });
+  fs.cpSync(TROXY_GUARD_MOD_SOURCE_DIR, destDir, { recursive: true });
+  return true;
+}
+
+export function uninstallTroxyGuardMod(home = os.homedir()) {
+  fs.rmSync(path.join(home, '.claude', 'skills', 'troxy-guard'), { recursive: true, force: true });
+}
 
 // `npx troxy-cli@latest <cmd>` puts a `troxy` shim on PATH only for that one
 // child process (npx's own temp-PATH trick) - it never installs a persistent
@@ -147,6 +173,14 @@ export async function reprovisionKeyConsumers(key, agentName, proxyOptIn = null,
       } catch (err) {
         console.log(`    • Claude Code usage capture  ✗  (${err.message})`);
       }
+      try {
+        const installed = await installTroxyGuardMod();
+        console.log(installed
+          ? `    • Troxy policy engine (terminal + Desktop)  ✓`
+          : `    • Troxy policy engine  -  (needs Claude Code 2.1.287+, skipped)`);
+      } catch (err) {
+        console.log(`    • Troxy policy engine  ✗  (${err.message})`);
+      }
     }
     if (hasClaude) {
       // Terminal used to get base-URL substitution (maybeEnableClaudeCodeProxy)

package/src/interceptor.js

@@ -33,6 +33,7 @@ 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
@@ -119,6 +120,21 @@ function _readFreshSandboxState(sandboxStateDir) {
   }
 }
 
+// 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)) {
@@ -130,7 +146,13 @@ export function buildTroxyForwardHeaders(incomingHeaders, troxyKey, sandboxState
   }
   const surface = detectSurface(incomingHeaders);
   if (surface) headers['x-troxy-surface'] = surface;
-  const sandboxState = _readFreshSandboxState(sandboxStateDir);
+  // 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/mods/troxy-guard/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "troxy-guard",
+  "version": "0.1.0",
+  "description": "Troxy's policy engine, enforcing your org's ALLOW/BLOCK/ESCALATE rules on every tool call."
+}

package/src/mods/troxy-guard/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.js"] }

package/src/mods/troxy-guard/hooks/register.js

@@ -0,0 +1,158 @@
+const POLICY_CHECK_URL = 'https://api.troxy.io/agent/policy-check';
+const TIMEOUT_MS = 5000;
+
+function toDomainAndFields(e) {
+  // Mapping a real Bash command to structured policy fields (which domain,
+  // which action_verb/resource) is deliberately out of scope for this first
+  // build - see the plan's "Explicitly out of scope" section. Returning null
+  // here is a safe no-op: the existing proxy remains the backstop for every
+  // real Bash action until a later plan adds real command classification.
+  return null;
+}
+
+async function guardBash($, e, next) {
+  const mapped = _internal.toDomainAndFields(e);
+  if (!mapped) return next(e);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  let result;
+  try {
+    const res = await $.http.fetch(POLICY_CHECK_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ domain: mapped.domain, fields: mapped.fields }),
+      signal: controller.signal,
+    });
+    result = res.ok ? await res.json() : { decision: 'ESCALATE', reason: 'policy service returned an error' };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (result.decision === 'BLOCK') {
+    return { deny: 'Blocked by your org\'s Troxy policy' + (result.policy_id ? ' (' + result.policy_id + ')' : '') };
+  }
+  if (result.decision === 'ESCALATE') {
+    const answer = await $.ui.ask('Troxy: ' + (result.reason || 'this action needs your approval') + '. Allow it?', { choices: ['Allow', 'Deny'] });
+    if (answer !== 'Allow') return { deny: 'Denied by you after a Troxy escalation.' };
+  }
+  return next(e);
+}
+
+async function failClosed($, e, next, err) {
+  // Registered via .catch() below - this runs if guardBash throws, or if
+  // Claude Code decides the hook exceeded its time budget and would otherwise
+  // just skip it. A skipped policy hook must never silently mean "allow".
+  return { deny: 'Troxy could not evaluate this action (' + err.message + ') - denied by default rather than allowed.' };
+}
+
+// --- Routing: extend the usage bar by sending easy prompts to a cheaper model.
+//
+// Ported from the proxy's scorer (troxy-tf-live model-proxy/app.py: bands,
+// never-upward rule, 50k context floor for Haiku). The mod scores each human
+// prompt once with the user's own session via $.model.complete, so there is no
+// Troxy round trip and no credential to carry. One decision per prompt, applied
+// to every step of its turn, so the cache prefix stays stable within a turn.
+
+const MODELS = {
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-5-5',
+  opus: 'claude-opus-5-5',
+};
+const RANK = { haiku: 0, sonnet: 1, opus: 2 };
+const BANDS = [[0.1, 'haiku'], [0.6, 'sonnet'], [0.8, 'opus']];
+const HAIKU_CONTEXT_FLOOR_TOKENS = 50000;
+const SCORE_TIMEOUT_MS = 3000;
+const SCORER_PROMPT_CHARS = 4000;
+const SCORER_SYSTEM = 'You are a routing classifier for a coding-assistant proxy. Read the request below '
+  + 'and reply with ONLY a number between 0.0 and 1.0 estimating how much reasoning or '
+  + 'capability it needs: 0.0 for trivial/routine work a small fast model handles fine, '
+  + '1.0 for something that genuinely needs the most capable model available. '
+  + 'Reply with the number and nothing else - no words, no punctuation.';
+
+function tierOf(model) {
+  const m = String(model || '').toLowerCase();
+  for (const t of Object.keys(RANK)) if (m.includes(t)) return t;
+  return null;
+}
+
+function parseScore(text) {
+  const m = /\d*\.?\d+/.exec(String(text || ''));
+  if (!m) return null;
+  const n = Number(m[0]);
+  return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : null;
+}
+
+function pickModel(score, requested, contextTokens) {
+  const rq = tierOf(requested);
+  if (rq === null) return requested; // unknown family (e.g. a newer tier): leave it alone
+  let tier = rq;
+  for (const [limit, name] of BANDS) {
+    if (score <= limit) { if (RANK[name] < RANK[rq]) tier = name; break; }
+  }
+  if (tier === 'haiku' && rq !== 'haiku' && contextTokens > HAIKU_CONTEXT_FLOOR_TOKENS) {
+    tier = RANK.sonnet < RANK[rq] ? 'sonnet' : rq;
+  }
+  return tier === rq ? requested : MODELS[tier];
+}
+
+// /troxy off|on|status. Pure so it can be tested; the hook below stores the result.
+function troxyCommand(args, paused) {
+  const a = String(args || '').trim().toLowerCase();
+  if (a === 'off') return { paused: true, text: 'Troxy routing is off. Your chosen model is used as-is. Type /troxy on to resume.' };
+  if (a === 'on') return { paused: false, text: 'Troxy routing is on.' };
+  return { paused, text: paused ? 'Troxy routing is off. Type /troxy on to resume.' : 'Troxy routing is on. Type /troxy off to pause it.' };
+}
+
+// Whether this session has shown its one "Troxy is active" notice yet.
+let announced = false;
+
+// The decision for the turn in flight: { score, tokens } or null (no change).
+let decision = null;
+
+async function scorePrompt($, e, next) {
+  decision = null;
+  if (await $.store.get('paused')) return next(e);
+  const kind = e.origin && e.origin.kind;
+  if (kind !== 'composer' && kind !== 'bridge' && kind !== 'sdk') return next(e);
+  const r = await $.model.complete(
+    { model: 'haiku', system: SCORER_SYSTEM, prompt: e.text.slice(0, SCORER_PROMPT_CHARS), maxTokens: 8, effort: 'low', timeoutMs: SCORE_TIMEOUT_MS },
+  );
+  const score = r.isAnswered ? parseScore(r.text) : null;
+  if (score !== null) {
+    const u = await $.session.usage();
+    decision = { score, tokens: u.context ? u.context.tokens : 0 };
+  }
+  return next(e);
+}
+
+async function* routeStep($, e, next) {
+  // Main loop only: a subagent keeps whatever model it was given.
+  if (!decision || e.agentId) return yield* next(e);
+  const model = pickModel(decision.score, e.model, decision.tokens);
+  if (model !== e.model && !announced) {
+    announced = true;
+    $.ui.toast('Troxy is active');
+  }
+  return yield* next(model === e.model ? e : { ...e, model });
+}
+
+export function register(on) {
+  on('tool.call', { tool: 'Bash' }, guardBash).catch(failClosed);
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'troxy', description: 'Pause or resume Troxy model routing', argumentHint: '[on|off|status]' });
+    return next(e);
+  });
+  on('command.run', { command: 'troxy' }, async ($, e) => {
+    const r = troxyCommand(e.args, Boolean(await $.store.get('paused')));
+    await $.store.set('paused', r.paused);
+    return { text: r.text };
+  });
+  // Routing fails open: a scorer or hook error must never break the session,
+  // it just means the requested model is used as-is.
+  on('prompt.submit', scorePrompt).catch(($, e, next) => { decision = null; return next(e); });
+  on('turn.step', routeStep).catch(async function* ($, e, next) { return yield* next(e); });
+}
+
+// Exported for tests only - not part of the mod's runtime contract.
+export const _internal = { toDomainAndFields, guardBash, failClosed, parseScore, pickModel, troxyCommand, MODELS };

package/src/mods/troxy-guard/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json"
+}

package/src/mods/version-check.js

@@ -0,0 +1,24 @@
+import { execFileSync } from 'node:child_process';
+
+export function supportsMods(versionString) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(versionString || '').trim());
+  if (!m) return false;
+  const actual = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const floor = [2, 1, 287];
+  for (let i = 0; i < 3; i++) {
+    if (actual[i] > floor[i]) return true;
+    if (actual[i] < floor[i]) return false;
+  }
+  return true;
+}
+
+export async function detectInstalledClaudeCodeVersion(execFn = execFileSync) {
+  try {
+    const out = execFn('claude', ['--version'], { encoding: 'utf8' });
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(out.trim());
+    if (!m) return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+  } catch {
+    return null;
+  }
+}

package/src/sandbox/posttooluse-hook.js

@@ -6,6 +6,38 @@ 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 });
@@ -59,17 +91,23 @@ export async function buildHookResponse(toolUseBlock, {
   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;
   }
 
-  if (randomFn() < sandboxFraction && randomFn() < holdoutFraction) {
+  // No session arm (hook input without session_id): legacy per-call draw.
+  if (!arm && randomFn() < sandboxFraction && randomFn() < holdoutFraction) {
     writeState(storeDir, 'holdout');
     return undefined;
   }
-  if (randomFn() >= sandboxFraction) {
+  if (!arm && randomFn() >= sandboxFraction) {
     writeState(storeDir, 'skipped');
     return undefined;
   }

package/src/tests/init-mods.test.js

@@ -0,0 +1,76 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { installTroxyGuardMod, uninstallTroxyGuardMod } from '../init.js';
+
+test('installTroxyGuardMod: copies the mod when the version supports it', async () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mod-home-'));
+  try {
+    const installed = await installTroxyGuardMod(tmpHome, async () => ({ major: 2, minor: 1, patch: 289 }));
+    assert.equal(installed, true);
+    assert.ok(fs.existsSync(path.join(tmpHome, '.claude', 'skills', 'troxy-guard', '.claude-plugin', 'plugin.json')));
+    assert.ok(fs.existsSync(path.join(tmpHome, '.claude', 'skills', 'troxy-guard', 'hooks', 'register.js')));
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+test('installTroxyGuardMod: skips silently below the version floor', async () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mod-home-'));
+  try {
+    const installed = await installTroxyGuardMod(tmpHome, async () => ({ major: 2, minor: 1, patch: 285 }));
+    assert.equal(installed, false);
+    assert.ok(!fs.existsSync(path.join(tmpHome, '.claude', 'skills', 'troxy-guard')));
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+test('installTroxyGuardMod: skips silently when Claude Code is not found at all', async () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mod-home-'));
+  try {
+    const installed = await installTroxyGuardMod(tmpHome, async () => null);
+    assert.equal(installed, false);
+    assert.ok(!fs.existsSync(path.join(tmpHome, '.claude', 'skills', 'troxy-guard')));
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+test('installTroxyGuardMod: re-running replaces a stale copy rather than erroring on an existing directory', async () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mod-home-'));
+  try {
+    const destDir = path.join(tmpHome, '.claude', 'skills', 'troxy-guard');
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(path.join(destDir, 'stale-leftover-file.txt'), 'from a previous version');
+    await installTroxyGuardMod(tmpHome, async () => ({ major: 2, minor: 1, patch: 289 }));
+    assert.ok(fs.existsSync(path.join(destDir, '.claude-plugin', 'plugin.json')));
+    assert.ok(!fs.existsSync(path.join(destDir, 'stale-leftover-file.txt')), 'expected the stale file to be gone after a clean reinstall');
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+test('uninstallTroxyGuardMod: removes the installed mod directory', () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mod-home-'));
+  try {
+    const destDir = path.join(tmpHome, '.claude', 'skills', 'troxy-guard');
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(path.join(destDir, 'plugin.json'), '{}');
+    uninstallTroxyGuardMod(tmpHome);
+    assert.ok(!fs.existsSync(destDir));
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+test('uninstallTroxyGuardMod: a no-op (not a throw) when nothing was installed', () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mod-home-'));
+  try {
+    assert.doesNotThrow(() => uninstallTroxyGuardMod(tmpHome));
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});

package/src/tests/interceptor.test.js

@@ -653,3 +653,23 @@ describe('createInterceptor - integration, real sockets', () => {
     assert.equal(result.body, 'tunneled-because-cert-unhealthy');
   });
 });
+
+describe('buildTroxyForwardHeaders session arm', () => {
+  it('tags a request with its own session arm, ignoring another session\'s last-state', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-sandbox-'));
+    fs.mkdirSync(path.join(dir, 'sessions'));
+    fs.writeFileSync(path.join(dir, 'sessions', 'sess-aaaa-1111.json'), JSON.stringify({ arm: 'holdout' }));
+    fs.writeFileSync(path.join(dir, 'last-state.json'), JSON.stringify({ state: 'treated' }));
+    const headers = buildTroxyForwardHeaders(
+      { host: 'api.anthropic.com', 'x-claude-code-session-id': 'sess-aaaa-1111' }, 'txy-key', dir);
+    assert.equal(headers['x-troxy-tool-sandbox'], 'holdout');
+  });
+
+  it('leaves a session with no arm yet untagged, never borrowing another session\'s last-state', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-sandbox-'));
+    fs.writeFileSync(path.join(dir, 'last-state.json'), JSON.stringify({ state: 'treated' }));
+    const headers = buildTroxyForwardHeaders(
+      { host: 'api.anthropic.com', 'x-claude-code-session-id': 'sess-new-9999' }, 'txy-key', dir);
+    assert.equal('x-troxy-tool-sandbox' in headers, false);
+  });
+});

package/src/tests/mods-fallback.test.js

@@ -0,0 +1,63 @@
+import { strict as assert } from 'assert';
+import { test } from 'node:test';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { installTroxyGuardMod } from '../init.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const initJsPath = path.join(__dirname, '..', 'init.js');
+
+test('on an unsupported Claude Code version, a real troxy init completes and installs no mod, with no error', () => {
+  // A fake `claude` reporting 2.1.285 (below the 2.1.287 floor) sits first on
+  // PATH, so this does not depend on which Claude Code the machine has installed.
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mods-fallback-'));
+  try {
+    const fakeBin = path.join(tmpHome, 'fakebin');
+    fs.mkdirSync(fakeBin);
+    fs.writeFileSync(path.join(fakeBin, 'claude'), '#!/bin/sh\necho "2.1.285 (Claude Code)"\n', { mode: 0o755 });
+    fs.mkdirSync(path.join(tmpHome, '.config', 'Claude'), { recursive: true });
+    const desktopConfigPath =
+      process.platform === 'darwin'
+        ? path.join(tmpHome, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+        : path.join(tmpHome, '.config', 'claude', 'claude_desktop_config.json');
+    fs.mkdirSync(path.dirname(desktopConfigPath), { recursive: true });
+    fs.writeFileSync(desktopConfigPath, '{}');
+
+    const script = `
+      import { reprovisionKeyConsumers } from ${JSON.stringify('file://' + initJsPath)};
+      await reprovisionKeyConsumers('test-api-key-ci', 'claude-code', false, false);
+    `;
+    const scriptPath = path.join(tmpHome, 'run.mjs');
+    fs.writeFileSync(scriptPath, script);
+
+    assert.doesNotThrow(() => {
+      execFileSync(process.execPath, [scriptPath], {
+        env: { ...process.env, HOME: tmpHome, PATH: `${fakeBin}${path.delimiter}${process.env.PATH}`, TROXY_TEST_SKIP_SERVICE_INSTALL: '1' },
+        encoding: 'utf8',
+      });
+    }, 'expected a real troxy init run to complete without throwing, even though this machine is below the mods version floor');
+
+    assert.ok(
+      !fs.existsSync(path.join(tmpHome, '.claude', 'skills', 'troxy-guard')),
+      'expected no mod directory on a version below the floor',
+    );
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+test('with the mod absent entirely (the org-lockdown case), installTroxyGuardMod leaves zero files behind - the proxy remains the sole backstop', async () => {
+  // Duplicated deliberately from Task 4's own test, as this plan's named
+  // Review Focus regression, so it survives independently of that file.
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-mods-fallback-'));
+  try {
+    const installed = await installTroxyGuardMod(tmpHome, async () => null);
+    assert.equal(installed, false);
+    assert.ok(!fs.existsSync(path.join(tmpHome, '.claude', 'skills', 'troxy-guard')));
+  } finally {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});

package/src/tests/mods-route.test.js

@@ -0,0 +1,54 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { _internal } from '../mods/troxy-guard/hooks/register.js';
+
+const { parseScore, pickModel, troxyCommand, MODELS } = _internal;
+
+test('parseScore: reads a bare number and clamps to 0..1', () => {
+  assert.equal(parseScore('0.35'), 0.35);
+  assert.equal(parseScore(' 0.8\n'), 0.8);
+  assert.equal(parseScore('1.7'), 1);
+  assert.equal(parseScore('Score: 0.2'), 0.2);
+});
+
+test('parseScore: unparseable text is null so the caller keeps the requested model', () => {
+  assert.equal(parseScore(''), null);
+  assert.equal(parseScore('hard'), null);
+});
+
+test('pickModel: bands route down from opus (<=0.1 haiku, <=0.6 sonnet, <=0.8 opus)', () => {
+  assert.equal(pickModel(0.05, MODELS.opus, 1000), MODELS.haiku);
+  assert.equal(pickModel(0.4, MODELS.opus, 1000), MODELS.sonnet);
+  assert.equal(pickModel(0.7, MODELS.opus, 1000), MODELS.opus);
+  assert.equal(pickModel(0.95, MODELS.opus, 1000), MODELS.opus);
+});
+
+test('pickModel: never routes upward', () => {
+  assert.equal(pickModel(0.95, MODELS.sonnet, 1000), MODELS.sonnet);
+  assert.equal(pickModel(0.7, MODELS.haiku, 1000), MODELS.haiku);
+  assert.equal(pickModel(0.4, MODELS.haiku, 1000), MODELS.haiku);
+});
+
+test('pickModel: no haiku once the context passes the 50k floor, sonnet instead', () => {
+  assert.equal(pickModel(0.05, MODELS.opus, 60000), MODELS.sonnet);
+  assert.equal(pickModel(0.05, MODELS.sonnet, 60000), MODELS.sonnet);
+  assert.equal(pickModel(0.05, MODELS.haiku, 60000), MODELS.haiku);
+});
+
+test('pickModel: a model it does not recognise is left alone', () => {
+  assert.equal(pickModel(0.05, 'some-other-model', 1000), 'some-other-model');
+});
+
+test('pickModel: a [1m] suffix is understood when comparing tiers', () => {
+  assert.equal(pickModel(0.4, MODELS.opus + '[1m]', 1000), MODELS.sonnet);
+  assert.equal(pickModel(0.95, MODELS.opus + '[1m]', 1000), MODELS.opus + '[1m]');
+});
+
+test('troxyCommand: off and on flip the setting, status and anything else only report it', () => {
+  assert.deepEqual(troxyCommand('off', false), { paused: true, text: 'Troxy routing is off. Your chosen model is used as-is. Type /troxy on to resume.' });
+  assert.deepEqual(troxyCommand(' ON ', true), { paused: false, text: 'Troxy routing is on.' });
+  assert.equal(troxyCommand('status', true).paused, true);
+  assert.match(troxyCommand('', true).text, /off/);
+  assert.match(troxyCommand('status', false).text, /on/);
+  assert.equal(troxyCommand('nonsense', false).paused, false);
+});

package/src/tests/mods-troxy-guard.test.js

@@ -0,0 +1,64 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { _internal } from '../mods/troxy-guard/hooks/register.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MOD_DIR = path.join(__dirname, '..', 'mods', 'troxy-guard');
+
+// --- Unit tests of the guard logic itself (fast, no subprocess needed) ---
+//
+// checkPolicy is deliberately NOT extracted as its own function: `claude
+// plugin validate` enforces that $ is only ever used inline at its own call
+// site (`$.noun.event(...)`), never forwarded as an argument to a helper -
+// an early version of this file failed validation for exactly that. That
+// collapses the testable surface here to toDomainAndFields and failClosed;
+// the BLOCK/ESCALATE/ALLOW branches are exercised by the real subprocess
+// test below instead, against a real $.http.fetch call.
+
+function fakeNext(e) { return Promise.resolve({ _passedThrough: e }); }
+
+test('guardBash: unmapped command (current real scope) passes through unchanged', async () => {
+  const result = await _internal.guardBash({}, { marker: 3 }, fakeNext);
+  assert.deepEqual(result, { _passedThrough: { marker: 3 } });
+});
+
+test('failClosed: denies with the error message rather than throwing or allowing', async () => {
+  const result = await _internal.failClosed({}, {}, fakeNext, new Error('fetch failed'));
+  assert.ok(result.deny.includes('fetch failed'));
+});
+
+// --- Real subprocess test: the mod actually loads and Bash passes through ---
+
+test('real subprocess: the mod loads via --plugin-dir and claude plugin validate recognizes the tool.call hook', () => {
+  const out = execFileSync('npx', ['-y', '@anthropic-ai/claude-code@2.1.289', 'plugin', 'validate', MOD_DIR], {
+    encoding: 'utf8',
+    timeout: 60000,
+  });
+  assert.ok(out.includes('tool.call'), `expected the validator to list a tool.call hook, got: ${out}`);
+});
+
+test('real subprocess: a real Bash command still runs normally through the mod (current scope: always passes through)', { skip: !fs.existsSync(path.join(os.homedir(), '.claude.json')) && 'no local Claude Code login available - this test needs a real, already-authenticated session (see project_claude_code_mods_investigation memory: a copied .claude.json alone was not sufficient to authenticate a fresh HOME in this environment, so this runs against the real HOME instead of an isolated one)' }, () => {
+  const workdir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-guard-e2e-workdir-'));
+  try {
+    fs.mkdirSync(path.join(workdir, '.claude'), { recursive: true });
+    fs.writeFileSync(
+      path.join(workdir, '.claude', 'settings.local.json'),
+      JSON.stringify({ permissions: { allow: ['Bash(echo:*)'] } }),
+    );
+    const out = execFileSync(
+      'npx',
+      ['-y', '@anthropic-ai/claude-code@2.1.289', '--plugin-dir', MOD_DIR, '-p',
+       'Run this exact bash command: echo TROXY_GUARD_PASSTHROUGH_TEST', '--output-format', 'json'],
+      { cwd: workdir, encoding: 'utf8', timeout: 90000 },
+    );
+    const result = JSON.parse(out);
+    assert.equal(result.is_error, false);
+  } finally {
+    fs.rmSync(workdir, { recursive: true, force: true });
+  }
+});

package/src/tests/mods-version-check.test.js

@@ -0,0 +1,44 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { supportsMods, detectInstalledClaudeCodeVersion } from '../mods/version-check.js';
+
+test('supportsMods: below floor returns false', () => {
+  assert.equal(supportsMods('2.1.285 (Claude Code)'), false);
+});
+
+test('supportsMods: at floor returns true', () => {
+  assert.equal(supportsMods('2.1.287 (Claude Code)'), true);
+});
+
+test('supportsMods: above floor (minor bump) returns true', () => {
+  assert.equal(supportsMods('2.2.0 (Claude Code)'), true);
+});
+
+test('supportsMods: above floor (patch bump) returns true', () => {
+  assert.equal(supportsMods('2.1.289 (Claude Code)'), true);
+});
+
+test('supportsMods: below floor (lower major) returns false', () => {
+  assert.equal(supportsMods('1.9.999 (Claude Code)'), false);
+});
+
+test('supportsMods: unparseable string returns false, not a throw', () => {
+  assert.equal(supportsMods('not a version'), false);
+});
+
+test('supportsMods: empty/undefined returns false', () => {
+  assert.equal(supportsMods(undefined), false);
+  assert.equal(supportsMods(''), false);
+});
+
+test('detectInstalledClaudeCodeVersion: parses a real-shaped execFn result', async () => {
+  const fakeExec = () => '2.1.289 (Claude Code)\n';
+  const result = await detectInstalledClaudeCodeVersion(fakeExec);
+  assert.deepEqual(result, { major: 2, minor: 1, patch: 289 });
+});
+
+test('detectInstalledClaudeCodeVersion: returns null, not a throw, when the command fails', async () => {
+  const fakeExec = () => { throw new Error('command not found: claude'); };
+  const result = await detectInstalledClaudeCodeVersion(fakeExec);
+  assert.equal(result, null);
+});

package/src/tests/posttooluse-hook.test.js

@@ -197,3 +197,29 @@ test('bin/troxy.js posttooluse-hook dispatch: real CLI subprocess does not throw
     fs.rmSync(tmpHome, { recursive: true, force: true });
   }
 });
+
+test('session arm is drawn once per session_id and sticks across tool calls', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-arm-'));
+  const big = { tool_response: { stdout: 'x'.repeat(5000) }, session_id: 'sess-aaaa-1111' };
+  // First call draws holdout (random 0 < 0.2).
+  const r1 = await buildHookResponse(big, { holdoutFraction: 0.2, randomFn: () => 0, storeDir: dir });
+  assert.equal(r1, undefined);
+  // Later draws would say treated, but the session stays holdout.
+  const r2 = await buildHookResponse(big, { holdoutFraction: 0.2, randomFn: () => 0.99, storeDir: dir });
+  assert.equal(r2, undefined);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(dir, 'sessions', 'sess-aaaa-1111.json'), 'utf8')).arm, 'holdout');
+
+  // A treated session compresses every big output, no per-call holdout draw.
+  const t = { ...big, session_id: 'sess-bbbb-2222' };
+  const t1 = await buildHookResponse(t, { holdoutFraction: 0.2, randomFn: () => 0.99, storeDir: dir });
+  assert.ok(t1?.hookSpecificOutput);
+  const t2 = await buildHookResponse(t, { holdoutFraction: 0.2, randomFn: () => 0, storeDir: dir });
+  assert.ok(t2?.hookSpecificOutput, 'treated session must not fall into a per-call holdout');
+});
+
+test('session_id with path characters is ignored (no file outside the store)', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-arm-'));
+  await buildHookResponse({ tool_response: { stdout: 'small' }, session_id: '../../etc/x' },
+    { holdoutFraction: 0.2, randomFn: () => 0, storeDir: dir });
+  assert.equal(fs.existsSync(path.join(dir, 'sessions')), false);
+});

package/src/uninstall.js

@@ -9,6 +9,7 @@ import {
   claudeCodeConfigPath, claudeCodeSettingsPath,
   unpatchClaudeCodeConfig, _unpatchClaudeCodeHooksFile,
   unpatchClaudeCodeProxy, unpatchClaudeCodeInterception,
+  uninstallTroxyGuardMod,
 } from './init.js';
 import { launchdUserDomain } from './launchd.js';
 
@@ -147,6 +148,7 @@ export async function runUninstall() {
     _unpatchClaudeCodeHooksFile(claudeCodeSettingsPath());
     unpatchClaudeCodeProxy(claudeCodeSettingsPath());
     unpatchClaudeCodeInterception(claudeCodeSettingsPath());
+    uninstallTroxyGuardMod();
     console.log('✓');
   } catch (err) {
     console.log('✗');