troxy-cli 1.18.0 → 1.19.0

package/bin/troxy.js

@@ -177,6 +177,17 @@ switch (command) {
     await runMcp();
     break;
 
+  // ── Claude Code Stop hook: real, host-captured usage per turn ─
+  // Invoked by Claude Code itself (registered via patchClaudeCodeHooks in
+  // init.js), never by a user directly. Must never throw or hang - see
+  // hook-report.js's own top-of-file note on why everything in it fails
+  // silently.
+  case 'hook-report': {
+    const { runHookReport } = await import('../src/hook-report.js');
+    await runHookReport();
+    break;
+  }
+
   // ── Heartbeat daemon (background service) ─────────────────────
   case 'daemon': {
     const { runDaemon } = await import('../src/daemon.js');
@@ -532,6 +543,11 @@ switch (command) {
     console.log(`
   Troxy: AI payment control
 
+  This CLI has two parts:
+    - Commands below (policies, mcps, activity, ...) are for YOU to run and manage your account.
+    - "troxy mcp" starts the MCP server an AI agent connects to. You don't run it by hand;
+      MCP clients (Claude Desktop, etc.) launch it after "troxy init" configures them.
+
   First time? Run these two commands in order:
     1) npx troxy-cli init --key txy-...   (get key from https://dash.troxy.io)
     2) troxy login                         (start a 12h CLI session)

package/package.json

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

package/src/api.js

@@ -95,6 +95,11 @@ export const api = {
   // guess, and Token Optimization says so on every agent that never reports.
   evaluateModel: (body, apiKey) => request('POST', '/evaluate/model', { apiKey, body }),
   reportModelUsage: (body, apiKey) => request('POST', '/evaluate/model/complete', { apiKey, body }),
+  // Real, host-captured usage for a turn that already happened - not an
+  // agent's self-report of what it thinks it used. Called only by the
+  // Claude Code Stop hook (hook-report.js), never by mcp-server.js's own
+  // instruction-driven self-report path.
+  reportVerifiedUsage: (body, apiKey) => request('POST', '/evaluate/model/verified', { apiKey, body }),
   selfRevoke: (apiKey) => request('POST', '/mcp/self-revoke', { apiKey }),
   revokeAllOthers: (apiKey) => request('POST', '/mcp/revoke-all-others', { apiKey }),
   confirmPayment: (auditId, body, apiKey) => request('POST', `/payments/${auditId}/confirm`, { apiKey, body }),

package/src/hook-report.js

@@ -0,0 +1,164 @@
+import fs           from 'fs';
+import { loadConfig } from './config.js';
+import { api }        from './api.js';
+
+// Claude Code Stop-hook entry point: `troxy hook-report` (wired in bin/troxy.js).
+// Registered by patchClaudeCodeHooks() in init.js, fires unconditionally at
+// the end of every Claude Code turn, tool-use or pure chat, regardless of
+// what the agent does or doesn't call. This exists because chat-only
+// self-report was proven live to not fire reliably (two consecutive
+// pure-chat turns with a connected agent produced zero checkpoint calls) -
+// nothing here trusts self-report to have already happened.
+//
+// Everything in this file must fail silently. A broken report must never
+// interrupt the user's Claude Code session - there is nothing more important
+// happening here than the conversation that just finished.
+
+const REPORT_TIMEOUT_MS = 2500;
+
+// Fields this file is allowed to touch from a transcript entry. Deliberately
+// narrow: extractUsage() below only ever reads these keys off a transcript
+// line, never the line's own `content` (the actual message text). This is
+// the enforcement mechanism for "the hook must never log, store, or forward
+// conversation content, only usage numbers" - a function that structurally
+// cannot see `content` cannot leak it, whether by a future edit forgetting
+// the boundary or otherwise.
+export function extractUsage(entry) {
+  const msg = entry?.message;
+  if (!msg || entry.type !== 'assistant') return null;
+  const usage = msg.usage;
+  if (!usage) return null;
+  const inputTokens = Number(usage.input_tokens) || 0;
+  const outputTokens = Number(usage.output_tokens) || 0;
+  const cacheCreation = Number(usage.cache_creation_input_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens) || 0;
+  return {
+    messageId: msg.id || null,
+    model: msg.model || null,
+    // Cache tokens are real spend (cache writes especially), so they count
+    // toward the total even though they're priced differently than a fresh
+    // input token. Troxy's own pricing table (chat_tools.py) does the actual
+    // dollar math server-side from the model id; this file only sums what
+    // the transcript says was used.
+    tokens: inputTokens + outputTokens + cacheCreation + cacheRead,
+  };
+}
+
+// Claude Code writes one JSONL line per content block (thinking/tool_use/
+// text), not one per turn or even one per model call - a single real API
+// response is split across several consecutive lines that all share the
+// same message.id and carry the identical usage object repeated on every
+// line. Verified live against a real session transcript before writing
+// this: naively summing every assistant line's usage overcounts by however
+// many content blocks that response happened to have. A turn can also span
+// several distinct real model calls if it used tools in between, so the fix
+// is not "take the last line's usage" either - it's dedup by message.id and
+// sum each unique id exactly once, walking back only as far as the last
+// user-authored line (the start of the current turn).
+export function usageForCurrentTurn(transcriptPath) {
+  let lines;
+  try {
+    lines = fs.readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return null;
+  }
+
+  const turnLines = [];
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let entry;
+    try {
+      entry = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    if (entry.type === 'user') break;
+    turnLines.push(entry);
+  }
+
+  const seen = new Map(); // messageId -> {model, tokens}
+  let lastModel = null;
+  for (const entry of turnLines) {
+    const usage = extractUsage(entry);
+    if (!usage || !usage.messageId) continue;
+    if (!seen.has(usage.messageId)) {
+      seen.set(usage.messageId, usage);
+      lastModel = lastModel || usage.model;
+    }
+  }
+
+  if (seen.size === 0) return null;
+
+  let totalTokens = 0;
+  for (const u of seen.values()) totalTokens += u.tokens;
+
+  // turn_key: dedups a hook that fires twice for the same turn (a retry,
+  // a Claude Code internal replay) against a repeat POST for the same
+  // data, and against a self-reported row for the same turn if one exists.
+  // The sorted, joined set of message ids in this turn is stable across a
+  // repeat firing of the hook for the same turn, and distinct across
+  // genuinely different turns.
+  const turnKey = Array.from(seen.keys()).sort().join(',').slice(0, 200);
+
+  return { tokens: totalTokens, model: lastModel, turnKey };
+}
+
+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');
+}
+
+export async function runHookReport() {
+  try {
+    const raw = await withTimeout(readStdin(), 1000);
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      process.exit(0);
+    }
+
+    const transcriptPath = payload?.transcript_path;
+    if (!transcriptPath) {
+      process.exit(0);
+    }
+
+    const usage = usageForCurrentTurn(transcriptPath);
+    if (!usage || !usage.model || usage.tokens <= 0) {
+      // Nothing measurable this turn (e.g. the very first line of a fresh
+      // session, or a turn that produced no assistant usage at all) - not
+      // an error, just nothing to report.
+      process.exit(0);
+    }
+
+    const config = loadConfig();
+    const apiKey = process.env.TROXY_API_KEY || config?.apiKey;
+    if (!apiKey) {
+      process.exit(0);
+    }
+
+    const sessionId = payload?.session_id || '';
+    const turnKey = sessionId ? `${sessionId}:${usage.turnKey}` : null;
+
+    await withTimeout(
+      api.reportVerifiedUsage(
+        { model: usage.model, actual_tokens: usage.tokens, turn_key: turnKey },
+        apiKey,
+      ),
+      REPORT_TIMEOUT_MS,
+    );
+  } catch {
+    // Never surface a failure to Claude Code. A dropped report is a gap in
+    // Token Optimization, not something worth interrupting the user's
+    // session over.
+  } finally {
+    process.exit(0);
+  }
+}

package/src/init.js

@@ -28,7 +28,12 @@ export function detectMcpClients() {
     hasOpenClaw = true;
   } catch {}
 
-  return { detected, hasOpenClaw, none: detected.length === 0 && !hasOpenClaw };
+  const hasClaude = hasClaudeCode();
+
+  return {
+    detected, hasOpenClaw, hasClaude,
+    none: detected.length === 0 && !hasOpenClaw && !hasClaude,
+  };
 }
 
 // `troxy update` on a hosted agent. The npm package is beside the point there:
@@ -44,7 +49,7 @@ export async function refreshHostedInstructions(key) {
 
 export async function reprovisionKeyConsumers(key, agentName) {
   const platform = process.platform;
-  const { detected, hasOpenClaw, none } = detectMcpClients();
+  const { detected, hasOpenClaw, hasClaude, none } = detectMcpClients();
 
   if (none) {
     // No MCP client on this machine almost always means a hosted agent running
@@ -82,6 +87,20 @@ export async function reprovisionKeyConsumers(key, agentName) {
         console.log(`    • OpenClaw  ✗  (${err.message})`);
       }
     }
+    if (hasClaude) {
+      try {
+        patchClaudeCodeConfig(claudeCodeConfigPath(), key);
+        console.log(`    • Claude Code (this project)  ✓`);
+      } catch (err) {
+        console.log(`    • Claude Code  ✗  (${err.message})`);
+      }
+      try {
+        patchClaudeCodeHooks(claudeCodeSettingsPath());
+        console.log(`    • Claude Code usage capture (all projects)  ✓`);
+      } catch (err) {
+        console.log(`    • Claude Code usage capture  ✗  (${err.message})`);
+      }
+    }
     console.log('\n  Restart your MCP client to activate Troxy.');
   }
 
@@ -419,3 +438,96 @@ function patchContinueConfig(configPath, apiKey) {
   });
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 }
+
+// Claude Code does not use the flat `mcpServers` file the other five clients
+// share - its MCP registration is project-scoped, living in `~/.claude.json`
+// under `projects["<cwd>"].mcpServers`, keyed by the directory `troxy init`
+// was run from. Confirmed by reading a real, populated `~/.claude.json` on a
+// machine with Claude Code installed - there is no separate, simpler config
+// file to target. Before this, Claude Code had no entry in MCP_CLIENTS at
+// all, so `troxy init` misdetected a Claude-Code-only machine as having no
+// MCP client and printed hosted-agent instructions instead of registering
+// anything.
+//
+// TROXY_HOOK_CAPTURE=1 is the signal mcp-server.js's own instructions check
+// to suppress its chat-only self-report clause for this session - once the
+// Stop hook (patchClaudeCodeHooks, below) is also registered, self-report
+// asking the agent to also report chat-only turns would double-count against
+// the hook's real capture of the same turns. Tool-use self-report is left
+// alone; the hook does not replace that, only chat-only reporting.
+function claudeCodeConfigPath() {
+  return path.join(os.homedir(), '.claude.json');
+}
+
+// configPath and cwd are explicit params, same shape as patchMcpConfig /
+// patchZedConfig above, so this can be pointed at a temp file and a fake
+// project directory in tests rather than always touching the real
+// ~/.claude.json on whatever machine the tests run on.
+export function patchClaudeCodeConfig(configPath, apiKey, cwd = process.cwd()) {
+  let config = {};
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  if (!config.projects) config.projects = {};
+  if (!config.projects[cwd]) config.projects[cwd] = {};
+  if (!config.projects[cwd].mcpServers) config.projects[cwd].mcpServers = {};
+  config.projects[cwd].mcpServers.troxy = {
+    command: 'npx',
+    args: ['troxy-cli', 'mcp'],
+    env: { TROXY_API_KEY: apiKey, TROXY_HOOK_CAPTURE: '1' },
+  };
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+// The hook, unlike MCP registration, is written to the GLOBAL user settings
+// file rather than a per-project one: registered once, it captures real
+// usage across every project this user works in with Claude Code, not just
+// the one `troxy init` happened to run inside. Idempotent by finding any
+// existing Stop hook entry whose command already invokes `troxy hook-report`
+// and replacing it in place, rather than blind-pushing - a second `troxy
+// init` must not duplicate the entry, and any of the user's OWN unrelated
+// Stop hooks in the same file must survive untouched.
+function claudeCodeSettingsPath() {
+  return path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+export function troxyHookCommand() {
+  let troxy;
+  try {
+    troxy = execSync('which troxy').toString().trim();
+  } catch {
+    troxy = 'npx troxy-cli';
+  }
+  return `${troxy} hook-report`;
+}
+
+export function patchClaudeCodeHooks(configPath, command = troxyHookCommand()) {
+  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) =>
+    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);
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+// Detects Claude Code the same way the daemon detects OpenClaw: by whether
+// its own CLI is on PATH, since (unlike the other five clients) there is no
+// single marker *file* whose mere existence means "Claude Code is
+// installed" - `~/.claude.json` and `~/.claude/settings.json` are both
+// created lazily and may not exist yet on a fresh install.
+function hasClaudeCode() {
+  try {
+    execSync('claude --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/mcp-server.js

@@ -31,6 +31,18 @@ export async function runMcp() {
     process.exit(1);
   }
 
+  // TROXY_HOOK_CAPTURE is set only by patchClaudeCodeConfig (init.js), only
+  // for a Claude Code session that also has the Stop hook registered
+  // (patchClaudeCodeHooks). That hook reports real, host-captured usage for
+  // every turn regardless of what the agent does - so instructing the agent
+  // to ALSO self-report chat-only turns here would double-count the same
+  // turn once as a self-report and once as a verified capture. Tool-use
+  // self-report is untouched: the hook does not gate on a policy decision
+  // (it fires after the turn already happened, there's nothing left to
+  // block), so it is not a substitute for the pre-call gating self-report
+  // still provides.
+  const hookCaptureActive = !!process.env.TROXY_HOOK_CAPTURE;
+
   const server = new Server(
     {
       name: 'troxy',
@@ -63,15 +75,21 @@ export async function runMcp() {
         // The trigger below is mechanical instead: did this turn use a tool,
         // yes or no. That is a fact you can check, not a judgment you make.
         'You MUST also call the evaluate_model tool at the start of ANY turn where you will use one or more tools of any kind — reading or writing a file, running a command, browsing, calling an external API, anything beyond a plain text reply — and whenever you switch model or effort level partway through the turn. This is not a judgment call about how the turn feels: if you are about to use a tool, call evaluate_model first, every time, regardless of how small the turn seems, and WAIT for the decision before proceeding. Give the exact model id and how many tokens you expect to use. Do not use any tool without first receiving an ALLOW or NOTIFY decision; if BLOCK, pick a cheaper or smaller model and call evaluate_model again with the new id; if ESCALATE, call wait_for_approval and do not proceed until it resolves. Then, at the end of that same turn, you MUST call report_model_usage with the audit_id from that decision and the real token total from your model API. Both halves are required: without the second call Troxy has only your prediction, and the account owner is shown that this agent\'s costs are unverified. Report the true number even when it is far above your estimate. ' +
-        // A turn that is PURE conversation, no tool use at all, still gets
-        // logged, just not gated. Blocking a chat reply on a network round
-        // trip protects against a risk that is vanishingly rare in practice
-        // (almost nobody writes a policy to block message content), and the
-        // cost of blocking anyway is a slower product on every single message.
-        // So chat calls the same two tools, in the same order, but treats the
-        // decision as a record rather than a gate: reply to the user first,
-        // report afterward, never hold the reply for Troxy's answer.
-        'A turn that is pure conversation, with no tool use at all, is different: you still call evaluate_model and report_model_usage for it, but you do NOT wait for or act on the decision before replying. Reply to the user first. Then, as the last step of that same turn (or the first step of your next turn if your environment does not let you act again after producing a reply), call evaluate_model with the model and your best token estimate, and call report_model_usage with the real total right after — same two tools as above, just not gating. If the decision comes back BLOCK or ESCALATE for a chat turn, do not retry with a different model and do not poll wait_for_approval: the reply has already been sent, there is nothing left to gate, and the decision is recorded for the account owner\'s visibility rather than enforced in the moment. Chat usage still counts toward every rolling spend and token limit, so it still shapes what the next tool-use call is allowed to do.',
+        (hookCaptureActive
+          // Claude Code's own Stop hook already reports real, host-captured
+          // usage for every turn in this session, chat-only included - see
+          // the note above `hookCaptureActive`. Self-reporting chat here too
+          // would double-count the same turn.
+          ? 'This session has real usage capture active for every turn (Claude Code\'s own Stop hook, not a self-report), so a turn that is pure conversation with no tool use is already covered - do NOT call evaluate_model or report_model_usage for it yourself. Tool-use turns are unaffected: keep gating on evaluate_model before using any tool exactly as described above.'
+          // A turn that is PURE conversation, no tool use at all, still gets
+          // logged, just not gated. Blocking a chat reply on a network round
+          // trip protects against a risk that is vanishingly rare in practice
+          // (almost nobody writes a policy to block message content), and the
+          // cost of blocking anyway is a slower product on every single message.
+          // So chat calls the same two tools, in the same order, but treats the
+          // decision as a record rather than a gate: reply to the user first,
+          // report afterward, never hold the reply for Troxy's answer.
+          : 'A turn that is pure conversation, with no tool use at all, is different: you still call evaluate_model and report_model_usage for it, but you do NOT wait for or act on the decision before replying. Reply to the user first. Then, as the last step of that same turn (or the first step of your next turn if your environment does not let you act again after producing a reply), call evaluate_model with the model and your best token estimate, and call report_model_usage with the real total right after — same two tools as above, just not gating. If the decision comes back BLOCK or ESCALATE for a chat turn, do not retry with a different model and do not poll wait_for_approval: the reply has already been sent, there is nothing left to gate, and the decision is recorded for the account owner\'s visibility rather than enforced in the moment. Chat usage still counts toward every rolling spend and token limit, so it still shapes what the next tool-use call is allowed to do.'),
     },
     { capabilities: { tools: {} } },
   );
@@ -288,9 +306,10 @@ export async function runMcp() {
         description:
           'Evaluate whether running a task on a given AI model should be allowed, blocked, or escalated ' +
           'based on your Troxy policies, and record what it is expected to cost. ' +
-          'Call this on every turn: at the start, before proceeding, if you will use a tool of any kind, or whenever you switch model or effort level mid-turn; ' +
-          'or after replying, without waiting for the decision, if the turn was pure conversation with no tool use. ' +
-          'Tool use gates on the decision; chat only records it. ' +
+          'Call this on every turn: at the start, before proceeding, if you will use a tool of any kind, or whenever you switch model or effort level mid-turn' +
+          (hookCaptureActive
+            ? '. This session has real usage capture active for chat-only turns already (do not call this or report_model_usage for a turn with no tool use - only for tool-use turns). '
+            : '; or after replying, without waiting for the decision, if the turn was pure conversation with no tool use. Tool use gates on the decision; chat only records it. ') +
           'Returns an audit_id. Keep it: you must pass it to report_model_usage when the turn finishes.',
         inputSchema: {
           type: 'object',

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

@@ -0,0 +1,125 @@
+// Claude Code has no entry in MCP_CLIENTS at all before this change - on a
+// machine with only Claude Code installed, `troxy init` misdetected "no MCP
+// client" and printed hosted-agent instructions instead of registering
+// anything. Its MCP config also has a different shape than the other five
+// clients: project-scoped, under `~/.claude.json`'s `projects["<cwd>"]`,
+// confirmed by reading a real populated file rather than assumed from docs.
+//
+// The Stop hook exists to close a gap self-report cannot: it fires
+// unconditionally at the end of every turn (tool-use or pure chat) and
+// reads real usage off Claude Code's own transcript, regardless of what the
+// agent does. Chat-only self-report was proven live to not fire reliably;
+// this does not depend on the agent choosing to comply at all.
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { patchClaudeCodeConfig, patchClaudeCodeHooks } from '../init.js';
+
+let dir;
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-cc-')); });
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+describe('patchClaudeCodeConfig', () => {
+  const configPath = () => path.join(dir, '.claude.json');
+  const read = () => JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+
+  it('creates the project-scoped mcpServers entry when the file does not exist', () => {
+    patchClaudeCodeConfig(configPath(), 'txy-abc', '/Users/x/proj');
+    const cfg = read();
+    assert.equal(cfg.projects['/Users/x/proj'].mcpServers.troxy.env.TROXY_API_KEY, 'txy-abc');
+  });
+
+  it('sets TROXY_HOOK_CAPTURE so mcp-server.js knows the hook already covers chat', () => {
+    patchClaudeCodeConfig(configPath(), 'txy-abc', '/Users/x/proj');
+    const cfg = read();
+    assert.equal(cfg.projects['/Users/x/proj'].mcpServers.troxy.env.TROXY_HOOK_CAPTURE, '1');
+  });
+
+  it('only touches this project entry, leaving other projects in the same file alone', () => {
+    fs.writeFileSync(configPath(), JSON.stringify({
+      projects: { '/other/proj': { mcpServers: { someOtherTool: { command: 'x' } } } },
+    }));
+    patchClaudeCodeConfig(configPath(), 'txy-abc', '/Users/x/proj');
+    const cfg = read();
+    assert.ok(cfg.projects['/other/proj'].mcpServers.someOtherTool, 'unrelated project entry was dropped');
+    assert.ok(cfg.projects['/Users/x/proj'].mcpServers.troxy);
+  });
+
+  it('preserves unrelated keys already on the project entry (e.g. allowedTools)', () => {
+    fs.writeFileSync(configPath(), JSON.stringify({
+      projects: { '/Users/x/proj': { allowedTools: ['Bash'], mcpServers: {} } },
+    }));
+    patchClaudeCodeConfig(configPath(), 'txy-abc', '/Users/x/proj');
+    const cfg = read();
+    assert.deepEqual(cfg.projects['/Users/x/proj'].allowedTools, ['Bash']);
+  });
+
+  it('re-running with a new key overwrites the old one rather than stacking', () => {
+    patchClaudeCodeConfig(configPath(), 'txy-old', '/Users/x/proj');
+    patchClaudeCodeConfig(configPath(), 'txy-new', '/Users/x/proj');
+    const cfg = read();
+    assert.equal(cfg.projects['/Users/x/proj'].mcpServers.troxy.env.TROXY_API_KEY, 'txy-new');
+  });
+
+  it('does not throw when the existing file is corrupted JSON', () => {
+    fs.writeFileSync(configPath(), '{ not json');
+    assert.doesNotThrow(() => patchClaudeCodeConfig(configPath(), 'txy-abc', '/Users/x/proj'));
+  });
+});
+
+describe('patchClaudeCodeHooks', () => {
+  const configPath = () => path.join(dir, 'settings.json');
+  const read = () => JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+
+  it('creates the Stop hook entry when the file does not exist', () => {
+    patchClaudeCodeHooks(configPath(), '/usr/local/bin/troxy hook-report');
+    const cfg = read();
+    assert.equal(cfg.hooks.Stop.length, 1);
+    assert.equal(cfg.hooks.Stop[0].hooks[0].command, '/usr/local/bin/troxy hook-report');
+    assert.equal(cfg.hooks.Stop[0].hooks[0].type, 'command');
+  });
+
+  it('is idempotent: running twice produces one Troxy entry, not two', () => {
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report');
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report');
+    const cfg = read();
+    assert.equal(cfg.hooks.Stop.length, 1);
+  });
+
+  it('updates the command in place on a re-run rather than appending', () => {
+    patchClaudeCodeHooks(configPath(), 'npx troxy-cli hook-report');
+    patchClaudeCodeHooks(configPath(), '/usr/local/bin/troxy hook-report');
+    const cfg = read();
+    assert.equal(cfg.hooks.Stop.length, 1);
+    assert.equal(cfg.hooks.Stop[0].hooks[0].command, '/usr/local/bin/troxy hook-report');
+  });
+
+  it("preserves the user's own unrelated Stop hooks in the same file", () => {
+    fs.writeFileSync(configPath(), JSON.stringify({
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'my-own-script.sh' }] }] },
+    }));
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report');
+    const cfg = read();
+    assert.equal(cfg.hooks.Stop.length, 2);
+    assert.ok(cfg.hooks.Stop.some(e => e.hooks[0].command === 'my-own-script.sh'));
+    assert.ok(cfg.hooks.Stop.some(e => e.hooks[0].command === 'troxy hook-report'));
+  });
+
+  it("preserves the user's own other hook events (PreToolUse etc.) untouched", () => {
+    fs.writeFileSync(configPath(), JSON.stringify({
+      hooks: { PreToolUse: [{ matcher: 'Write', hooks: [{ type: 'command', command: 'validate.sh' }] }] },
+    }));
+    patchClaudeCodeHooks(configPath(), 'troxy hook-report');
+    const cfg = read();
+    assert.ok(cfg.hooks.PreToolUse, 'an unrelated hook event was dropped by the patch');
+  });
+
+  it('does not throw when the existing file is corrupted JSON', () => {
+    fs.writeFileSync(configPath(), 'not json at all');
+    assert.doesNotThrow(() => patchClaudeCodeHooks(configPath(), 'troxy hook-report'));
+  });
+});

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

@@ -0,0 +1,139 @@
+// The transcript-parsing half of the Claude Code Stop hook.
+//
+// Verified live against a real session transcript before writing this (see
+// the plan): Claude Code writes one JSONL line per content block
+// (thinking/tool_use/text), not one per turn or even one per real model
+// call. Multiple consecutive lines share the same message.id and top-level
+// requestId, and carry the IDENTICAL usage object repeated on every line.
+// Naively summing every assistant line's usage overcounts by however many
+// content blocks that one response happened to have - these tests exist
+// because that bug is easy to reintroduce and would silently inflate every
+// number Token Optimization shows for a Claude Code agent.
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { usageForCurrentTurn, extractUsage } from '../hook-report.js';
+
+let dir;
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-transcript-')); });
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+function transcriptPath() {
+  return path.join(dir, 'transcript.jsonl');
+}
+
+function writeLines(lines) {
+  fs.writeFileSync(transcriptPath(), lines.map(l => JSON.stringify(l)).join('\n') + '\n');
+}
+
+function assistantLine(messageId, usage, model = 'claude-sonnet-5') {
+  return { type: 'assistant', message: { id: messageId, model, usage } };
+}
+
+const USAGE_A = { input_tokens: 2, output_tokens: 1176, cache_creation_input_tokens: 4134, cache_read_input_tokens: 244103 };
+
+describe('extractUsage', () => {
+  it('only reads usage/model/id fields, never message.content', () => {
+    const entry = {
+      type: 'assistant',
+      message: {
+        id: 'msg_1',
+        model: 'claude-sonnet-5',
+        usage: { input_tokens: 10, output_tokens: 5 },
+        content: [{ type: 'text', text: 'this is the actual conversation, must never be touched' }],
+      },
+    };
+    const result = extractUsage(entry);
+    assert.deepEqual(Object.keys(result).sort(), ['messageId', 'model', 'tokens']);
+    assert.ok(!JSON.stringify(result).includes('actual conversation'));
+  });
+
+  it('returns null for a non-assistant line', () => {
+    assert.equal(extractUsage({ type: 'user', message: { usage: { input_tokens: 1 } } }), null);
+  });
+
+  it('returns null when there is no usage object at all', () => {
+    assert.equal(extractUsage({ type: 'assistant', message: { id: 'x' } }), null);
+  });
+});
+
+describe('usageForCurrentTurn', () => {
+  it('sums usage once per unique message.id, not once per JSONL line', () => {
+    // The exact shape found live: three content-block lines (thinking,
+    // tool_use, text) all sharing one message.id and one usage object.
+    writeLines([
+      { type: 'user', message: { content: [{ type: 'text', text: 'hi' }] } },
+      assistantLine('msg_1', USAGE_A),
+      assistantLine('msg_1', USAGE_A),
+      assistantLine('msg_1', USAGE_A),
+    ]);
+    const result = usageForCurrentTurn(transcriptPath());
+    const expectedOnce = USAGE_A.input_tokens + USAGE_A.output_tokens
+      + USAGE_A.cache_creation_input_tokens + USAGE_A.cache_read_input_tokens;
+    assert.equal(result.tokens, expectedOnce, 'summed the same message.id multiple times');
+  });
+
+  it('sums each distinct message.id once when a turn used a tool mid-turn (two real model calls)', () => {
+    writeLines([
+      { type: 'user', message: { content: [{ type: 'text', text: 'hi' }] } },
+      assistantLine('msg_1', { input_tokens: 10, output_tokens: 20 }),
+      assistantLine('msg_1', { input_tokens: 10, output_tokens: 20 }), // same call, second content block
+      assistantLine('msg_2', { input_tokens: 5, output_tokens: 8 }),  // a second real model call after a tool result
+    ]);
+    const result = usageForCurrentTurn(transcriptPath());
+    assert.equal(result.tokens, 10 + 20 + 5 + 8);
+  });
+
+  it('only looks back to the last user-authored line, not the whole session', () => {
+    writeLines([
+      { type: 'user', message: { content: [{ type: 'text', text: 'first turn' }] } },
+      assistantLine('msg_old', { input_tokens: 999, output_tokens: 999 }),
+      { type: 'user', message: { content: [{ type: 'text', text: 'second turn' }] } },
+      assistantLine('msg_new', { input_tokens: 10, output_tokens: 10 }),
+    ]);
+    const result = usageForCurrentTurn(transcriptPath());
+    assert.equal(result.tokens, 20, 'usage from a prior turn leaked into the current one');
+  });
+
+  it('returns the model from the assistant lines in the current turn', () => {
+    writeLines([
+      { type: 'user', message: { content: [{ type: 'text', text: 'hi' }] } },
+      assistantLine('msg_1', { input_tokens: 1, output_tokens: 1 }, 'claude-opus-4.5'),
+    ]);
+    const result = usageForCurrentTurn(transcriptPath());
+    assert.equal(result.model, 'claude-opus-4.5');
+  });
+
+  it('returns a stable turn_key for the same set of message ids, order-independent', () => {
+    writeLines([
+      { type: 'user', message: { content: [] } },
+      assistantLine('msg_b', { input_tokens: 1, output_tokens: 1 }),
+      assistantLine('msg_a', { input_tokens: 1, output_tokens: 1 }),
+    ]);
+    const result = usageForCurrentTurn(transcriptPath());
+    assert.equal(result.turnKey, 'msg_a,msg_b');
+  });
+
+  it('returns null when the transcript has no assistant usage at all (fresh session)', () => {
+    writeLines([{ type: 'user', message: { content: [{ type: 'text', text: 'hi' }] } }]);
+    assert.equal(usageForCurrentTurn(transcriptPath()), null);
+  });
+
+  it('does not throw when the transcript file does not exist', () => {
+    assert.doesNotThrow(() => usageForCurrentTurn(path.join(dir, 'missing.jsonl')));
+    assert.equal(usageForCurrentTurn(path.join(dir, 'missing.jsonl')), null);
+  });
+
+  it('skips unparseable lines rather than throwing', () => {
+    fs.writeFileSync(transcriptPath(), [
+      JSON.stringify({ type: 'user', message: { content: [] } }),
+      'not valid json',
+      JSON.stringify(assistantLine('msg_1', { input_tokens: 1, output_tokens: 1 })),
+    ].join('\n') + '\n');
+    assert.doesNotThrow(() => usageForCurrentTurn(transcriptPath()));
+  });
+});