ultracost 0.2.1 → 0.3.0

package/docs/ESTIMATES.md

@@ -175,6 +175,30 @@ model invokes, rather than from the kernel. This is documented, not hidden.
   is denied, so set `ULTRACOST_GATE=off` there. The 3-option AskUserQuestion menu needs a
   TUI session.
 
+## The closed loop (calibration, reconcile, ledger, budget)
+
+The estimate above is *static* — it runs before the workflow. Phase 2 closes the loop by
+reading the workflow's real token usage back from local transcripts (offline) and feeding it
+forward:
+
+- **`ultracost reconcile [--last|<wfId>]`** matches a real run's per-stage token usage
+  (`subagents/workflows/wf_*/agent-*.jsonl` + `journal.jsonl`) against the all-opus baseline,
+  using cache-aware pricing (`estimation.cacheMultipliers`, default cache-read `0.1x` / cache-write
+  `1.25x` input). Per-stage attribution is by file path + `isSidechain`/`agentId`, never `sessionId`
+  (subagent files inherit the parent session id).
+- **`ultracost calibrate`** turns those per-stage token sizes into a prior
+  (`~/.claude/ultracost/calibration.json`), dropping outliers beyond `3x` / below `0.2x` the median.
+  `estimate`, `explain`, `simulate`, and the gate use it automatically when present, replacing the
+  flat `tokensPerStage` default with your measured numbers.
+- **`ultracost usage`** reports real cost split across the main loop, plain subagents, and
+  dynamic-workflow stages.
+- **`ultracost ledger`** persists per-run savings (`~/.claude/ultracost/ledger.jsonl`, idempotent
+  per workflow id) and reports the cumulative total versus all-opus.
+- **Budget guard.** `budget.perRun` / `budget.perDay` make the `PreToolUse` gate **deny** a launch
+  whose estimate would exceed the cap (per-day reads the ledger's spend for the current day).
+
+All of this is offline and Claude-Code-only; nothing leaves the machine.
+
 ## Validation (live, multi-domain)
 
 Drafted by Claude under the plugin across domains; each script guard-clean (every stage

package/docs/PUBLISHING.md

@@ -5,9 +5,9 @@ first, then work down the distribution list.
 
 > **External-site note.** Anthropic plugin/marketplace facts below were verified against
 > the official docs (`code.claude.com/docs/en/plugins`,
-> `code.claude.com/docs/en/plugin-marketplaces`) on **2026-06-14**. Third-party sites
-> (awesome lists, auto-trackers) come from the project plan — confirm their current
-> submission rules on each site before relying on them, since they change.
+> `code.claude.com/docs/en/plugin-marketplaces`) on **2026-06-14**. The third-party
+> directory mechanics (awesome lists, auto-trackers) were also checked on **2026-06-14** —
+> confirm their current submission rules on each site before relying on them, since they change.
 
 ---
 
@@ -17,13 +17,13 @@ The GitHub handle is set to `danielkremen818` across the repo. If you fork or mo
 update the handle in every file that ships:
 
 - [x] `package.json` — `repository.url`, `bugs.url`, `homepage`.
-- [x] `README.md` — the npm install command (`npx ultracost init`) and the npm/CI badge URLs.
+- [x] `README.md` — the plugin install commands (`/plugin marketplace add danielkremen818/ultracost` → `/plugin install ultracost@ultracost`), the npm install command (`npx ultracost init`), and the npm/CI badge URLs.
 - [x] `CHANGELOG.md` — the `[Unreleased]`/release compare links.
 - [x] `.claude-plugin/plugin.json` — `homepage` and `repository`; also confirm `author` and `version`.
 - [ ] `LICENSE` and `NOTICE` — confirm the copyright holder.
 
-Names that must stay consistent across the plugin package and the docs (so the planned
-plugin install works once it is published):
+Names that must stay consistent across the plugin package and the docs (so the live
+plugin install keeps working):
 
 - Marketplace name: **`ultracost`** and plugin name: **`ultracost`** → the plugin resolves
   as `ultracost@ultracost`.
@@ -67,37 +67,44 @@ Anthropic runs a public community marketplace, `anthropics/claude-plugins-commun
 users add with `/plugin marketplace add anthropics/claude-plugins-community` and install
 from as `@claude-community`. Approved plugins also surface on `claude.com/plugins`.
 
-Submit through the in-app directory form. The project plan points to the short link
-**`clau.de/plugin-directory-submission`**. As of 2026-06-14 the official docs list these
-canonical submission entry points:
+Submit a **public GitHub link** (or a zip) through the in-app directory form. The short link
+**`clau.de/plugin-directory-submission`** redirects to the canonical entry points:
 
-- **claude.ai:** `claude.ai/admin-settings/directory/submissions/plugins/new` — requires a
-  Team or Enterprise org with directory-management access (org Owners have it by default).
 - **Console:** `platform.claude.com/plugins/submit` — for individual authors not in a
   Team/Enterprise org.
+- **claude.ai:** `claude.ai/admin-settings/directory/submissions/plugins/new` — requires a
+  Team or Enterprise org with directory-management access (org Owners have it by default).
 
 What to know:
 
-- Submissions go through an **automated safety screening** plus the same
-  `claude plugin validate` check the pipeline runs — pass it locally first.
-- Approved plugins are pinned to a specific commit SHA in the community catalog; CI bumps the
-  pin as you push. The public catalog **syncs nightly**, so expect a delay between approval
-  and your plugin appearing.
+- Submissions run `claude plugin validate` **plus an automated safety screening** — pass the
+  validate locally first.
+- On approval the plugin is **pinned to a commit SHA**, **synced nightly** (expect a delay
+  before it appears), and also shown at `claude.com/plugins`. Future pushes **auto-mirror** —
+  no re-submission needed.
 - The separate **official** marketplace (`claude-plugins-official`) is curated by Anthropic
   at its discretion — there's no application; the submission form does not add to it.
 
-### 2. Your own marketplace repo
+### 2. Your own marketplace repo (live now)
 
-ultracost ships its own `.claude-plugin/marketplace.json`, so the repo can serve as a
-self-hosted plugin marketplace once that install path is announced. **Not yet documented as
-user-facing** — the README leads with the npm CLI (`npx ultracost init`) for now. When the
-plugin distribution is published, surface the marketplace-add + install steps here and in the
-README and launch posts.
+ultracost ships its own `.claude-plugin/marketplace.json`, so the repo **is** a self-hosted
+plugin marketplace — no extra hosting required. Users install straight from it inside Claude
+Code:
 
-### 3. awesome-claude-code (hesreallyhim)
+```text
+/plugin marketplace add danielkremen818/ultracost
+/plugin install ultracost@ultracost
+```
+
+These are the commands the README leads with; keep them in sync across the README, this doc,
+and launch posts.
 
-A large, high-traffic curated list (the plan notes ~45k stars — verify the current count).
-Submit via the repo's contribution form/PR process. Their bar, which ultracost already meets:
+### 3. awesome-claude-code (hesreallyhim, ~46k stars)
+
+A large, high-traffic curated list. **Submit via the issue form only** —
+`https://github.com/hesreallyhim/awesome-claude-code/issues/new?template=recommend-resource.yml`.
+**Do not open a PR** (PRs are auto-closed and trigger a submission cooldown). Their bar, which
+ultracost already meets:
 
 - **Evidence-based claims** — lead with the audit finding (most real `ultracode` stages are
   unpinned; even Anthropic's bundled `deep-research` workflow pins zero stages) and a short
@@ -106,17 +113,17 @@ Submit via the repo's contribution form/PR process. Their bar, which ultracost a
 - **No telemetry, no network calls** — ultracost is a local static analyzer + file installer;
   it makes no outbound requests.
 
-### 4. Auto-trackers (passive listings)
-
-These sites index public Claude Code plugin/marketplace repos automatically; a public repo
-with a valid `marketplace.json` is usually enough. Per the plan:
+### 4. Third-party directories (passive + light intake)
 
-- `awesomeclaudeplugins.com`
-- `claudecodemarketplace.com`
-- `claudecodeplugins.dev`
+These sites index public Claude Code plugin/marketplace repos. Intake differs per site:
 
-Confirm each site's current intake (some have a submit form, some scrape) before assuming a
-listing.
+- **`claudemarketplaces.com`** — **no submission form**; it auto-crawls GitHub daily for repos
+  with a valid `.claude-plugin/marketplace.json`. Quality gate: **5+ GitHub stars**. Listed
+  within ~24h of meeting the bar.
+- **`buildwithclaude.com`** — open a PR at `buildwithclaude.com/contribute` (repo
+  `davepoon/buildwithclaude`); it also indexes GitHub on its own.
+- **ClaudePluginHub (`claudepluginhub.com`)** — submit the repo URL for fast indexing;
+  otherwise auto-discovered via GitHub Code Search.
 
 ### 5. npm publish + GitHub release
 

package/docs/architecture.md

@@ -49,11 +49,29 @@ flowchart TD
     class POL,RUL,GRD ft;
 ```
 
+## Phase 2 modules (precision, visuals, closed loop)
+
+The shared core grew three capability groups, all zero-dependency:
+
+- **Precision** — `lexer.js` (a hand-rolled JS tokenizer) backs `guard.js`, and `classify.js`
+  scores a prompt's tier so the guard can flag wrong-tier (`UC006`), over-effort (`UC007`), and
+  off-opus `alwaysOpus` roles (`UC008`).
+- **Visuals** — `render.js` (truecolor/256/16 with `NO_COLOR`/`FORCE_COLOR`, ANSI-aware width via
+  `util.stripVTControlCharacters` + `Intl.Segmenter`, tables/bars/sparklines/panels) backs `log.js`
+  and every command; the cost gate emits an aligned multi-line table.
+- **Closed loop** — `transcript.js` reads local session transcripts and attributes tokens per
+  workflow stage, `cost.js` prices them (cache-aware), and `loop.js` reconciles, calibrates, and
+  keeps the savings ledger. `detect.js` tells `status`/`doctor`/`init` how ultracost is delivered
+  (plugin vs CLI vs both) so they never misreport or double-install.
+
+The SessionStart hook (`reinject.mjs`) and the routing skill are both compiled from
+`rules.js`, so the CLAUDE.md block, the injected context, and the skill cannot drift.
+
 ## The two surfaces
 
 | | Plugin (primary) | npm CLI (secondary) |
 |---|---|---|
-| **Install** | ships in-repo; a separate install path is planned (not yet announced) | `npx ultracost init` (the install path today) |
+| **Install** | `/plugin marketplace add danielkremen818/ultracost` → `/plugin install ultracost@ultracost` | `npx ultracost init` |
 | **Routing guidance** | **`SessionStart` hook** injects the policy as context (no file mutation); a skill ships alongside for explicit reference | block injected into `~/.claude/CLAUDE.md` |
 | **Guard** | `/ultracost:check` command (runs `guard.js`) | `ultracost check` / `ultracost audit` |
 | **Policy injection** | `hooks/hooks.json` → `node "${CLAUDE_PLUGIN_ROOT}/templates/hooks/reinject.mjs"` (all `SessionStart` sources) | `node "<config>/ultracost/reinject.mjs"`, registered in `settings.json` |

package/docs/policy.md

@@ -5,7 +5,7 @@ The policy lives at `~/.claude/ultracost/policy.json` after install. Edit it, th
 
 ```json
 {
-  "version": 1,
+  "version": 2,
   "neverUse": ["haiku"],
   "allowInherit": false,
   "default": "opus",
@@ -30,8 +30,31 @@ The policy lives at `~/.claude/ultracost/policy.json` after install. Edit it, th
 | `default` | string | Tier used by `--fix` and recommended as the fallback. Must exist in `tiers`. |
 | `tieBreaker` | string | Tier the rules tell Claude to use "when in doubt". |
 | `tiers` | object | Named tiers. Each has `model` (alias or full id) and optional `effort`. A tier whose `model` is in `neverUse` is rejected at load time. |
-| `alwaysOpus` | string[] | Stage roles that must always use the default tier (orchestrator, final synthesis, …). Rendered into the rules. |
+| `alwaysOpus` | string[] | Stage roles that must always use the default tier (orchestrator, final synthesis, …). Rendered into the rules **and** enforced by the guard: a stage whose prompt reads like one of these roles but pins a cheaper tier raises `UC008`. |
 | `rules` | object[] | Human/LLM-facing routing guidance. Each has `tier`, optional `label`, and `when` (the natural-language criteria). |
+| `classify.keywords` | object | Optional extra `opus`/`sonnet` keyword signals, merged with the built-in rubric, used by the `UC006` wrong-tier check and `ultracost explain`. The opening imperative verb of a prompt is weighted most. |
+| `budget.perRun` | number\|null | Pre-flight cap (USD) on a single workflow launch. When the estimate exceeds it, the cost gate **denies** the launch. `null` = no cap. |
+| `budget.perDay` | number\|null | Pre-flight cap (USD) on a day's spend; the gate sums today's recorded ledger spend plus the new estimate. `null` = no cap. |
+| `estimation.cacheMultipliers` | object | `cacheRead` / `cacheWrite` factors applied to cached input tokens when pricing real transcript usage (`usage`/`reconcile`/`ledger`). Defaults `0.1` / `1.25`. |
+
+## New guard codes (v2)
+
+| Code | Severity | Meaning |
+|------|----------|---------|
+| `UC006` | warning | The pinned model disagrees with the work the prompt describes (e.g. a `refactor` stage on `sonnet`, or a `grep` stage on `opus`). Heuristic; only fires on a confident, literal prompt. |
+| `UC007` | warning | The pinned `effort` exceeds the model's `effort.maxByModel` cap (e.g. `sonnet` @ `xhigh`). |
+| `UC008` | warning | A stage that reads like an `alwaysOpus` role pins a non-default tier. |
+
+`UC006`–`UC008` are warnings — they never change the exit code on their own (only the
+pin-presence errors `UC001`–`UC004` do). The wrong-tier scoring is deterministic and offline.
+
+## The closed loop
+
+`ultracost calibrate` writes a token prior learned from your real runs to
+`~/.claude/ultracost/calibration.json`; `estimate`, `explain`, `simulate`, and the cost gate
+use it automatically when present. `ultracost ledger` persists per-run savings to
+`~/.claude/ultracost/ledger.jsonl`. Both are local and offline. See
+[ESTIMATES.md](./ESTIMATES.md) for the cost model and reconciliation details.
 
 ## Notes on effort
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracost",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Per-stage model routing for Claude Code dynamic workflows (ultracode). Quality-first policy, CLAUDE.md rule injection, and a workflow-script guard that catches subagent stages that would silently inherit Opus.",
   "type": "module",
   "bin": {

package/src/classify.js

@@ -0,0 +1,125 @@
+import { tierModel } from './policy.js';
+
+// Deterministic, offline keyword scorer that maps a stage's prompt to the tier the
+// work *reads like*, so the guard can flag a pin that disagrees with the task
+// (UC006) without an LLM. The imperative verb that opens a prompt is the strongest
+// signal ("List ...", "Design ...", "Apply ..."), so the first matched keyword is
+// weighted heavily and later words only break ties. Keyword lists are reused from
+// the public model-router rubrics (smart-router / model-matchmaker / model-changer)
+// and can be extended per policy via policy.classify.keywords.
+
+const DEFAULT_KEYWORDS = {
+  opus: [
+    'design', 'architect', 'architecture', 'refactor', 'rewrite', 'debug', 'review',
+    'audit', 'analyze', 'analyse', 'plan', 'planning', 'synthesize', 'synthesise',
+    'synthesis', 'consolidate', 'evaluate', 'assess', 'optimize', 'optimise',
+    'investigate', 'diagnose', 'reason', 'implement', 'security', 'vulnerability'
+  ],
+  sonnet: [
+    'list', 'find', 'search', 'grep', 'glob', 'collect', 'gather', 'extract', 'fetch',
+    'read', 'scan', 'enumerate', 'count', 'format', 'rename', 'apply', 'run', 'execute',
+    'summarize', 'summarise', 'copy', 'move', 'retrieve', 'lookup', 'locate', 'file',
+    'files', 'tests'
+  ]
+};
+
+// alwaysOpus role names matched only as specific words — deliberately NOT 'plan'
+// (too ambiguous, e.g. "the plan glob"). Custom roles fall back to their own long words.
+const ROLE_SYNONYMS = {
+  orchestrator: ['orchestrator', 'orchestrate'],
+  planner: ['planner'],
+  'final-synthesis': ['synthesis', 'synthesize', 'synthesise'],
+  consolidation: ['consolidation', 'consolidate']
+};
+
+const words = (s) => String(s || '').toLowerCase().split(/[^a-z]+/).filter(Boolean);
+
+function keywordSet(tier, policy) {
+  const extra = policy?.classify?.keywords?.[tier] || [];
+  return new Set([...DEFAULT_KEYWORDS[tier], ...extra.map((w) => String(w).toLowerCase())]);
+}
+
+// Map a model alias/id to its tier name for comparison ('opus' | 'sonnet' | 'haiku').
+export function tierOfModel(model) {
+  const v = String(model).toLowerCase();
+  if (v.includes('sonnet')) return 'sonnet';
+  if (v.includes('haiku')) return 'haiku';
+  return 'opus';
+}
+
+export function classifyPrompt(prompt, policy = {}) {
+  const opus = keywordSet('opus', policy);
+  const sonnet = keywordSet('sonnet', policy);
+  const scores = { opus: 0, sonnet: 0 };
+  const matched = [];
+  for (const w of words(prompt)) {
+    const tier = opus.has(w) ? 'opus' : sonnet.has(w) ? 'sonnet' : null;
+    if (!tier) continue;
+    scores[tier] += matched.length === 0 ? 3 : 1; // leading verb dominates
+    matched.push(w);
+  }
+  const winner = scores.opus === scores.sonnet ? null : scores.opus > scores.sonnet ? 'opus' : 'sonnet';
+  const top = Math.max(scores.opus, scores.sonnet);
+  const margin = Math.abs(scores.opus - scores.sonnet);
+  let confidence = 'none';
+  if (winner) confidence = top >= 3 && margin >= 2 ? 'high' : 'low';
+  return { tier: winner, confidence, scores, matched };
+}
+
+function matchedRole(prompt, roles = []) {
+  const set = new Set(words(prompt));
+  for (const role of roles) {
+    const syns = ROLE_SYNONYMS[role] || words(role).filter((w) => w.length >= 5);
+    if (syns.some((s) => set.has(s))) return role;
+  }
+  return null;
+}
+
+const effortRank = (effort, policy) => {
+  const range = policy?.effort?.range || ['low', 'medium', 'high', 'xhigh'];
+  return range.indexOf(effort);
+};
+
+// Advisory (warning-level) findings for a stage whose model is a valid literal pin:
+//   UC006 the pinned model disagrees with the work the prompt describes,
+//   UC007 the effort exceeds the model's cap,
+//   UC008 an alwaysOpus role is pinned to a non-default tier.
+// Returns partial finding objects ({ code, severity, message }); the caller adds
+// file/line/column. Conservative by design — only fires on confident signals.
+export function semanticFindings({ model, effort, prompt }, policy, CODES) {
+  const out = [];
+  const mtier = tierOfModel(model);
+  const defaultTier = tierOfModel(tierModel(policy.default, policy));
+
+  if (prompt) {
+    const c = classifyPrompt(prompt, policy);
+    if (c.tier && c.confidence === 'high' && c.tier !== mtier) {
+      out.push({
+        code: CODES.WRONGTIER,
+        severity: 'warn',
+        message: `stage reads like ${c.tier} work (${c.matched.slice(0, 3).join(', ')}) but pins "${model}" — consider model: '${c.tier}'`
+      });
+    }
+    const role = matchedRole(prompt, policy.alwaysOpus);
+    if (role && mtier !== defaultTier) {
+      out.push({
+        code: CODES.ALWAYSOPUS,
+        severity: 'warn',
+        message: `stage looks like the "${role}" role (policy.alwaysOpus) but pins "${model}" — these stay on ${tierModel(policy.default, policy)}`
+      });
+    }
+  }
+
+  if (effort) {
+    const cap = policy?.effort?.maxByModel?.[mtier];
+    if (cap && effortRank(effort, policy) > effortRank(cap, policy) && effortRank(effort, policy) !== -1) {
+      out.push({
+        code: CODES.OVEREFFORT,
+        severity: 'warn',
+        message: `effort '${effort}' exceeds the '${cap}' cap for ${mtier} (policy.effort.maxByModel)`
+      });
+    }
+  }
+
+  return out;
+}

package/src/cost.js

@@ -0,0 +1,54 @@
+// Turn real transcript token usage into USD, using the policy's per-model rates plus
+// cache multipliers (cache reads bill at ~0.1x input, cache writes at ~1.25x — the
+// pattern Claude Code's own cost math uses). Model ids are resolved by substring so
+// both aliases (claude-opus-4-8) and dated ids (claude-sonnet-4-6-20250929) price.
+
+const PRICE_KEYS = ['opus', 'sonnet', 'haiku'];
+
+export function modelPrice(model, policy) {
+  const v = String(model || '').toLowerCase();
+  const key = PRICE_KEYS.find((k) => v.includes(k)) || 'opus';
+  return policy?.pricing?.[key] || policy?.pricing?.opus || { input: 5, output: 25 };
+}
+
+// Cache-creation tokens: prefer the flat field, else sum the newer nested ephemeral
+// buckets (cache_creation.ephemeral_5m_input_tokens + ephemeral_1h_input_tokens).
+function cacheCreate(u) {
+  if (typeof u.cache_creation_input_tokens === 'number') return u.cache_creation_input_tokens;
+  const c = u.cache_creation;
+  if (c) return (c.ephemeral_5m_input_tokens || 0) + (c.ephemeral_1h_input_tokens || 0);
+  return 0;
+}
+
+// Sum a list of message.usage objects into one normalized usage record.
+export function sumUsage(list) {
+  const acc = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
+  for (const u of list) {
+    if (!u) continue;
+    acc.input_tokens += u.input_tokens || 0;
+    acc.output_tokens += u.output_tokens || 0;
+    acc.cache_creation_input_tokens += cacheCreate(u);
+    acc.cache_read_input_tokens += u.cache_read_input_tokens || 0;
+  }
+  return acc;
+}
+
+// USD for one usage record at a given price ({ input, output } per MTok).
+export function costFromUsage(usage, price, policy) {
+  const mult = policy?.estimation?.cacheMultipliers || { cacheRead: 0.1, cacheWrite: 1.25 };
+  const u = usage || {};
+  const input = u.input_tokens || 0;
+  const output = u.output_tokens || 0;
+  const cr = u.cache_read_input_tokens || 0;
+  const cw = u.cache_creation_input_tokens || 0;
+  return (
+    input * price.input +
+    output * price.output +
+    cr * price.input * (mult.cacheRead ?? 0.1) +
+    cw * price.input * (mult.cacheWrite ?? 1.25)
+  ) / 1e6;
+}
+
+// Total tokens billed (for display) — every bucket counts as a token moved.
+export const totalTokens = (u) =>
+  (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0);

package/src/detect.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  CLAUDE_MD, SETTINGS, SETTINGS_LOCAL, HOOK_PATH, POLICY_PATH,
+  PLUGIN_CACHE_DIR, PLUGIN_ID, MARKER_START
+} from './paths.js';
+
+// How ultracost is actually wired into Claude Code. The plugin ships its hooks via
+// plugins/cache/<owner>/<name>/<version>/hooks/hooks.json (resolved with
+// ${CLAUDE_PLUGIN_ROOT}); the legacy npm CLI writes ~/.claude/CLAUDE.md + a
+// SessionStart hook in settings.json. status/doctor/init read this so they stop
+// reporting the plugin as "off" and refuse to double-install.
+
+const BYPASS_MODES = new Set(['bypassPermissions', 'dontAsk']);
+
+// null = file absent; undefined = present but invalid JSON.
+function readJson(p) {
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return undefined; }
+}
+
+const pluginEnabledIn = (s) => !!(s && s.enabledPlugins && s.enabledPlugins[PLUGIN_ID]);
+
+const hookHasUltracost = (s) =>
+  Array.isArray(s?.hooks?.SessionStart) &&
+  s.hooks.SessionStart.some((h) => h.hooks?.some((hh) => typeof hh.command === 'string' && hh.command.includes('ultracost')));
+
+function pluginCache() {
+  if (!existsSync(PLUGIN_CACHE_DIR)) return { cacheDir: null, version: null, hooks: { sessionStart: false, preToolUse: false } };
+  let versions;
+  try { versions = readdirSync(PLUGIN_CACHE_DIR).filter((v) => !v.startsWith('.')); } catch { versions = []; }
+  if (!versions.length) return { cacheDir: null, version: null, hooks: { sessionStart: false, preToolUse: false } };
+  const version = versions.sort().at(-1);
+  const cacheDir = join(PLUGIN_CACHE_DIR, version);
+  const hj = readJson(join(cacheDir, 'hooks', 'hooks.json'));
+  return {
+    cacheDir,
+    version,
+    hooks: { sessionStart: !!hj?.hooks?.SessionStart, preToolUse: !!hj?.hooks?.PreToolUse }
+  };
+}
+
+export function detectDelivery(env = process.env) {
+  const settings = readJson(SETTINGS);
+  const local = readJson(SETTINGS_LOCAL);
+
+  const enabledIn = [];
+  if (pluginEnabledIn(settings)) enabledIn.push('settings.json');
+  if (pluginEnabledIn(local)) enabledIn.push('settings.local.json');
+
+  const cache = pluginCache();
+  const plugin = {
+    enabled: enabledIn.length > 0,
+    enabledIn,
+    cacheDir: cache.cacheDir,
+    version: cache.version,
+    hooks: cache.hooks,
+    // Require BOTH enablement and the cached hooks — a stale cache after /plugin
+    // uninstall must not read as active.
+    ok: enabledIn.length > 0 && cache.hooks.sessionStart && cache.hooks.preToolUse
+  };
+
+  const rules = existsSync(CLAUDE_MD) && readFileSync(CLAUDE_MD, 'utf8').includes(MARKER_START);
+  const settingsHook = hookHasUltracost(settings) || hookHasUltracost(local);
+  const cli = {
+    rules,
+    hook: existsSync(HOOK_PATH),
+    settingsHook,
+    policy: existsSync(POLICY_PATH),
+    ok: rules && settingsHook
+  };
+
+  const perm = { ...(settings?.permissions || {}), ...(local?.permissions || {}) };
+  const permissionMode = perm.defaultMode;
+  const skipDangerous = !!(
+    perm.skipDangerousModePermissionPrompt ??
+    settings?.skipDangerousModePermissionPrompt ??
+    local?.skipDangerousModePermissionPrompt
+  );
+
+  const verdict = plugin.ok && cli.ok ? 'both' : plugin.ok ? 'plugin' : cli.ok ? 'cli' : 'none';
+
+  return {
+    verdict,
+    plugin,
+    cli,
+    permissionMode,
+    skipDangerous,
+    bypass: BYPASS_MODES.has(permissionMode) || skipDangerous,
+    gateEnv: env.ULTRACOST_GATE,
+    settingsInvalid: settings === undefined || local === undefined
+  };
+}

package/src/estimate.js

@@ -99,3 +99,21 @@ export function estimateText(text, policy, opts = {}) {
 export function estimateFile(file, policy, opts) {
   return estimateText(readFileSync(file, 'utf8'), policy, opts);
 }
+
+// Total cost of the same workflow under three policies, for `ultracost simulate`:
+// all-opus (the unguided ultracode default), all-sonnet (aggressive cost-first), and
+// tiered (the per-stage pins as written).
+export function scenarioTotals(text, policy) {
+  const stages = stageList(text);
+  const assumedFanout = policy.estimation.assumedFanout;
+  const weight = (s) => (s.fanout ? assumedFanout : 1);
+  const sum = (model, effort) => stages.reduce((n, s) => n + stageCost(model, effort, policy) * weight(s), 0);
+  const def = policy.tiers[policy.default] || { model: 'opus', effort: 'xhigh' };
+  const son = policy.tiers.sonnet || { model: 'sonnet', effort: 'high' };
+  return {
+    stages: stages.length,
+    allOpus: round(sum(def.model, def.effort)),
+    allSonnet: round(sum(son.model, son.effort || 'high')),
+    tiered: round(estimateText(text, policy).cost.tiered)
+  };
+}