deepflow 0.1.102 → 0.1.103

package/bin/install.js

@@ -256,6 +256,7 @@ async function configureHooks(claudeDir) {
   const snapshotGuardCmd = `node "${path.join(claudeDir, 'hooks', 'df-snapshot-guard.js')}"`;
   const invariantCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-invariant-check.js')}"`;
   const subagentRegistryCmd = `node "${path.join(claudeDir, 'hooks', 'df-subagent-registry.js')}"`;
+  const commandUsageCmd = `node "${path.join(claudeDir, 'hooks', 'df-command-usage.js')}"`;
 
   let settings = {};
 
@@ -333,10 +334,10 @@ async function configureHooks(claudeDir) {
     settings.hooks.SessionEnd = [];
   }
 
-  // Remove any existing quota logger / dashboard push from SessionEnd
+  // Remove any existing quota logger / dashboard push / command usage from SessionEnd
   settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(hook => {
     const cmd = hook.hooks?.[0]?.command || '';
-    return !cmd.includes('df-quota-logger') && !cmd.includes('df-dashboard-push');
+    return !cmd.includes('df-quota-logger') && !cmd.includes('df-dashboard-push') && !cmd.includes('df-command-usage');
   });
 
   // Add quota logger to SessionEnd
@@ -354,17 +355,25 @@ async function configureHooks(claudeDir) {
       command: dashboardPushCmd
     }]
   });
-  log('Quota logger + dashboard push configured (SessionEnd)');
+
+  // Add command usage hook to SessionEnd (flush any pending command data)
+  settings.hooks.SessionEnd.push({
+    hooks: [{
+      type: 'command',
+      command: commandUsageCmd
+    }]
+  });
+  log('Quota logger + dashboard push + command usage configured (SessionEnd)');
 
   // Configure PostToolUse hook for tool usage instrumentation
   if (!settings.hooks.PostToolUse) {
     settings.hooks.PostToolUse = [];
   }
 
-  // Remove any existing deepflow tool usage / execution history / worktree guard / snapshot guard / invariant check hooks from PostToolUse
+  // Remove any existing deepflow tool usage / execution history / worktree guard / snapshot guard / invariant check / command usage hooks from PostToolUse
   settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(hook => {
     const cmd = hook.hooks?.[0]?.command || '';
-    return !cmd.includes('df-tool-usage') && !cmd.includes('df-execution-history') && !cmd.includes('df-worktree-guard') && !cmd.includes('df-snapshot-guard') && !cmd.includes('df-invariant-check');
+    return !cmd.includes('df-tool-usage') && !cmd.includes('df-execution-history') && !cmd.includes('df-worktree-guard') && !cmd.includes('df-snapshot-guard') && !cmd.includes('df-invariant-check') && !cmd.includes('df-command-usage');
   });
 
   // Add tool usage hook
@@ -406,6 +415,14 @@ async function configureHooks(claudeDir) {
       command: invariantCheckCmd
     }]
   });
+
+  // Add command usage hook to PostToolUse
+  settings.hooks.PostToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: commandUsageCmd
+    }]
+  });
   log('PostToolUse hook configured');
 
   // Configure SubagentStop hook for subagent registry
@@ -428,6 +445,26 @@ async function configureHooks(claudeDir) {
   });
   log('SubagentStop hook configured');
 
+  // Configure PreToolUse hook for command usage instrumentation
+  if (!settings.hooks.PreToolUse) {
+    settings.hooks.PreToolUse = [];
+  }
+
+  // Remove any existing deepflow command usage hooks from PreToolUse
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(hook => {
+    const cmd = hook.hooks?.[0]?.command || '';
+    return !cmd.includes('df-command-usage');
+  });
+
+  // Add command usage hook to PreToolUse
+  settings.hooks.PreToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: commandUsageCmd
+    }]
+  });
+  log('PreToolUse hook configured');
+
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
 
@@ -611,7 +648,7 @@ async function uninstall() {
   ];
 
   if (level === 'global') {
-    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-invariant-check.js', 'hooks/df-quota-logger.js', 'hooks/df-tool-usage.js', 'hooks/df-dashboard-push.js', 'hooks/df-execution-history.js', 'hooks/df-worktree-guard.js', 'hooks/df-snapshot-guard.js', 'hooks/df-subagent-registry.js');
+    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-invariant-check.js', 'hooks/df-quota-logger.js', 'hooks/df-tool-usage.js', 'hooks/df-dashboard-push.js', 'hooks/df-execution-history.js', 'hooks/df-worktree-guard.js', 'hooks/df-snapshot-guard.js', 'hooks/df-subagent-registry.js', 'hooks/df-command-usage.js');
   }
 
   for (const item of toRemove) {
@@ -649,7 +686,7 @@ async function uninstall() {
         if (settings.hooks?.SessionEnd) {
           settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
-            return !cmd.includes('df-quota-logger') && !cmd.includes('df-dashboard-push');
+            return !cmd.includes('df-quota-logger') && !cmd.includes('df-dashboard-push') && !cmd.includes('df-command-usage');
           });
           if (settings.hooks.SessionEnd.length === 0) {
             delete settings.hooks.SessionEnd;
@@ -658,12 +695,21 @@ async function uninstall() {
         if (settings.hooks?.PostToolUse) {
           settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
-            return !cmd.includes('df-tool-usage') && !cmd.includes('df-execution-history') && !cmd.includes('df-worktree-guard') && !cmd.includes('df-snapshot-guard') && !cmd.includes('df-invariant-check');
+            return !cmd.includes('df-tool-usage') && !cmd.includes('df-execution-history') && !cmd.includes('df-worktree-guard') && !cmd.includes('df-snapshot-guard') && !cmd.includes('df-invariant-check') && !cmd.includes('df-command-usage');
           });
           if (settings.hooks.PostToolUse.length === 0) {
             delete settings.hooks.PostToolUse;
           }
         }
+        if (settings.hooks?.PreToolUse) {
+          settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(hook => {
+            const cmd = hook.hooks?.[0]?.command || '';
+            return !cmd.includes('df-command-usage');
+          });
+          if (settings.hooks.PreToolUse.length === 0) {
+            delete settings.hooks.PreToolUse;
+          }
+        }
         if (settings.hooks?.SubagentStop) {
           settings.hooks.SubagentStop = settings.hooks.SubagentStop.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
@@ -677,7 +723,7 @@ async function uninstall() {
           delete settings.hooks;
         }
         fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-        console.log(`  ${c.green}✓${c.reset} Removed SessionStart/SessionEnd/PostToolUse/SubagentStop hooks`);
+        console.log(`  ${c.green}✓${c.reset} Removed SessionStart/SessionEnd/PreToolUse/PostToolUse/SubagentStop hooks`);
       } catch (e) {
         // Fail silently
       }

package/bin/install.test.js

@@ -589,6 +589,220 @@ describe('Uninstaller — file removal and settings cleanup', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// T4. command-usage hook registration (PreToolUse, PostToolUse, SessionEnd)
+// ---------------------------------------------------------------------------
+
+describe('T4 — command-usage hook registration in install.js', () => {
+
+  // -- Source-level checks: verify install.js registers df-command-usage.js --
+
+  test('source defines commandUsageCmd variable', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    const pattern = /commandUsageCmd\s*=\s*`node.*df-command-usage\.js/;
+    assert.ok(
+      pattern.test(src),
+      'install.js should define commandUsageCmd pointing to df-command-usage.js'
+    );
+  });
+
+  test('source pushes command-usage hook to PreToolUse', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // Find PreToolUse section — should contain a push with commandUsageCmd
+    const preToolUseSection = src.match(/PreToolUse[\s\S]*?log\('PreToolUse hook configured'\)/);
+    assert.ok(preToolUseSection, 'Should have a PreToolUse configuration section');
+    assert.ok(
+      preToolUseSection[0].includes('commandUsageCmd'),
+      'PreToolUse section should push commandUsageCmd'
+    );
+  });
+
+  test('source pushes command-usage hook to PostToolUse', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // Find PostToolUse section
+    const postToolUseSection = src.match(/PostToolUse[\s\S]*?log\('PostToolUse hook configured'\)/);
+    assert.ok(postToolUseSection, 'Should have a PostToolUse configuration section');
+    assert.ok(
+      postToolUseSection[0].includes('commandUsageCmd'),
+      'PostToolUse section should push commandUsageCmd'
+    );
+  });
+
+  test('source pushes command-usage hook to SessionEnd', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // Find SessionEnd section — should include command-usage alongside quota-logger + dashboard-push
+    const sessionEndSection = src.match(/SessionEnd[\s\S]*?log\('Quota logger.*configured.*SessionEnd/);
+    assert.ok(sessionEndSection, 'Should have a SessionEnd configuration section');
+    assert.ok(
+      sessionEndSection[0].includes('commandUsageCmd'),
+      'SessionEnd section should push commandUsageCmd'
+    );
+  });
+
+  test('source creates PreToolUse array if missing', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    assert.ok(
+      src.includes("if (!settings.hooks.PreToolUse)"),
+      'install.js should initialize PreToolUse array if not present'
+    );
+  });
+
+  // -- Dedup logic: filter removes existing command-usage before re-adding --
+
+  test('PreToolUse dedup filter removes existing df-command-usage entries', () => {
+    const preToolUse = [
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+      { hooks: [{ type: 'command', command: 'node /usr/local/my-custom.js' }] },
+    ];
+
+    const filtered = preToolUse.filter(hook => {
+      const cmd = hook.hooks?.[0]?.command || '';
+      return !cmd.includes('df-command-usage');
+    });
+
+    assert.equal(filtered.length, 1, 'Should remove existing df-command-usage hook');
+    assert.ok(filtered[0].hooks[0].command.includes('my-custom.js'), 'Should keep non-deepflow hooks');
+  });
+
+  test('PostToolUse dedup filter removes df-command-usage alongside other deepflow hooks', () => {
+    const postToolUse = [
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-tool-usage.js' }] },
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-worktree-guard.js' }] },
+      { hooks: [{ type: 'command', command: 'node /usr/local/keep-me.js' }] },
+    ];
+
+    const filtered = postToolUse.filter(hook => {
+      const cmd = hook.hooks?.[0]?.command || '';
+      return !cmd.includes('df-tool-usage') &&
+             !cmd.includes('df-execution-history') &&
+             !cmd.includes('df-worktree-guard') &&
+             !cmd.includes('df-snapshot-guard') &&
+             !cmd.includes('df-invariant-check') &&
+             !cmd.includes('df-command-usage');
+    });
+
+    assert.equal(filtered.length, 1);
+    assert.ok(filtered[0].hooks[0].command.includes('keep-me.js'));
+  });
+
+  test('SessionEnd dedup filter removes df-command-usage alongside quota-logger and dashboard-push', () => {
+    const sessionEnd = [
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-quota-logger.js' }] },
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-dashboard-push.js' }] },
+      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+      { hooks: [{ type: 'command', command: 'node /usr/local/keep.js' }] },
+    ];
+
+    const filtered = sessionEnd.filter(hook => {
+      const cmd = hook.hooks?.[0]?.command || '';
+      return !cmd.includes('df-quota-logger') &&
+             !cmd.includes('df-dashboard-push') &&
+             !cmd.includes('df-command-usage');
+    });
+
+    assert.equal(filtered.length, 1);
+    assert.ok(filtered[0].hooks[0].command.includes('keep.js'));
+  });
+
+  // -- Uninstall cleanup --
+
+  test('uninstall toRemove includes df-command-usage.js', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // Find the toRemove.push(...) line for hooks in uninstall
+    assert.ok(
+      src.includes("'hooks/df-command-usage.js'"),
+      'toRemove should include hooks/df-command-usage.js for uninstall'
+    );
+  });
+
+  test('uninstall SessionEnd filter removes df-command-usage', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // In the uninstall function, the SessionEnd filter should include df-command-usage
+    // Find the uninstall section's SessionEnd filter
+    const uninstallSection = src.match(/async function uninstall[\s\S]+$/);
+    assert.ok(uninstallSection, 'Should have uninstall function');
+    // Check SessionEnd filter in uninstall includes command-usage
+    const sessionEndFilter = uninstallSection[0].match(/SessionEnd[\s\S]*?\.filter[\s\S]*?\);/);
+    assert.ok(sessionEndFilter, 'Should have SessionEnd filter in uninstall');
+    assert.ok(
+      sessionEndFilter[0].includes('df-command-usage'),
+      'Uninstall SessionEnd filter should remove df-command-usage hooks'
+    );
+  });
+
+  test('uninstall PostToolUse filter removes df-command-usage', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    const uninstallSection = src.match(/async function uninstall[\s\S]+$/);
+    const postToolUseFilter = uninstallSection[0].match(/PostToolUse[\s\S]*?\.filter[\s\S]*?\);/);
+    assert.ok(postToolUseFilter, 'Should have PostToolUse filter in uninstall');
+    assert.ok(
+      postToolUseFilter[0].includes('df-command-usage'),
+      'Uninstall PostToolUse filter should remove df-command-usage hooks'
+    );
+  });
+
+  test('uninstall cleans up PreToolUse hooks', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    const uninstallSection = src.match(/async function uninstall[\s\S]+$/);
+    assert.ok(
+      uninstallSection[0].includes('PreToolUse'),
+      'Uninstall function should handle PreToolUse cleanup'
+    );
+    // Verify it filters out df-command-usage from PreToolUse
+    const preToolUseFilter = uninstallSection[0].match(/PreToolUse[\s\S]*?\.filter[\s\S]*?\);/);
+    assert.ok(preToolUseFilter, 'Should have PreToolUse filter in uninstall');
+    assert.ok(
+      preToolUseFilter[0].includes('df-command-usage'),
+      'Uninstall PreToolUse filter should remove df-command-usage hooks'
+    );
+  });
+
+  test('uninstall deletes PreToolUse key when array becomes empty', () => {
+    // Reproduce the uninstall logic for PreToolUse
+    const settings = {
+      hooks: {
+        PreToolUse: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+        ],
+      }
+    };
+
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(hook => {
+      const cmd = hook.hooks?.[0]?.command || '';
+      return !cmd.includes('df-command-usage');
+    });
+    if (settings.hooks.PreToolUse.length === 0) {
+      delete settings.hooks.PreToolUse;
+    }
+
+    assert.ok(!('PreToolUse' in settings.hooks), 'PreToolUse should be deleted when empty after filtering');
+  });
+
+  test('uninstall keeps PreToolUse when non-deepflow hooks remain', () => {
+    const settings = {
+      hooks: {
+        PreToolUse: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+          { hooks: [{ type: 'command', command: 'node /usr/local/custom-pre-hook.js' }] },
+        ],
+      }
+    };
+
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(hook => {
+      const cmd = hook.hooks?.[0]?.command || '';
+      return !cmd.includes('df-command-usage');
+    });
+    if (settings.hooks.PreToolUse.length === 0) {
+      delete settings.hooks.PreToolUse;
+    }
+
+    assert.ok('PreToolUse' in settings.hooks, 'PreToolUse should be kept when custom hooks remain');
+    assert.equal(settings.hooks.PreToolUse.length, 1);
+    assert.ok(settings.hooks.PreToolUse[0].hooks[0].command.includes('custom-pre-hook.js'));
+  });
+});
+
 // ---------------------------------------------------------------------------
 // 4. isInstalled helper logic
 // ---------------------------------------------------------------------------

package/hooks/df-command-usage.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * deepflow command usage tracker
+ * Tracks df:* command invocations with token deltas and tool call counts.
+ *
+ * Events:
+ *   PreToolUse  — detect Skill calls matching df:*, close previous command, open new marker
+ *   PostToolUse — increment tool_calls_count on the active marker
+ *   SessionEnd  — close any open marker so the last command gets a record
+ *
+ * Marker: .deepflow/active-command.json
+ * Output: .deepflow/command-usage.jsonl (append-only)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const event = process.env.CLAUDE_HOOK_EVENT || '';
+
+// Read stdin for hook payload
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', d => raw += d);
+process.stdin.on('end', () => {
+  try {
+    main();
+  } catch (_e) {
+    // REQ-8: never break Claude Code
+  }
+  process.exit(0);
+});
+
+function main() {
+  const baseDir = findProjectDir();
+  if (!baseDir) return;
+
+  const deepflowDir = path.join(baseDir, '.deepflow');
+  const markerPath = path.join(deepflowDir, 'active-command.json');
+  const usagePath = path.join(deepflowDir, 'command-usage.jsonl');
+  const tokenHistoryPath = path.join(deepflowDir, 'token-history.jsonl');
+
+  if (event === 'PreToolUse') {
+    handlePreToolUse(deepflowDir, markerPath, usagePath, tokenHistoryPath);
+  } else if (event === 'PostToolUse') {
+    handlePostToolUse(markerPath);
+  } else if (event === 'SessionEnd') {
+    handleSessionEnd(deepflowDir, markerPath, usagePath, tokenHistoryPath);
+  }
+}
+
+function handlePreToolUse(deepflowDir, markerPath, usagePath, tokenHistoryPath) {
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; }
+
+  const toolName = payload.tool_name || '';
+  const toolInput = payload.tool_input || {};
+
+  // Only trigger on Skill calls with df:* skill names
+  if (toolName !== 'Skill') return;
+  const skillName = toolInput.skill || '';
+  if (!skillName.startsWith('df:')) return;
+
+  const sessionId = payload.session_id || process.env.CLAUDE_SESSION_ID || 'unknown';
+
+  // If marker exists, close previous command first (close-on-next)
+  if (safeExists(markerPath)) {
+    closeCommand(markerPath, usagePath, tokenHistoryPath);
+  }
+
+  // Create new marker
+  ensureDir(deepflowDir);
+  const tokenSnapshot = readLastTokenRecord(tokenHistoryPath);
+  const transcriptPath = findTranscriptPath(payload);
+  const transcriptOffset = safeFileSize(transcriptPath);
+
+  const marker = {
+    command: skillName,
+    session_id: sessionId,
+    started_at: new Date().toISOString(),
+    token_snapshot: {
+      input_tokens: tokenSnapshot.input_tokens || 0,
+      cache_read_input_tokens: tokenSnapshot.cache_read_input_tokens || 0,
+      cache_creation_input_tokens: tokenSnapshot.cache_creation_input_tokens || 0
+    },
+    transcript_path: transcriptPath,
+    transcript_offset: transcriptOffset,
+    tool_calls_count: 0
+  };
+
+  safeWriteFile(markerPath, JSON.stringify(marker, null, 2));
+}
+
+function handlePostToolUse(markerPath) {
+  if (!safeExists(markerPath)) return;
+
+  // Don't count the Skill call itself (the one that opened the marker)
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; }
+  const toolName = payload.tool_name || '';
+  const toolInput = payload.tool_input || {};
+  if (toolName === 'Skill' && (toolInput.skill || '').startsWith('df:')) return;
+
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    marker.tool_calls_count = (marker.tool_calls_count || 0) + 1;
+    safeWriteFile(markerPath, JSON.stringify(marker, null, 2));
+  } catch (_e) {
+    // Marker may have been deleted mid-session (REQ-8)
+  }
+}
+
+function handleSessionEnd(deepflowDir, markerPath, usagePath, tokenHistoryPath) {
+  if (!safeExists(markerPath)) return;
+  closeCommand(markerPath, usagePath, tokenHistoryPath);
+}
+
+/**
+ * Close the active command: compute deltas, parse transcript for output_tokens,
+ * append usage record, delete marker.
+ */
+function closeCommand(markerPath, usagePath, tokenHistoryPath) {
+  let marker;
+  try {
+    marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+  } catch (_e) {
+    safeDelete(markerPath);
+    return;
+  }
+
+  const endSnapshot = readLastTokenRecord(tokenHistoryPath);
+  const startSnapshot = marker.token_snapshot || {};
+
+  // Compute token deltas
+  const deltaIn = Math.max(0, (endSnapshot.input_tokens || 0) - (startSnapshot.input_tokens || 0));
+  const deltaCacheRead = Math.max(0, (endSnapshot.cache_read_input_tokens || 0) - (startSnapshot.cache_read_input_tokens || 0));
+  const deltaCacheCreate = Math.max(0, (endSnapshot.cache_creation_input_tokens || 0) - (startSnapshot.cache_creation_input_tokens || 0));
+
+  // Parse transcript for output_tokens
+  const outputTokens = parseTranscriptOutputTokens(
+    marker.transcript_path,
+    marker.transcript_offset || 0
+  );
+
+  const record = {
+    command: marker.command,
+    session_id: marker.session_id,
+    started_at: marker.started_at,
+    ended_at: new Date().toISOString(),
+    tool_calls_count: marker.tool_calls_count || 0,
+    input_tokens_delta: deltaIn,
+    output_tokens: outputTokens,
+    cache_read_delta: deltaCacheRead,
+    cache_creation_delta: deltaCacheCreate
+  };
+
+  // Append to usage JSONL
+  ensureDir(path.dirname(usagePath));
+  try {
+    fs.appendFileSync(usagePath, JSON.stringify(record) + '\n');
+  } catch (_e) {
+    // REQ-8: fail silently
+  }
+
+  safeDelete(markerPath);
+}
+
+/**
+ * Read the last line of token-history.jsonl by seeking the last ~2KB.
+ */
+function readLastTokenRecord(tokenHistoryPath) {
+  try {
+    if (!fs.existsSync(tokenHistoryPath)) return {};
+    const stat = fs.statSync(tokenHistoryPath);
+    if (stat.size === 0) return {};
+
+    const readSize = Math.min(stat.size, 2048);
+    const buf = Buffer.alloc(readSize);
+    const fd = fs.openSync(tokenHistoryPath, 'r');
+    fs.readSync(fd, buf, 0, readSize, stat.size - readSize);
+    fs.closeSync(fd);
+
+    const chunk = buf.toString('utf8');
+    const lines = chunk.trimEnd().split('\n');
+    const lastLine = lines[lines.length - 1].trim();
+    if (!lastLine) return {};
+    return JSON.parse(lastLine);
+  } catch (_e) {
+    return {};
+  }
+}
+
+/**
+ * Parse transcript from offset to current end, accumulating output_tokens
+ * from message.usage.output_tokens fields (pattern from df-subagent-registry.js).
+ */
+function parseTranscriptOutputTokens(transcriptPath, offset) {
+  let total = 0;
+  try {
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) return 0;
+    const stat = fs.statSync(transcriptPath);
+    if (stat.size <= offset) return 0;
+
+    const readLen = stat.size - offset;
+    const buf = Buffer.alloc(readLen);
+    const fd = fs.openSync(transcriptPath, 'r');
+    fs.readSync(fd, buf, 0, readLen, offset);
+    fs.closeSync(fd);
+
+    const slice = buf.toString('utf8');
+    const lines = slice.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const evt = JSON.parse(trimmed);
+        const usage = (evt.message && evt.message.usage) || evt.usage;
+        if (usage && usage.output_tokens) {
+          total += usage.output_tokens;
+        }
+      } catch (_e) {
+        // skip malformed lines
+      }
+    }
+  } catch (_e) {
+    // REQ-8
+  }
+  return total;
+}
+
+/**
+ * Find the project directory from hook payload or environment.
+ */
+function findProjectDir() {
+  try {
+    const payload = JSON.parse(raw);
+    if (payload.cwd) return payload.cwd;
+    if (payload.workspace && payload.workspace.current_dir) return payload.workspace.current_dir;
+  } catch (_e) {
+    // fall through
+  }
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Find the transcript path from the hook payload.
+ */
+function findTranscriptPath(payload) {
+  if (payload.transcript_path) return payload.transcript_path;
+  if (payload.session_storage_path) {
+    return path.join(payload.session_storage_path, 'transcript.jsonl');
+  }
+  return '';
+}
+
+// --- Utility helpers ---
+
+function safeExists(filePath) {
+  try { return fs.existsSync(filePath); } catch { return false; }
+}
+
+function safeDelete(filePath) {
+  try { fs.unlinkSync(filePath); } catch (_e) { /* REQ-8 */ }
+}
+
+function safeWriteFile(filePath, data) {
+  try { fs.writeFileSync(filePath, data); } catch (_e) { /* REQ-8 */ }
+}
+
+function safeFileSize(filePath) {
+  try {
+    if (!filePath) return 0;
+    if (!fs.existsSync(filePath)) return 0;
+    return fs.statSync(filePath).size;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+function ensureDir(dir) {
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  } catch (_e) { /* REQ-8 */ }
+}