troxy-cli 1.20.0 → 1.21.0

package/bin/troxy.js

@@ -188,6 +188,16 @@ switch (command) {
     break;
   }
 
+  // ── Claude Code PreToolUse hook: gates model choice before a tool runs ─
+  // Invoked by Claude Code itself (registered via patchClaudeCodeHooks in
+  // init.js), never by a user directly. Must never throw or hang - see
+  // pretooluse-hook.js's own top-of-file note.
+  case 'pretooluse-hook': {
+    const { runPreToolUseHook } = await import('../src/pretooluse-hook.js');
+    await runPreToolUseHook();
+    break;
+  }
+
   // ── Heartbeat daemon (background service) ─────────────────────
   case 'daemon': {
     const { runDaemon } = await import('../src/daemon.js');
@@ -541,7 +551,7 @@ switch (command) {
   default:
     if (command) console.error(`  Unknown command: ${command}\n`);
     console.log(`
-  Troxy: AI payment control
+  Troxy: a secure control layer for AI agents
 
   This CLI has two parts:
     - Commands below (policies, mcps, activity, ...) are for YOU to run and manage your account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "troxy-cli",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Control layer for AI agents: check payments, emails, logins and destructive actions against your policies",
   "homepage": "https://troxy.io",
   "bugs": {

package/src/init.js

@@ -246,7 +246,7 @@ export async function runInit({ key, name } = {}) {
     process.exit(1);
   }
 
-  console.log('\n  Troxy: AI payment control\n');
+  console.log('\n  Troxy: a secure control layer for AI agents\n');
 
   // Validate the key by hitting /evaluate (404 = key is valid, TypeError = network failure)
   process.stdout.write('  Validating API key...  ');
@@ -304,9 +304,7 @@ export async function runInit({ key, name } = {}) {
 
   console.log('\n  Your payments are now protected.');
   console.log('  Dashboard → https://dash.troxy.io');
-  console.log('\n  Try it:');
-  console.log(`    troxy pay --merchant "Test" --amount 10`);
-  console.log('  This will appear in your dashboard within seconds.\n');
+  console.log('\n  For more information, visit https://docs.troxy.io\n');
 }
 
 function installService(apiKey, agentName) {
@@ -489,30 +487,62 @@ function claudeCodeSettingsPath() {
   return path.join(os.homedir(), '.claude', 'settings.json');
 }
 
-export function troxyHookCommand() {
-  let troxy;
+function _resolveTroxyBin() {
   try {
-    troxy = execSync('which troxy').toString().trim();
+    return execSync('which troxy').toString().trim();
   } catch {
-    troxy = 'npx troxy-cli';
+    return 'npx troxy-cli';
   }
-  return `${troxy} hook-report`;
 }
 
-export function patchClaudeCodeHooks(configPath, command = troxyHookCommand()) {
+export function troxyHookCommand() {
+  return `${_resolveTroxyBin()} hook-report`;
+}
+
+// PreToolUse gate: fires before every tool call and can actually block one,
+// unlike the Stop hook above (report-only, after the fact). Added because a
+// model-domain policy was previously only enforceable if the connected
+// agent voluntarily called the evaluate_model MCP tool first - proven live
+// to not happen (a real Claude Code session used its own Bash tool directly
+// without ever checking in, even on a fresh session with a valid key). See
+// pretooluse-hook.js for the full reasoning and fail-open guarantees.
+export function troxyPreToolUseCommand() {
+  return `${_resolveTroxyBin()} pretooluse-hook`;
+}
+
+export function patchClaudeCodeHooks(
+  configPath,
+  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 = [];
 
-  const isTroxyEntry = (matcherEntry) =>
+  if (!Array.isArray(config.hooks.Stop)) config.hooks.Stop = [];
+  const isTroxyStopEntry = (matcherEntry) =>
     Array.isArray(matcherEntry?.hooks) &&
     matcherEntry.hooks.some(h => typeof h?.command === 'string' && h.command.includes('hook-report'));
-
-  const troxyEntry = { hooks: [{ type: 'command', command }] };
-  const idx = config.hooks.Stop.findIndex(isTroxyEntry);
-  if (idx >= 0) config.hooks.Stop[idx] = troxyEntry;
-  else config.hooks.Stop.push(troxyEntry);
+  const stopEntry = { hooks: [{ type: 'command', command: stopCommand }] };
+  const stopIdx = config.hooks.Stop.findIndex(isTroxyStopEntry);
+  if (stopIdx >= 0) config.hooks.Stop[stopIdx] = stopEntry;
+  else config.hooks.Stop.push(stopEntry);
+
+  // matcher: '*' means "every tool" in Claude Code's own hook config syntax
+  // - NOT the regex '.*', which is a different (and wrong) pattern here.
+  // A short "timeout" (seconds) on the hook entry itself is a second,
+  // independent fail-open guarantee on top of pretooluse-hook.js's own
+  // internal race: even if the Node process somehow hung despite that,
+  // Claude Code cancels the hook and lets the tool proceed once this
+  // elapses (its documented behavior for a timed-out PreToolUse hook).
+  if (!Array.isArray(config.hooks.PreToolUse)) config.hooks.PreToolUse = [];
+  const isTroxyPreToolUseEntry = (matcherEntry) =>
+    Array.isArray(matcherEntry?.hooks) &&
+    matcherEntry.hooks.some(h => typeof h?.command === 'string' && h.command.includes('pretooluse-hook'));
+  const preToolUseEntry = { matcher: '*', hooks: [{ type: 'command', command: preToolUseCommand, timeout: 5 }] };
+  const preIdx = config.hooks.PreToolUse.findIndex(isTroxyPreToolUseEntry);
+  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');

package/src/pretooluse-hook.js

@@ -0,0 +1,113 @@
+import { loadConfig } from './config.js';
+import { api } from './api.js';
+import { usageForCurrentTurn } from './hook-report.js';
+
+// Claude Code PreToolUse hook entry point: `troxy pretooluse-hook` (wired in
+// bin/troxy.js, registered by patchClaudeCodeHooks in init.js). Fires before
+// EVERY tool call, in every project, for anyone who has run `troxy init` -
+// unlike hook-report.js (which only ever reports, after the fact), this one
+// can actually block. That makes fail-open correctness even more load-
+// bearing here: a bug that hangs or wrongly denies would degrade every tool
+// call in every project, not just Token Optimization data.
+//
+// Why this exists: a model-domain policy was previously only enforceable if
+// the connected agent voluntarily called the evaluate_model MCP tool before
+// acting on its own - proven live to not happen (a real Claude Code session
+// just used its own Bash tool directly, never checked in, even on a fresh
+// session with a valid key). PreToolUse is the host's own gate, not the
+// agent's discretion, so it's the first mechanism that actually enforces a
+// model policy instead of hoping the agent asks first.
+//
+// Everything in this file must fail open. A broken or slow check must never
+// block a tool call that a real policy would have allowed anyway - see the
+// GATE_TIMEOUT_MS race below, on top of the timeout Claude Code itself
+// enforces on the hook process (settings.json's "timeout" field, set when
+// this hook is registered).
+
+const STDIN_TIMEOUT_MS = 1000;
+const GATE_TIMEOUT_MS = 2500; // fail open fast - well under Claude Code's own hook timeout
+
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), ms)),
+  ]);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// Pure - the exact contract Claude Code's docs specify for PreToolUse: exit
+// 0 with this JSON on stdout is what blocks, not the legacy exit-code-2
+// convention. A wrong field name here fails open (invalid JSON is a non-
+// blocking error per Claude Code's own docs), never fails closed - so
+// getting this exactly right is what makes the gate work at all, not just
+// what makes it safe.
+export function buildDenyPayload(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+function allow() {
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify(buildDenyPayload(reason)));
+  process.exit(0); // exit 0, not 2 - the JSON permissionDecision is what blocks (modern contract)
+}
+
+export async function runPreToolUseHook() {
+  try {
+    const raw = await withTimeout(readStdin(), STDIN_TIMEOUT_MS);
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      return allow(); // can't parse our own input - never block on that
+    }
+
+    const transcriptPath = payload?.transcript_path;
+    if (!transcriptPath) return allow();
+
+    // transcript_path can lag the current turn by a beat (Claude Code's own
+    // docs note this), so this may occasionally read the previous turn's
+    // model instead of one just switched to mid-conversation. Worst case:
+    // one tool call briefly evaluated against the wrong (but recent) model -
+    // not a wrong-direction failure (never wrongly denies because of it),
+    // just an occasional miss, consistent with fail-open throughout this file.
+    const usage = usageForCurrentTurn(transcriptPath);
+    if (!usage || !usage.model) return allow(); // nothing to gate against yet
+
+    const config = loadConfig();
+    const apiKey = process.env.TROXY_API_KEY || config?.apiKey;
+    if (!apiKey) return allow();
+
+    const result = await withTimeout(
+      api.evaluateModel({ model: usage.model, task: payload.tool_name || '' }, apiKey),
+      GATE_TIMEOUT_MS,
+    );
+
+    if (result?.decision === 'BLOCK') {
+      return deny(`Troxy: blocked by policy - ${result.reason || `the model "${usage.model}" is not allowed.`}`);
+    }
+    // ALLOW, ESCALATE, or anything unexpected: don't block. ESCALATE has no
+    // synchronous human-in-the-loop path from inside a hook (there is
+    // nowhere here to pause and wait on an approval), so it fails open
+    // rather than hanging Claude Code - same reasoning as every other
+    // "never block on our own uncertainty" branch in this file.
+    return allow();
+  } catch {
+    // Network error, timeout, malformed response - never block the user's
+    // session over our own failure.
+    return allow();
+  }
+}

package/src/tests/claude-code-hook.test.js

@@ -123,3 +123,58 @@ describe('patchClaudeCodeHooks', () => {
     assert.doesNotThrow(() => patchClaudeCodeHooks(configPath(), 'troxy hook-report'));
   });
 });
+
+describe('patchClaudeCodeHooks: PreToolUse gate', () => {
+  const configPath = () => path.join(dir, 'settings.json');
+  const read = () => JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+
+  it('creates the PreToolUse entry alongside Stop, matching every tool', () => {
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', '/usr/local/bin/troxy pretooluse-hook');
+    const cfg = read();
+    assert.equal(cfg.hooks.PreToolUse.length, 1);
+    assert.equal(cfg.hooks.PreToolUse[0].hooks[0].command, '/usr/local/bin/troxy pretooluse-hook');
+    // '*' (not the regex '.*') is Claude Code's own documented syntax for
+    // "every tool" - the wrong one here means the gate silently never fires.
+    assert.equal(cfg.hooks.PreToolUse[0].matcher, '*');
+  });
+
+  it('sets a short per-hook timeout as a second, independent fail-open guarantee', () => {
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', 'troxy pretooluse-hook');
+    const cfg = read();
+    assert.ok(cfg.hooks.PreToolUse[0].hooks[0].timeout > 0);
+    assert.ok(cfg.hooks.PreToolUse[0].hooks[0].timeout <= 10, 'timeout should be short, not Claude Code\'s 600s default');
+  });
+
+  it('is idempotent: running twice produces one Troxy PreToolUse entry, not two', () => {
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', 'troxy pretooluse-hook');
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', 'troxy pretooluse-hook');
+    const cfg = read();
+    assert.equal(cfg.hooks.PreToolUse.length, 1);
+  });
+
+  it('updates the PreToolUse command in place on a re-run rather than appending', () => {
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', 'npx troxy-cli pretooluse-hook');
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', '/usr/local/bin/troxy pretooluse-hook');
+    const cfg = read();
+    assert.equal(cfg.hooks.PreToolUse.length, 1);
+    assert.equal(cfg.hooks.PreToolUse[0].hooks[0].command, '/usr/local/bin/troxy pretooluse-hook');
+  });
+
+  it("preserves the user's own unrelated PreToolUse hooks in the same file", () => {
+    fs.writeFileSync(configPath(), JSON.stringify({
+      hooks: { PreToolUse: [{ matcher: 'Write', hooks: [{ type: 'command', command: 'validate.sh' }] }] },
+    }));
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', 'troxy pretooluse-hook');
+    const cfg = read();
+    assert.equal(cfg.hooks.PreToolUse.length, 2);
+    assert.ok(cfg.hooks.PreToolUse.some(e => e.hooks[0].command === 'validate.sh'));
+    assert.ok(cfg.hooks.PreToolUse.some(e => e.hooks[0].command === 'troxy pretooluse-hook'));
+  });
+
+  it('registering PreToolUse never touches the Stop hook entry', () => {
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report', 'troxy pretooluse-hook');
+    const cfg = read();
+    assert.equal(cfg.hooks.Stop.length, 1);
+    assert.equal(cfg.hooks.Stop[0].hooks[0].command, 'troxy hook-report');
+  });
+});

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

@@ -0,0 +1,42 @@
+// The PreToolUse hook is the first mechanism that actually GATES a model
+// policy, rather than hoping the connected agent voluntarily calls the
+// evaluate_model MCP tool first - proven live not to happen (a real Claude
+// Code session used its own Bash tool directly without ever checking in,
+// even with a valid key freshly connected). Unlike the Stop hook
+// (hook-report.js, report-only), a bug here has real blast radius: it fires
+// before every tool call, in every project, for anyone who has run
+// `troxy init`. buildDenyPayload's exact shape is what Claude Code's docs
+// specify for a PreToolUse hook to actually block - a wrong field name
+// fails OPEN (invalid JSON is documented as a non-blocking error), so this
+// is the one place in this file where getting the shape exactly right is
+// what makes the gate work at all, not just what makes it safe.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildDenyPayload } from '../pretooluse-hook.js';
+
+describe('buildDenyPayload', () => {
+  it('matches the exact PreToolUse hookSpecificOutput contract', () => {
+    const payload = buildDenyPayload('some reason');
+    assert.deepEqual(payload, {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: 'some reason',
+      },
+    });
+  });
+
+  it('is valid JSON when stringified (a parse failure here fails open, not closed)', () => {
+    assert.doesNotThrow(() => JSON.stringify(buildDenyPayload('reason')));
+  });
+
+  it('carries the reason through unmodified', () => {
+    const payload = buildDenyPayload('Troxy: blocked by policy - the model "claude-opus-4" is not allowed.');
+    assert.equal(
+      payload.hookSpecificOutput.permissionDecisionReason,
+      'Troxy: blocked by policy - the model "claude-opus-4" is not allowed.',
+    );
+  });
+});