chore(wheelhouse): cascade template@5473ac3c

Author: jdalton

.claude/hooks/fleet/token-spend-guard/README.md

@@ -0,0 +1,28 @@
+# token-spend-guard
+
+PreToolUse hook that reminds (non-fatal `exit 2`) when a **known-mechanical** Bash command runs on a **premium model or high reasoning effort**. Enforces the "Token spend: match model + effort to the job" rule.
+
+## What it catches
+
+A command whose shape is unambiguously mechanical — wheelhouse cascade (`pnpm run sync`, `chore(wheelhouse): cascade` commit), whole-tree lint autofix (`oxlint --fix .` / `fix --all`), or format sweep (`oxfmt --write .`) — while:
+
+- the model (read from the transcript's most-recent assistant `model` field) is an Opus, **or**
+- `$CLAUDE_EFFORT` is `high` / `xhigh` / `max`.
+
+Each dimension is flagged and bypassed independently. `low`/`medium` effort and Sonnet/Haiku never trigger — they're already the cheap/fast tier.
+
+## Why
+
+Mechanical work is dumb-bit propagation; a cheap/fast model at low/medium effort handles it fine. Spending premium model + high-effort tokens on cascades and autofix sweeps is wasted money. The premium tier is for design, ambiguous debugging, and security review. The trigger set is deliberately narrow so the guard never nags during real work — a false trigger would train reflex-bypassing, which defeats the rule.
+
+## Bypass
+
+- `Allow model bypass` (keep the premium model for this task) — also accepts `Allow model-spend bypass`.
+- `Allow effort bypass` (keep high effort for this task).
+- `SOCKET_TOKEN_SPEND_GUARD_DISABLED=1` (disable entirely).
+
+## Test
+
+```sh
+pnpm test
+```

.claude/hooks/fleet/token-spend-guard/index.mts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — token-spend-guard.
+//
+// Reminds (exit 2, non-fatal nudge) when a KNOWN-MECHANICAL command runs on a
+// premium model or high reasoning effort. Mechanical work — cascades, lint-
+// autofix sweeps, rename/path migrations — is dumb-bit propagation that a
+// cheap/fast model at low/medium effort handles fine; spending `opus` +
+// `high`/`xhigh`/`max` tokens on it is wasted money. Design work (architecture,
+// ambiguous debugging, security review) is what the premium tier is for.
+//
+// Two signals, both observable to a PreToolUse hook:
+//   - effort: the `$CLAUDE_EFFORT` env var (low|medium|high|xhigh|max), set by
+//     the harness for tool-use-context hooks.
+//   - model: read from the transcript's most-recent assistant event `model`
+//     field (the payload itself carries no model outside SessionStart).
+//
+// Only fires on a command whose shape is unambiguously mechanical, so it never
+// nags during real work. Reminder, not a hard block — but it sets exit 2 so the
+// agent sees it and either drops the model/effort or types a bypass.
+//
+// Bypass: "Allow model bypass" (keep the premium model) or "Allow effort
+// bypass" (keep high effort) in a recent user turn, or
+// SOCKET_TOKEN_SPEND_GUARD_DISABLED=1.
+
+import { getDefaultLogger } from '@socketsecurity/lib-stable/logger/default'
+import process from 'node:process'
+
+import { withBashGuard } from '../_shared/payload.mts'
+import { bypassPhrasePresent, readLines } from '../_shared/transcript.mts'
+
+const logger = getDefaultLogger()
+
+const MODEL_BYPASS = ['Allow model bypass', 'Allow model-spend bypass'] as const
+const EFFORT_BYPASS = ['Allow effort bypass'] as const
+
+// Effort levels that count as "premium" — the tiers worth conserving on
+// mechanical work. low/medium are already cheap, so they never trigger.
+const PREMIUM_EFFORT = new Set(['high', 'xhigh', 'max'])
+
+// A model id is "premium" when it's an Opus. Sonnet/Haiku are the cheap/fast
+// tier the guard nudges toward. Matches both alias and full-id shapes
+// (`opus`, `claude-opus-4-8`, `claude-opus-4-8[1m]`).
+function isPremiumModel(model: string): boolean {
+  return /\bopus\b/i.test(model) || /claude-opus/i.test(model)
+}
+
+// Command shapes that are unambiguously mechanical. Kept deliberately narrow:
+// a false trigger on real work would train the agent to reflex-bypass, which
+// defeats the rule. Each entry is a substring/RE checked against the command.
+const MECHANICAL_RE = [
+  // Wheelhouse cascade sync + its commit.
+  /\bpnpm\s+run\s+sync\b/,
+  /chore\(wheelhouse\):\s*cascade\b/,
+  // Mass autofix / format sweeps (the whole-tree variants, not a single file).
+  /\b(?:pnpm\s+(?:run|exec)\s+)?(?:oxlint|eslint)\b[^\n]*--fix\b[^\n]*(?:\s\.|--all)\b/,
+  /\b(?:pnpm\s+run\s+)?fix\b\s+--all\b/,
+  /\boxfmt\b[^\n]*--write\b[^\n]*\s\.(?:\s|$)/,
+] as const
+
+function isMechanical(command: string): boolean {
+  return MECHANICAL_RE.some(re => re.test(command))
+}
+
+// Read the model from the most-recent assistant event in the transcript.
+// Returns '' when unreadable — the guard then can't judge the model and only
+// considers effort.
+function readCurrentModel(transcriptPath: string | undefined): string {
+  const lines = readLines(transcriptPath)
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i]
+    if (!line || !line.includes('"model"')) {
+      continue
+    }
+    try {
+      const evt = JSON.parse(line) as { model?: unknown; type?: unknown }
+      if (typeof evt.model === 'string' && evt.model) {
+        return evt.model
+      }
+    } catch {
+      // Skip malformed lines.
+    }
+  }
+  return ''
+}
+
+await withBashGuard((command, payload) => {
+  if (process.env['SOCKET_TOKEN_SPEND_GUARD_DISABLED']) {
+    return
+  }
+  if (!isMechanical(command)) {
+    return
+  }
+
+  const effort = String(process.env['CLAUDE_EFFORT'] ?? '').toLowerCase()
+  const model = readCurrentModel(payload.transcript_path)
+
+  const effortIsPremium = PREMIUM_EFFORT.has(effort)
+  const modelIsPremium = !!model && isPremiumModel(model)
+
+  // Each dimension is independently bypassable, so only flag the dimensions
+  // that are both premium AND not bypassed for this turn.
+  const flagModel =
+    modelIsPremium &&
+    !bypassPhrasePresent(payload.transcript_path, MODEL_BYPASS)
+  const flagEffort =
+    effortIsPremium &&
+    !bypassPhrasePresent(payload.transcript_path, EFFORT_BYPASS)
+
+  if (!flagModel && !flagEffort) {
+    return
+  }
+
+  const lines = [
+    '[token-spend-guard] Mechanical command on a premium setting.',
+    '',
+  ]
+  if (flagModel) {
+    lines.push(
+      `  model  : ${model} — premium. Mechanical work runs fine on a`,
+      '           cheap/fast model. Switch: /model sonnet  (or haiku).',
+      '           Keep it for this task: type "Allow model bypass".',
+    )
+  }
+  if (flagEffort) {
+    lines.push(
+      `  effort : ${effort} — premium. Drop it: /effort low  (or medium).`,
+      '           Keep it for this task: type "Allow effort bypass".',
+    )
+  }
+  lines.push(
+    '',
+    '  Mechanical = cascades, lint-autofix sweeps, rename/path migrations.',
+    '  Reserve premium model + high effort for design, hard debugging,',
+    '  security review. Disable entirely: SOCKET_TOKEN_SPEND_GUARD_DISABLED=1.',
+    '',
+  )
+  logger.error(lines.join('\n') + '\n')
+  process.exitCode = 2
+})

.claude/hooks/fleet/token-spend-guard/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "hook-token-spend-guard",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mts"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:"
+  }
+}

.claude/hooks/fleet/token-spend-guard/test/index.test.mts

@@ -0,0 +1,121 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from '@socketsecurity/lib-stable/process/spawn/child'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const HOOK_PATH = path.join(__dirname, '..', 'index.mts')
+
+// Build a transcript whose most-recent assistant event uses `model`, plus an
+// optional user line (for bypass-phrase tests).
+function makeTranscript(model: string, userText?: string): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'tokenspend-'))
+  const p = path.join(dir, 'session.jsonl')
+  const lines = []
+  if (userText) {
+    lines.push(JSON.stringify({ role: 'user', content: userText }))
+  }
+  lines.push(JSON.stringify({ type: 'assistant', model, content: [] }))
+  writeFileSync(p, lines.join('\n'))
+  return p
+}
+
+function runHook(
+  command: string,
+  transcriptPath: string,
+  effort: string,
+  extraEnv: Record<string, string> = {},
+): { stderr: string; exitCode: number } {
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: JSON.stringify({
+      tool_name: 'Bash',
+      tool_input: { command },
+      transcript_path: transcriptPath,
+    }),
+    env: { ...process.env, CLAUDE_EFFORT: effort, ...extraEnv },
+  })
+  return { stderr: String(result.stderr), exitCode: result.status ?? -1 }
+}
+
+const CASCADE = 'pnpm run sync --target . --fix'
+
+test('REMINDS on mechanical command + premium model (opus)', () => {
+  const t = makeTranscript('claude-opus-4-8')
+  const { stderr, exitCode } = runHook(CASCADE, t, 'low')
+  assert.equal(exitCode, 2)
+  assert.match(stderr, /token-spend-guard/)
+  assert.match(stderr, /premium/)
+  assert.match(stderr, /opus/)
+})
+
+test('REMINDS on mechanical command + premium effort (high)', () => {
+  const t = makeTranscript('claude-sonnet-4-6')
+  const { stderr, exitCode } = runHook(CASCADE, t, 'high')
+  assert.equal(exitCode, 2)
+  assert.match(stderr, /effort/)
+})
+
+test('ALLOWS mechanical command on cheap model + low effort', () => {
+  const t = makeTranscript('claude-sonnet-4-6')
+  const { exitCode } = runHook(CASCADE, t, 'low')
+  assert.equal(exitCode, 0)
+})
+
+test('ALLOWS a non-mechanical command even on premium model + high effort', () => {
+  const t = makeTranscript('claude-opus-4-8')
+  const { exitCode } = runHook('git status', t, 'high')
+  assert.equal(exitCode, 0)
+})
+
+test('model bypass silences the model flag (effort low → fully clears)', () => {
+  const t = makeTranscript('claude-opus-4-8', 'Allow model bypass')
+  const { exitCode } = runHook(CASCADE, t, 'low')
+  assert.equal(exitCode, 0)
+})
+
+test('effort bypass silences the effort flag (cheap model → fully clears)', () => {
+  const t = makeTranscript('claude-sonnet-4-6', 'Allow effort bypass')
+  const { exitCode } = runHook(CASCADE, t, 'max')
+  assert.equal(exitCode, 0)
+})
+
+test('one bypass does NOT silence the other dimension', () => {
+  // opus + high, only model bypassed → effort still flags.
+  const t = makeTranscript('claude-opus-4-8', 'Allow model bypass')
+  const { stderr, exitCode } = runHook(CASCADE, t, 'high')
+  assert.equal(exitCode, 2)
+  assert.match(stderr, /effort/)
+  assert.doesNotMatch(stderr, /Switch: \/model/)
+})
+
+test('cascade commit subject triggers the guard', () => {
+  const t = makeTranscript('claude-opus-4-8')
+  const { exitCode } = runHook(
+    'git commit -m "chore(wheelhouse): cascade template@abc123"',
+    t,
+    'low',
+  )
+  assert.equal(exitCode, 2)
+})
+
+test('disabled env var short-circuits', () => {
+  const t = makeTranscript('claude-opus-4-8')
+  const { exitCode } = runHook(CASCADE, t, 'high', {
+    SOCKET_TOKEN_SPEND_GUARD_DISABLED: '1',
+  })
+  assert.equal(exitCode, 0)
+})
+
+test('IGNORES non-Bash tools', () => {
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: JSON.stringify({
+      tool_name: 'Write',
+      tool_input: { command: CASCADE },
+    }),
+    env: { ...process.env, CLAUDE_EFFORT: 'high' },
+  })
+  assert.equal(result.status, 0)
+})

.claude/hooks/fleet/token-spend-guard/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "declarationMap": false,
+    "erasableSyntaxOnly": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "target": "esnext",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  }
+}

.config/fleet/oxlint-plugin/test/no-top-level-await.test.mts

@@ -0,0 +1,55 @@
+/**
+ * @file Unit tests for the no-top-level-await oxlint rule. Spawns the real
+ *   oxlint binary against fixture files in a tmp dir (see lib/rule-tester.mts).
+ *   Skips silently when `oxlint` isn't on PATH so a fresh-laptop checkout
+ *   doesn't false-fail before `pnpm install` materializes the bin link.
+ *
+ *   Why the rule exists: fleet bundles publish to CJS (rolldown CJS output)
+ *   and CJS does not support module-scope `await`. A regression there either
+ *   fails the bundle outright or silently emits an uninitialized export.
+ *   The valid cases pin the supported escape hatches (await inside an async
+ *   function, an async IIFE, the `socket-hook: allow top-level-await`
+ *   comment) so a future refactor can't quietly drop them.
+ */
+
+import { describe, test } from 'node:test'
+
+import rule from '../rules/no-top-level-await.mts'
+import { RuleTester } from '../lib/rule-tester.mts'
+
+describe('socket/no-top-level-await', () => {
+  test('valid + invalid cases', () => {
+    new RuleTester().run('no-top-level-await', rule, {
+      valid: [
+        {
+          name: 'await inside async function',
+          code: 'async function f() { await Promise.resolve() }\n',
+        },
+        {
+          name: 'await inside async arrow',
+          code: 'const f = async () => { await Promise.resolve() }\n',
+        },
+        {
+          name: 'await inside async IIFE',
+          code: ';(async () => { await Promise.resolve() })()\n',
+        },
+        {
+          name: 'bypass comment opts module out',
+          code: '// socket-hook: allow top-level-await\nawait Promise.resolve()\n',
+        },
+      ],
+      invalid: [
+        {
+          name: 'top-level await expression',
+          code: 'await Promise.resolve()\n',
+          errors: [{ messageId: 'banned' }],
+        },
+        {
+          name: 'top-level for await',
+          code: 'for await (const x of [1, 2]) {}\n',
+          errors: [{ messageId: 'banned' }],
+        },
+      ],
+    })
+  })
+})