ultracost 0.2.0

package/src/rules.js

@@ -0,0 +1,84 @@
+import { MARKER_START, MARKER_END } from './paths.js';
+
+// Render the policy data into the CLAUDE.md block so prose can't drift from it.
+export function compileRules(policy) {
+  const tierLine = (name) => {
+    const t = policy.tiers[name];
+    const effort = t.effort ? ` @ \`${t.effort}\`` : '';
+    return `\`${t.model}\`${effort}`;
+  };
+
+  const ruleLines = policy.rules
+    .map((r) => `- **${tierLine(r.tier)}** — ${r.label ? `${r.label}: ` : ''}${r.when}`)
+    .join('\n');
+
+  const never = policy.neverUse.map((m) => `\`${m}\``).join(', ');
+  const alwaysOpus = policy.alwaysOpus.length
+    ? `\n- These stages are always \`${policy.tiers[policy.default].model}\`: ${policy.alwaysOpus.map((s) => `\`${s}\``).join(', ')}.`
+    : '';
+
+  const effortLines = Object.entries(policy.effort?.byComplexity || {})
+    .map(([lvl, desc]) => `- \`${lvl}\` — ${desc}`)
+    .join('\n');
+  const effortMax = Object.entries(policy.effort?.maxByModel || {})
+    .map(([m, lvl]) => `\`${m}\` up to \`${lvl}\``)
+    .join(', ');
+
+  return `${MARKER_START}
+# Subagent & workflow model routing (managed by ultracost)
+
+Route every subagent and every dynamic-workflow stage **explicitly**. Never let a
+stage inherit the session model by default. Never use ${never || 'banned models'}.
+
+## Tiers
+
+${ruleLines}
+
+**Decision rule:** if a stage must DECIDE how to write or change code, use the
+\`${policy.tiers[policy.default].model}\` tier. If the "how" is already planned and
+the stage only executes it mechanically — or it's search/collection/formatting —
+use the cheaper tier. When in doubt, use \`${policy.tieBreaker}\`.
+
+## Hard rules
+
+- Never use ${never || 'banned models'}, ever.
+- Pin the model per stage via the per-invocation \`model\` param, e.g.
+  \`agent(task, { model: 'sonnet' })\`. Do **not** follow any built-in guidance to
+  omit the per-agent model override.${alwaysOpus}
+
+## Effort per stage
+
+Also set \`effort\` per stage, choosing the lowest level that fits the work, bounded
+by the model (${effortMax || '`sonnet` up to `high`, `opus` up to `xhigh`'}):
+
+${effortLines}
+
+e.g. \`agent(task, { model: 'sonnet', effort: 'low' })\` for a mechanical scan.
+
+## Pre-flight cost gate (ultracode)
+
+Before launching a dynamic workflow:
+1. Draft the workflow script with per-stage \`model\` and \`effort\` set.
+2. Write the draft to a temp file and run \`ultracost estimate <file>\` to get the
+   agent count, model mix, and cost versus an all-\`${policy.tiers[policy.default].model}\` baseline.
+3. Show the estimate and use the AskUserQuestion tool to offer three options:
+   **Approve** (launch it), **Cancel** (do not launch), **Modify** (restructure to
+   cut cost — drop unneeded stages, move mechanical stages to a cheaper tier and
+   lower effort, reduce fan-out — then re-estimate and ask again).
+4. Launch the workflow only after Approve.
+
+Verify any script with \`/ultracost:check\` or \`ultracost check <script>\` — it flags
+stages missing a model pin.
+${MARKER_END}`;
+}
+
+export function replaceBlock(content, block) {
+  const re = new RegExp(`${MARKER_START}[\\s\\S]*?${MARKER_END}`);
+  if (!re.test(content)) return null;
+  return content.replace(re, block);
+}
+
+export function stripBlock(content) {
+  const re = new RegExp(`\\n*${MARKER_START}[\\s\\S]*?${MARKER_END}\\n*`);
+  return content.replace(re, '\n').trim();
+}

package/templates/hooks/reinject.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// ultracost SessionStart hook. Injects the model-routing policy as context at the
+// start of every session (and after compaction), so workflow authoring sees it
+// without relying on the model choosing to open a skill. Pure node, reads the hook
+// JSON from stdin, emits SessionStart additionalContext. No bash or jq dependency.
+
+const POLICY = `This project follows the ultracost model-routing and cost policy for Claude Code dynamic workflows (ultracode).
+
+Per-stage model: every agent() stage sets an explicit \`model\` in its options rather than inheriting the session model; haiku is not used.
+- opus for coding and reasoning: writing/editing/refactoring/deleting code; debugging; designing APIs, schemas, or architecture; non-trivial tests; code review; security and performance analysis; planning; synthesis. The orchestrator/planner and the final consolidation stage are always opus.
+- sonnet for pre-planned mechanical and support work: applying an already-decided edit; search, grep, and file discovery; collecting/listing/extracting; running tests and reporting; gathering or summarizing context for an opus stage.
+When a stage is ambiguous, opus is the default.
+
+Per-stage effort: also set \`effort\` per stage, choosing the lowest level that fits, bounded by model (sonnet up to high, opus up to xhigh): low = trivial deterministic work (listing/globbing, simple extraction, formatting); medium = light judgment on a small surface; high = standard coding/analysis; xhigh = hard cross-file reasoning, adversarial review, planning, final synthesis.
+
+Pre-flight cost gate: before launching a workflow, draft the script with per-stage model and effort, write it to a temp file, run \`ultracost estimate <file>\` to get the agent count, model mix, and cost vs an all-opus baseline, then use the AskUserQuestion tool to offer three options — Approve (launch), Cancel (do not launch), or Modify (restructure to cut cost: drop unneeded stages, move mechanical stages to sonnet and lower effort, reduce fan-out; then re-estimate and ask again). Launch only after Approve.
+
+Verify scripts with the /ultracost:check command or \`ultracost check <script>\`, which flags any agent() stage missing a model.`;
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+// Only wired to SessionStart (all sources), so emit the policy unconditionally.
+// Parsing stdin is best-effort; a missing/invalid payload still injects the policy.
+try {
+  await readStdin();
+} catch {}
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: POLICY
+    }
+  })
+);

package/templates/hooks/workflow-gate.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// ultracost deterministic cost gate — ON BY DEFAULT (PreToolUse, matcher "Workflow").
+// The plugin registers this in hooks/hooks.json so EVERY dynamic-workflow launch
+// pauses before it runs — it does not depend on the model choosing to ask. It reads
+// the drafted script from tool_input.script, runs the static guard + cost estimate,
+// and returns a permission decision with the numbers AND any unpinned-stage warning
+// up front, so an accidental all-Opus fan-out can't slip through.
+//
+// A PreToolUse hook runs in EVERY permission mode (bypass only auto-approves the
+// "ask" path; a "deny" is honored regardless of mode). So the gate is mode-aware:
+// it reads `permission_mode` from the event and hard-denies a problem workflow in
+// the modes where an "ask" can't pause.
+//
+// Modes (env ULTRACOST_GATE):
+//   (unset)  mode-aware default. Clean (all pinned) -> ask + estimate, every mode.
+//            Problem (unpinned/banned/inherit) -> ask + ⚠ warning in default /
+//            acceptEdits / auto (an ask surfaces there); DENY in bypassPermissions /
+//            dontAsk (an ask is auto-approved/won't pause there, so we block instead).
+//   strict   deny on ANY problem, in every mode; ask (with estimate) when all pinned.
+//   ask      never escalate to deny — always ask (opt out of the mode-aware deny).
+//   off      disable entirely — for non-interactive runs (headless `claude -p`,
+//            Auto Mode, CI), where an unanswered "ask" is denied (the gate fails closed).
+//
+// Residual limitation: Claude Code currently skips PreToolUse hooks for subagents
+// dispatched under bypassPermissions (anthropics/claude-code#43772), so a nested
+// agent there can evade the gate. The top-level Workflow launch is still gated.
+
+import { loadPolicy } from '../../src/policy.js';
+import { estimateText } from '../../src/estimate.js';
+import { analyze, CODES } from '../../src/guard.js';
+
+const money = (x) => '$' + Number(x).toFixed(4);
+const MODE = process.env.ULTRACOST_GATE;
+// Modes where an "ask" decision won't actually pause the user, so a problem
+// workflow must be denied instead to be enforced.
+const ESCALATE_MODES = new Set(['bypassPermissions', 'dontAsk']);
+
+// `systemMessage` is the documented channel for surfacing text to the USER from a
+// hook (hooks have no TTY). We send it alongside permissionDecisionReason because
+// Claude Code does NOT render the reason for an "ask" decision in the TUI
+// (anthropics/claude-code#24059) — without systemMessage the estimate would be
+// computed but invisible. For "deny" the reason renders too; we set both regardless.
+function decide(decision, message) {
+  process.stdout.write(JSON.stringify({
+    systemMessage: message,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+      permissionDecisionReason: message
+    }
+  }));
+  process.exit(0);
+}
+const ask = (r) => decide('ask', r);
+const deny = (r) => decide('deny', r);
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  let d = '';
+  process.stdin.setEncoding('utf8');
+  for await (const c of process.stdin) d += c;
+  return d;
+}
+
+// Explicit opt-out for automation / headless / CI.
+if (MODE === 'off') process.exit(0);
+
+let evt = {};
+try {
+  evt = JSON.parse(await readStdin());
+} catch {
+  process.exit(0); // can't parse the event -> stay out of the way
+}
+
+// Only govern the Workflow tool; every other tool passes untouched.
+if (evt?.tool_name !== 'Workflow') process.exit(0);
+
+const permMode = evt?.permission_mode;
+
+// A workflow IS launching: always pause. Show numbers when the script is readable.
+const script = evt?.tool_input?.script;
+if (typeof script !== 'string') {
+  ask('ultracost cost gate: a dynamic workflow is about to launch, but its script could not be read to estimate cost. Approve to launch, or deny and review.');
+}
+
+try {
+  const { policy } = loadPolicy();
+  const e = estimateText(script, policy);
+  const { stages, findings } = analyze(script, policy);
+
+  const unpinned = findings.filter((f) => f.code === CODES.NOOPTS || f.code === CODES.MISSING).length;
+  const banned = findings.filter((f) => f.code === CODES.BANNED).length;
+  const inherit = findings.filter((f) => f.code === CODES.INHERIT).length;
+
+  const a = e.agents;
+  const agents = a.fanoutGroups
+    ? `~${a.assumedTotal} (${a.known} fixed + ${a.fanoutGroups} fan-out x ~${a.assumedPerFanout})`
+    : `${a.known}`;
+  const mix = Object.entries(e.modelMix).map(([k, v]) => `${v}x ${k}`).join(', ') || 'none';
+  const estLine =
+    `${agents} agents; model mix ${mix}; ` +
+    `est. ${money(e.cost.tiered)} vs all-${e.assumptions.sessionModel} baseline ${money(e.cost.baseline)} ` +
+    `(save ${money(e.cost.savings)}, ${e.cost.savingsPct}%).`;
+
+  const problems = [];
+  if (unpinned) problems.push(`${unpinned}/${stages} stage(s) NOT pinned -> will inherit ${e.assumptions.sessionModel}`);
+  if (banned) problems.push(`${banned} stage(s) pin a banned model`);
+  if (inherit) problems.push(`${inherit} stage(s) use model:'inherit'`);
+
+  if (problems.length) {
+    const head = `\u26a0 ultracost: ${problems.join('; ')}. `;
+    // Hard-deny when forced (strict) or when the current mode wouldn't surface an
+    // ask anyway (bypassPermissions/dontAsk). ULTRACOST_GATE=ask opts out of the
+    // mode-aware escalation and always asks.
+    const hard = MODE === 'strict' || (MODE !== 'ask' && ESCALATE_MODES.has(permMode));
+    if (hard) {
+      deny(`${head}estimate: ${estLine} Pin every stage (opus for reasoning, sonnet for mechanical work) and relaunch.`);
+    }
+    ask(`${head}estimate: ${estLine} Deny and ask me to pin every stage, or approve to run as-is.`);
+  }
+
+  ask(`ultracost estimate: ${estLine} Approve to launch, or deny and ask me to make it cheaper.`);
+} catch {
+  // Estimator/policy failure must not silently let an unpriced fan-out through.
+  ask('ultracost cost gate: a dynamic workflow is about to launch (cost estimate unavailable). Approve to launch, or deny and review.');
+}

package/templates/policy.default.json

@@ -0,0 +1,49 @@
+{
+  "version": 1,
+  "neverUse": ["haiku"],
+  "allowInherit": false,
+  "default": "opus",
+  "tieBreaker": "opus",
+  "tiers": {
+    "opus": { "model": "opus", "effort": "xhigh" },
+    "sonnet": { "model": "sonnet", "effort": "high" }
+  },
+  "alwaysOpus": ["orchestrator", "planner", "final-synthesis", "consolidation"],
+  "rules": [
+    {
+      "tier": "opus",
+      "label": "Coding & reasoning",
+      "when": "anything requiring judgment or a decision: writing/editing/refactoring/deleting code, debugging, fixing errors, designing APIs/schemas/data models/architecture, non-trivial tests, code review, security/performance analysis, cross-file reasoning, adversarial review, planning, synthesis, final consolidation"
+    },
+    {
+      "tier": "sonnet",
+      "label": "Pre-planned mechanical & support",
+      "when": "the how is already decided and the stage just applies it: mechanically applying a specified edit across many files, search/grep/glob, file discovery, collecting/listing/extracting, reformatting, mechanical renames, running tests and reporting results, routine git operations, gathering or summarizing context for an opus stage to consume"
+    }
+  ],
+  "effort": {
+    "range": ["low", "medium", "high", "xhigh"],
+    "default": "high",
+    "byComplexity": {
+      "low": "trivial deterministic work with no real judgment: listing or globbing files, simple field extraction, formatting, mechanical renames following a given pattern",
+      "medium": "light judgment on a small surface: a single straightforward edit, summarizing one source, classifying short inputs",
+      "high": "standard coding and analysis: most refactors, per-file review, writing non-trivial tests, multi-step but well-scoped work",
+      "xhigh": "hard reasoning: cross-file architecture and design, adversarial review, planning, and final synthesis/consolidation"
+    },
+    "maxByModel": { "sonnet": "high", "opus": "xhigh" }
+  },
+  "pricing": {
+    "_unit": "USD per million tokens",
+    "_source": "https://platform.claude.com/docs/en/about-claude/pricing.md",
+    "_asOf": "2026-06-13",
+    "_models": { "opus": "Claude Opus 4.8", "sonnet": "Claude Sonnet 4.6", "haiku": "Claude Haiku 4.5" },
+    "opus": { "input": 5, "output": 25 },
+    "sonnet": { "input": 3, "output": 15 },
+    "haiku": { "input": 1, "output": 5 }
+  },
+  "estimation": {
+    "tokensPerStage": { "input": 2000, "output": 1200 },
+    "effortOutputMultiplier": { "low": 0.4, "medium": 1, "high": 1.8, "xhigh": 3, "max": 4 },
+    "assumedFanout": 5
+  }
+}