@kill-switch/agent-guard 0.1.5 → 0.1.6

package/README.md

@@ -136,18 +136,24 @@ your alert channels:
 ```
 
 `status` shows it; the hook injects it into the session even when only the hook is running
-(it reads the snapshot the proxy persisted). No proxy and want a rough read? Pin your tier and
-agent-guard *estimates* from the ledger (clearly labelled, never blocks):
+(it reads the snapshot the proxy persisted).
+
+**Without the proxy, real percentages are unknowable** — Claude Code fetches them from Anthropic
+and never writes them to disk, and local cost does *not* map to Anthropic's internal rate-limit
+units (so we don't fake a "% of limit"). Instead, hook-only mode shows what's honestly knowable:
+your **auto-detected plan tier** (read from `~/.claude.json`) plus **absolute rolling cost** —
+and points you at the proxy for the real numbers. Your tier needs no flag; `--plan` only
+overrides the auto-detection.
 
 ```sh
-ks guard config --plan max5        # auto | pro | max5 | max20
+ks guard config --plan max5        # auto (detect) | pro | max5 | max20
 ```
 
-Tune the thresholds (0–1 utilization) if the defaults are too eager:
+Tune the thresholds (0–1 utilization) if the proxy's pacing is too eager:
 
 | Setting | Meaning | Default |
 |---|---|---|
-| `--plan` (`AGENT_GUARD_PLAN`) | `auto` (headers only) or a tier for estimation | `auto` |
+| `--plan` (`AGENT_GUARD_PLAN`) | `auto` (detect from ~/.claude.json) or pin a tier | `auto` |
 | `--weekly-soft` / `--weekly-danger` | weekly warn / danger utilization | 0.6 / 0.85 |
 | `--5h-soft` / `--5h-danger` | 5-hour warn / danger utilization | 0.7 / 0.9 |
 | `--burn-ratio` | pace multiplier that triggers a warning | 1.5 |

package/dist/claude-code.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read what Claude Code persists locally about the account.
+ *
+ * Claude Code stores the user's plan tier in `~/.claude.json` under
+ * `oauthAccount` — so we can auto-detect it instead of making the user pass
+ * `--plan`. Note: Claude Code does NOT persist the live `/usage` rate-limit
+ * percentages anywhere readable (they're fetched from Anthropic and rendered in
+ * the TUI only) — the proxy's `unified-*` response headers remain the single
+ * source of truth for real utilization. This module is best-effort and never
+ * throws; a missing/unreadable file just means "unknown".
+ */
+/** The subscription tiers agent-guard knows about (a subset of LimitsConfig.plan). */
+export type SubscriptionTier = "pro" | "max5" | "max20";
+/** Map a Claude Code rate-limit-tier string (e.g. "default_claude_max_20x") to our tier. */
+export declare function mapRateLimitTier(raw: string | null | undefined): SubscriptionTier | null;
+/**
+ * Best-effort read of the user's plan tier from `~/.claude.json`. Prefers the
+ * per-user tier over the org default when present. Returns null if absent.
+ */
+export declare function detectPlanTier(claudeJsonPath?: string): SubscriptionTier | null;
+/** Human label for a tier. */
+export declare function tierLabel(tier: SubscriptionTier): string;

package/dist/claude-code.js

@@ -0,0 +1,48 @@
+/**
+ * Read what Claude Code persists locally about the account.
+ *
+ * Claude Code stores the user's plan tier in `~/.claude.json` under
+ * `oauthAccount` — so we can auto-detect it instead of making the user pass
+ * `--plan`. Note: Claude Code does NOT persist the live `/usage` rate-limit
+ * percentages anywhere readable (they're fetched from Anthropic and rendered in
+ * the TUI only) — the proxy's `unified-*` response headers remain the single
+ * source of truth for real utilization. This module is best-effort and never
+ * throws; a missing/unreadable file just means "unknown".
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Map a Claude Code rate-limit-tier string (e.g. "default_claude_max_20x") to our tier. */
+export function mapRateLimitTier(raw) {
+    if (!raw)
+        return null;
+    const s = raw.toLowerCase();
+    if (/max[_-]?20x/.test(s))
+        return "max20";
+    if (/max[_-]?5x/.test(s))
+        return "max5";
+    if (s.includes("pro"))
+        return "pro";
+    // Anything else (free, team, enterprise, unknown) → no estimate-tier mapping.
+    return null;
+}
+/**
+ * Best-effort read of the user's plan tier from `~/.claude.json`. Prefers the
+ * per-user tier over the org default when present. Returns null if absent.
+ */
+export function detectPlanTier(claudeJsonPath = join(homedir(), ".claude.json")) {
+    try {
+        const j = JSON.parse(readFileSync(claudeJsonPath, "utf8"));
+        const acct = j.oauthAccount;
+        if (!acct)
+            return null;
+        return mapRateLimitTier(acct.userRateLimitTier) ?? mapRateLimitTier(acct.organizationRateLimitTier);
+    }
+    catch {
+        return null;
+    }
+}
+/** Human label for a tier. */
+export function tierLabel(tier) {
+    return tier === "max20" ? "Max 20x" : tier === "max5" ? "Max 5x" : "Pro";
+}

package/dist/index.d.ts

@@ -16,8 +16,8 @@ export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, c
 export { dispatchAlert, type AlertEvent, type AlertLevel } from "./alert.js";
 export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
+export { buildStatusReport, buildLimitsReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
+export { detectPlanTier, mapRateLimitTier, tierLabel, type SubscriptionTier } from "./claude-code.js";
 export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, type LimitSnapshot, type WindowState, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, type PacingAssessment, type PacingLevel, type PacingThresholds, } from "./pacing.js";
-export { estimateSnapshot, isEstimated, TIER_BUDGETS, type PlanTier, type TierBudget, } from "./estimate.js";
 export { installHook, setBudget, setLimits, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, type LimitsPatch, } from "./ops.js";

package/dist/index.js

@@ -16,8 +16,8 @@ export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, c
 export { dispatchAlert } from "./alert.js";
 export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport, formatLimitsLines } from "./report.js";
+export { buildStatusReport, buildLimitsReport, formatLimitsLines } from "./report.js";
+export { detectPlanTier, mapRateLimitTier, tierLabel } from "./claude-code.js";
 export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, } from "./pacing.js";
-export { estimateSnapshot, isEstimated, TIER_BUDGETS, } from "./estimate.js";
 export { installHook, setBudget, setLimits, resetLedger, } from "./ops.js";

package/dist/report.d.ts

@@ -4,24 +4,39 @@
  *
  * Two halves:
  *   - the dollar budget (session + daily-rolling), always present; and
- *   - the subscription rate-limit standing (5-hour + weekly pacing), present
- *     once we've seen Anthropic's unified headers via the proxy, or estimated
- *     when the user has pinned a plan tier. Alert-only — never blocks.
+ *   - the subscription rate-limit standing. Real 5-hour/weekly utilization is
+ *     only knowable from Anthropic's `unified-*` headers, which the proxy
+ *     captures — so when we have a fresh snapshot we show real percentages, and
+ *     otherwise we show what's honestly knowable locally: the auto-detected plan
+ *     tier plus absolute rolling cost (NOT a fabricated "% of limit" — local cost
+ *     does not map to Anthropic's internal rate-limit units). Alert-only.
  */
-import { type SessionRecord } from "./ledger.js";
+import { type GuardConfig } from "./config.js";
+import { type SessionRecord, type Ledger } from "./ledger.js";
 import { type Budget, type VerdictLevel } from "./budget.js";
 import { type PacingAssessment, type PacingLevel } from "./pacing.js";
-import type { GuardConfig } from "./config.js";
-import type { Ledger } from "./ledger.js";
+import { type SubscriptionTier } from "./claude-code.js";
 export interface LimitsReport {
-    /** Where the numbers came from. "none" = no data and no pinned plan to estimate from. */
-    source: "headers" | "estimated" | "none";
+    /** "headers" = real proxy data; "none" = no live data (show tier + cost only). */
+    source: "headers" | "none";
+    /** Configured plan ("auto" | tier). */
     plan: string;
+    /** Resolved subscription tier (from config or auto-detected from ~/.claude.json). */
+    tier: SubscriptionTier | null;
+    /** True when the tier came from ~/.claude.json rather than an explicit --plan. */
+    tierDetected: boolean;
     subscriptionDetected: boolean;
-    /** Epoch ms the snapshot was observed (headers) or computed (estimated). */
+    /** Epoch ms the headers snapshot was observed, or null. */
     observedAt: number | null;
+    /** Real per-window pacing (only when source === "headers"). */
     windows: PacingAssessment[];
     level: PacingLevel;
+    /** Absolute rolling cost (API-equivalent USD) — honest local signal, not a limit %. */
+    cost: {
+        fiveHourUSD: number;
+        dailyUSD: number;
+        weeklyUSD: number;
+    };
 }
 export interface StatusReport {
     budget: Budget;
@@ -29,12 +44,10 @@ export interface StatusReport {
     verdict: VerdictLevel;
     reasons: string[];
     paused: boolean;
-    /** Epoch ms the pause auto-expires, or null (indefinite / not paused). */
     pauseUntil: number | null;
     sessions: Array<{
         id: string;
     } & SessionRecord>;
-    /** Subscription rate-limit pacing — present whenever we have data to show. */
     limits: LimitsReport;
 }
 /**
@@ -45,8 +58,7 @@ export interface StatusReport {
 export declare function buildLimitsReport(cfg: GuardConfig, ledger: Ledger, now: number): LimitsReport;
 /**
  * Render the subscription rate-limit section as plain text lines (no color), so
- * both the `agent-guard` and `ks guard` status views stay identical. Returns an
- * empty array when there's nothing useful to show.
+ * both the `agent-guard` and `ks guard` status views stay identical.
  */
 export declare function formatLimitsLines(limits: LimitsReport, now?: number): string[];
 /** Build the current status report from the on-disk config + ledger. */

package/dist/report.js

@@ -4,18 +4,30 @@
  *
  * Two halves:
  *   - the dollar budget (session + daily-rolling), always present; and
- *   - the subscription rate-limit standing (5-hour + weekly pacing), present
- *     once we've seen Anthropic's unified headers via the proxy, or estimated
- *     when the user has pinned a plan tier. Alert-only — never blocks.
+ *   - the subscription rate-limit standing. Real 5-hour/weekly utilization is
+ *     only knowable from Anthropic's `unified-*` headers, which the proxy
+ *     captures — so when we have a fresh snapshot we show real percentages, and
+ *     otherwise we show what's honestly knowable locally: the auto-detected plan
+ *     tier plus absolute rolling cost (NOT a fabricated "% of limit" — local cost
+ *     does not map to Anthropic's internal rate-limit units). Alert-only.
  */
-import { loadConfig } from "./config.js";
-import { isPaused, pauseExpiry } from "./config.js";
+import { loadConfig, isPaused, pauseExpiry } from "./config.js";
 import { loadLedger, rollingDailyCost } from "./ledger.js";
 import { evaluate } from "./budget.js";
+import { fmtUSD } from "./cost.js";
 import { loadLimitsState, WINDOW_MS } from "./limits.js";
 import { assessSnapshot, worstLevel } from "./pacing.js";
-import { estimateSnapshot } from "./estimate.js";
+import { detectPlanTier, tierLabel } from "./claude-code.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
+/** Sum metered cost across sessions whose last activity is within `windowMs`. */
+function costInWindow(ledger, now, windowMs) {
+    let total = 0;
+    for (const s of Object.values(ledger.sessions)) {
+        if (now - s.lastAt < windowMs)
+            total += s.costUSD || 0;
+    }
+    return total;
+}
 /**
  * Compute the subscription rate-limit section. Exported so the Claude Code hook
  * can reuse its already-loaded cfg + ledger instead of paying for a second
@@ -23,48 +35,52 @@ const DAY_MS = 24 * 60 * 60 * 1000;
  */
 export function buildLimitsReport(cfg, ledger, now) {
     const state = loadLimitsState();
-    const thresholds = cfg.limits;
     const plan = cfg.limits.plan;
-    // Prefer real header data — but only while it's still usable. A snapshot older
-    // than the weekly window is too stale to trust at all; and any single window
-    // whose reset time has already passed has since rolled over (its utilization is
-    // from a prior window), so we drop it rather than present expired numbers — and
-    // a reset time in the past — as if they were live. If nothing usable remains we
-    // fall through to the estimate (or "none").
+    // Resolve the effective tier: an explicit --plan wins; otherwise auto-detect
+    // from ~/.claude.json (oauthAccount.organizationRateLimitTier).
+    let tier = plan === "pro" || plan === "max5" || plan === "max20" ? plan : null;
+    let tierDetected = false;
+    if (!tier) {
+        const detected = detectPlanTier();
+        if (detected) {
+            tier = detected;
+            tierDetected = true;
+        }
+    }
+    const cost = {
+        fiveHourUSD: costInWindow(ledger, now, WINDOW_MS["5h"]),
+        dailyUSD: costInWindow(ledger, now, DAY_MS),
+        weeklyUSD: costInWindow(ledger, now, WINDOW_MS.weekly),
+    };
+    // Real data: a fresh snapshot, with any already-reset window dropped (stale).
     const snap = state.snapshot;
     if (snap && now - snap.observedAt < WINDOW_MS.weekly) {
-        const windows = assessSnapshot(snap, thresholds, now).filter((w) => !(w.resetAt != null && w.resetAt <= now));
+        const windows = assessSnapshot(snap, cfg.limits, now).filter((w) => !(w.resetAt != null && w.resetAt <= now));
         if (windows.length) {
             return {
                 source: "headers",
                 plan,
+                tier,
+                tierDetected,
                 subscriptionDetected: state.subscriptionDetected,
                 observedAt: snap.observedAt,
                 windows,
                 level: worstLevel(windows),
+                cost,
             };
         }
     }
-    // Otherwise estimate, but only when the user pinned a tier (opt-in, fuzzy).
-    if (plan === "pro" || plan === "max5" || plan === "max20") {
-        const snap = estimateSnapshot(ledger, plan, now);
-        const windows = assessSnapshot(snap, thresholds, now);
-        return {
-            source: "estimated",
-            plan,
-            subscriptionDetected: state.subscriptionDetected,
-            observedAt: snap.observedAt,
-            windows,
-            level: worstLevel(windows),
-        };
-    }
+    // No live data — honest local signal only (tier + absolute cost, never a fake %).
     return {
         source: "none",
         plan,
+        tier,
+        tierDetected,
         subscriptionDetected: state.subscriptionDetected,
         observedAt: null,
         windows: [],
         level: "ok",
+        cost,
     };
 }
 function bar(frac) {
@@ -84,30 +100,28 @@ function ageString(observedAt, now) {
 }
 /**
  * Render the subscription rate-limit section as plain text lines (no color), so
- * both the `agent-guard` and `ks guard` status views stay identical. Returns an
- * empty array when there's nothing useful to show.
+ * both the `agent-guard` and `ks guard` status views stay identical.
  */
 export function formatLimitsLines(limits, now = Date.now()) {
-    if (limits.source === "none") {
-        // Only nudge if they haven't opted into either path.
-        if (!limits.subscriptionDetected) {
-            return [
-                "Claude Code plan limits: unknown.",
-                "  Run `ks guard proxy` and point Claude Code at it for exact 5-hour + weekly usage,",
-                "  or set your tier (`ks guard config --plan max5`) for an estimate.",
-            ];
-        }
-        return [];
-    }
-    const icon = limits.level === "danger" ? "🟥" : limits.level === "warn" ? "🟡" : "🟢";
-    const tag = limits.source === "estimated" ? " (estimated — run the proxy for exact)" : "";
-    const lines = [`${icon} Claude Code plan limits${tag}  ·  observed ${limits.observedAt ? ageString(limits.observedAt, now) : "—"}`];
-    for (const w of limits.windows) {
-        // w.message already leads with "<window> limit NN% used, …", so the bar
-        // carries the visual and the message carries the numbers + pacing.
-        lines.push(`  ${bar(w.utilization)}  ${w.message}`);
+    // Real proxy data → real percentages.
+    if (limits.source === "headers") {
+        const icon = limits.level === "danger" ? "🟥" : limits.level === "warn" ? "🟡" : "🟢";
+        const lines = [`${icon} Claude Code plan limits  ·  observed ${limits.observedAt ? ageString(limits.observedAt, now) : "—"}`];
+        for (const w of limits.windows)
+            lines.push(`  ${bar(w.utilization)}  ${w.message}`);
+        return lines;
     }
-    return lines;
+    // No live data: show what's honestly knowable — the tier and absolute cost,
+    // and steer to the proxy for the real percentages. Never a fabricated % bar.
+    const planStr = limits.tier
+        ? `Claude Code plan: ${tierLabel(limits.tier)}${limits.tierDetected ? " (detected)" : ""}`
+        : "Claude Code plan: unknown";
+    const c = limits.cost;
+    return [
+        `📊 ${planStr} — real 5-hour/weekly limit % needs the proxy`,
+        `   local rolling cost (API-equivalent, NOT a limit %): 5h ${fmtUSD(c.fiveHourUSD)} · 24h ${fmtUSD(c.dailyUSD)} · 7d ${fmtUSD(c.weeklyUSD)}`,
+        `   for exact limits: \`ks guard proxy\` → ANTHROPIC_BASE_URL=http://localhost:8787 claude`,
+    ];
 }
 /** Build the current status report from the on-disk config + ledger. */
 export function buildStatusReport(now = Date.now()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Kill Switch for coding agents — stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM bill. Native hook + token-metering proxy with per-session and daily-rolling budgets.",
   "type": "module",
   "bin": {