@kill-switch/agent-guard 0.1.5 → 0.1.7

package/README.md

@@ -115,8 +115,33 @@ scarce resource isn't dollars — it's your plan's rate-limit quota, in two roll
 - a **5-hour** window (burst protection), and
 - a **weekly** (7-day) window — the real lockout risk, "resets a couple times a month".
 
-Anthropic reports exactly where you stand on every response via `anthropic-ratelimit-unified-*`
-headers. Run Claude Code **through the proxy** and agent-guard reads them — no estimation:
+### Easiest: `agent-guard usage`
+
+Pull your **real** limits straight from Anthropic — the same data `/usage` shows — no proxy, no
+workflow change:
+
+```sh
+agent-guard usage     # → 5-hour, weekly, and per-model (Sonnet/Opus) weekly utilization + resets
+```
+
+It reads your Claude Code OAuth token from the OS credential store (macOS Keychain
+`Claude Code-credentials`, or `~/.claude/.credentials.json` on Linux — used only as a Bearer
+header, **never logged or stored**) and GETs the `/api/oauth/usage` endpoint. `status`
+auto-refreshes this (throttled to 120s). The endpoint is **undocumented**, so every call fails
+soft — if it's unavailable, agent-guard falls back to the proxy or "unknown".
+
+```
+🟢 Claude Code plan limits  ·  observed just now
+  [██░░░░░░░░░░░░░░░░░░]  5-hour limit 12% used, resets 9:19 AM
+  [███░░░░░░░░░░░░░░░░░]  weekly limit 17% used, resets Tue 7:59 PM
+  [░░░░░░░░░░░░░░░░░░░░]  weekly · Sonnet   1%
+```
+
+### Alternative: the proxy
+
+Anthropic also reports your standing on every response via `anthropic-ratelimit-unified-*`
+headers (5h + weekly only — no per-model). Run Claude Code **through the proxy** and agent-guard
+reads them in-flight:
 
 ```sh
 agent-guard proxy                                    # meters Anthropic + reads limit headers
@@ -136,18 +161,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/claude-usage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Real subscription usage from Anthropic's OAuth usage endpoint.
+ *
+ * This is the authoritative, structured source for Claude Code Pro/Max limits —
+ * the same data the `/usage` command shows — without a proxy, a screen-scrape, or
+ * a (hopeless) local estimate. It's the endpoint the polished community status-
+ * line tools settled on. One caveat: it's **undocumented**, so Anthropic could
+ * change or gate it; every call here fails soft (returns null) and the caller
+ * falls back to the proxy / "unknown".
+ *
+ * Token handling: the OAuth access token is read from the OS credential store
+ * (macOS Keychain `Claude Code-credentials`, or `~/.claude/.credentials.json` on
+ * Linux), used only as a Bearer header on the GET, and **never logged or
+ * persisted** by us.
+ */
+import { type LimitSnapshot } from "./limits.js";
+/**
+ * Best-effort read of the Claude Code OAuth access token from the OS credential
+ * store. Returns null (never throws, never logs the token) if unavailable.
+ */
+export declare function readOAuthToken(): string | null;
+interface UsageWindow {
+    utilization?: number | null;
+    resets_at?: string | null;
+}
+export interface UsageResponse {
+    five_hour?: UsageWindow | null;
+    seven_day?: UsageWindow | null;
+    seven_day_sonnet?: UsageWindow | null;
+    seven_day_opus?: UsageWindow | null;
+    extra_usage?: {
+        is_enabled?: boolean;
+        monthly_limit?: number;
+        used_credits?: number;
+    } | null;
+}
+/** GET the usage endpoint with the given token. Returns null on any failure. */
+export declare function fetchUsage(token: string, timeoutMs?: number): Promise<UsageResponse | null>;
+/** Map the OAuth usage response into a {@link LimitSnapshot}. */
+export declare function usageToSnapshot(u: UsageResponse, now: number): LimitSnapshot;
+/**
+ * Fetch real usage and persist it as the live snapshot, throttled. Returns the
+ * fresh snapshot on a successful fetch, or null if we skipped (throttled) or
+ * couldn't fetch (no token / endpoint down — caller falls back gracefully).
+ */
+export declare function refreshUsage(now: number, opts?: {
+    force?: boolean;
+    throttleMs?: number;
+}): Promise<LimitSnapshot | null>;
+export {};

package/dist/claude-usage.js

@@ -0,0 +1,131 @@
+/**
+ * Real subscription usage from Anthropic's OAuth usage endpoint.
+ *
+ * This is the authoritative, structured source for Claude Code Pro/Max limits —
+ * the same data the `/usage` command shows — without a proxy, a screen-scrape, or
+ * a (hopeless) local estimate. It's the endpoint the polished community status-
+ * line tools settled on. One caveat: it's **undocumented**, so Anthropic could
+ * change or gate it; every call here fails soft (returns null) and the caller
+ * falls back to the proxy / "unknown".
+ *
+ * Token handling: the OAuth access token is read from the OS credential store
+ * (macOS Keychain `Claude Code-credentials`, or `~/.claude/.credentials.json` on
+ * Linux), used only as a Bearer header on the GET, and **never logged or
+ * persisted** by us.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { loadLimitsState, saveLimitsState, parseReset, } from "./limits.js";
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const OAUTH_BETA = "oauth-2025-04-20";
+const DEFAULT_THROTTLE_MS = 120_000; // don't hammer the endpoint
+/**
+ * Best-effort read of the Claude Code OAuth access token from the OS credential
+ * store. Returns null (never throws, never logs the token) if unavailable.
+ */
+export function readOAuthToken() {
+    try {
+        let raw;
+        if (platform() === "darwin") {
+            raw = execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], {
+                encoding: "utf8",
+                timeout: 4000,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        else {
+            raw = readFileSync(join(homedir(), ".claude", ".credentials.json"), "utf8");
+        }
+        const j = JSON.parse(raw);
+        return j?.claudeAiOauth?.accessToken ?? j?.accessToken ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** GET the usage endpoint with the given token. Returns null on any failure. */
+export async function fetchUsage(token, timeoutMs = 8000) {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(USAGE_URL, {
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    "anthropic-beta": OAUTH_BETA,
+                    "content-type": "application/json",
+                },
+                signal: ctrl.signal,
+            });
+        }
+        finally {
+            clearTimeout(t);
+        }
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convert one endpoint window to a {@link WindowState}. The endpoint's
+ * `utilization` is an integer **percent** (0–100) — including small values like
+ * 1 (= 1%), so we always divide by 100 (NOT the header parser's ambiguous
+ * >1.5 heuristic, which would read 1 as 100%).
+ */
+function toWindow(u, now) {
+    if (!u || typeof u.utilization !== "number")
+        return null;
+    return {
+        utilization: Math.max(0, Math.min(1, u.utilization / 100)),
+        resetAt: parseReset(u.resets_at ?? null, now),
+    };
+}
+/** Map the OAuth usage response into a {@link LimitSnapshot}. */
+export function usageToSnapshot(u, now) {
+    const extras = [];
+    const addExtra = (label, w) => {
+        const s = toWindow(w, now);
+        if (s)
+            extras.push({ label, utilization: s.utilization, resetAt: s.resetAt });
+    };
+    addExtra("weekly · Sonnet", u.seven_day_sonnet);
+    addExtra("weekly · Opus", u.seven_day_opus);
+    return {
+        fiveHour: toWindow(u.five_hour, now),
+        weekly: toWindow(u.seven_day, now),
+        status: "oauth-usage",
+        observedAt: now,
+        extras: extras.length ? extras : undefined,
+    };
+}
+/**
+ * Fetch real usage and persist it as the live snapshot, throttled. Returns the
+ * fresh snapshot on a successful fetch, or null if we skipped (throttled) or
+ * couldn't fetch (no token / endpoint down — caller falls back gracefully).
+ */
+export async function refreshUsage(now, opts = {}) {
+    const throttle = opts.throttleMs ?? DEFAULT_THROTTLE_MS;
+    const state = loadLimitsState();
+    if (!opts.force && state.lastFetchAt && now - state.lastFetchAt < throttle && state.snapshot) {
+        return null; // recent enough — use the cached snapshot
+    }
+    const token = readOAuthToken();
+    if (!token)
+        return null;
+    const usage = await fetchUsage(token);
+    if (!usage) {
+        // mark the attempt so we don't retry every call when the endpoint is down
+        saveLimitsState({ ...loadLimitsState(), lastFetchAt: now });
+        return null;
+    }
+    const snapshot = usageToSnapshot(usage, now);
+    const fresh = loadLimitsState();
+    saveLimitsState({ ...fresh, subscriptionDetected: true, snapshot, lastFetchAt: now });
+    return snapshot;
+}

package/dist/cli.js

@@ -19,6 +19,7 @@ import { evaluate } from "./budget.js";
 import { fmtUSD } from "./cost.js";
 import { installHook, setBudget, setLimits, resetLedger } from "./ops.js";
 import { buildStatusReport, formatLimitsLines } from "./report.js";
+import { refreshUsage } from "./claude-usage.js";
 const program = new Command();
 program
     .name("agent-guard")
@@ -59,9 +60,15 @@ program
 // ── status ───────────────────────────────────────────────────────────────────
 program
     .command("status")
-    .description("Show current session + daily spend against the budget")
+    .description("Show current session + daily spend, and real Claude Code plan limits")
     .option("--json", "Output as JSON")
-    .action((opts) => {
+    .action(async (opts) => {
+    try {
+        await refreshUsage(Date.now()); // throttled real-limits pull; never fails status
+    }
+    catch {
+        /* offline / no token */
+    }
     const cfg = loadConfig();
     const ledger = loadLedger();
     const now = Date.now();
@@ -119,6 +126,34 @@ program
             console.log(line);
     }
 });
+// ── usage (real Claude Code plan limits) ─────────────────────────────────────
+program
+    .command("usage")
+    .description("Fetch your REAL Claude Code plan limits (5h + weekly + per-model) from Anthropic")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    let snap;
+    try {
+        snap = await refreshUsage(Date.now(), { force: true });
+    }
+    catch {
+        snap = null;
+    }
+    const report = buildStatusReport();
+    if (opts.json) {
+        console.log(JSON.stringify({ fetched: !!snap, limits: report.limits }, null, 2));
+        return;
+    }
+    if (!snap && report.limits.source !== "headers") {
+        console.log("Couldn't fetch usage — need a logged-in Claude Code (token in the macOS Keychain or ~/.claude/.credentials.json).");
+        console.log("The /api/oauth/usage endpoint is undocumented and may be unavailable.");
+        return;
+    }
+    console.log("");
+    for (const line of formatLimitsLines(report.limits))
+        console.log(line);
+    console.log("");
+});
 // ── pause / resume (escape hatch) ────────────────────────────────────────────
 program
     .command("pause")

package/dist/index.d.ts

@@ -16,8 +16,9 @@ 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 { 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 { buildStatusReport, buildLimitsReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
+export { detectPlanTier, mapRateLimitTier, tierLabel, type SubscriptionTier } from "./claude-code.js";
+export { readOAuthToken, fetchUsage, usageToSnapshot, refreshUsage, type UsageResponse } from "./claude-usage.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, type LimitSnapshot, type WindowState, type ExtraWindow, 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,9 @@ 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 { readOAuthToken, fetchUsage, usageToSnapshot, refreshUsage } from "./claude-usage.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/limits.d.ts

@@ -32,6 +32,12 @@ export interface WindowState {
     /** Raw per-window status string from Anthropic (e.g. "allowed" / "warning"), if any. */
     status?: string;
 }
+/** A labelled extra window (e.g. per-model weekly) — display-only, no pacing. */
+export interface ExtraWindow {
+    label: string;
+    utilization: number;
+    resetAt: number | null;
+}
 /** A point-in-time read of the account's subscription rate-limit standing. */
 export interface LimitSnapshot {
     fiveHour: WindowState | null;
@@ -40,6 +46,8 @@ export interface LimitSnapshot {
     status: string | null;
     /** Epoch ms when this snapshot was observed. */
     observedAt: number;
+    /** Extra windows from the OAuth usage endpoint (per-model weekly, etc.) — display only. */
+    extras?: ExtraWindow[];
 }
 /** Persisted global state (account-wide, not per-session). */
 export interface LimitsState {
@@ -51,6 +59,8 @@ export interface LimitsState {
     notified: Record<string, boolean>;
     /** Epoch ms we first logged the raw unified-* headers (write-once diagnostic). */
     headersLoggedAt?: number;
+    /** Epoch ms of the last OAuth usage-endpoint fetch (for throttling). */
+    lastFetchAt?: number;
 }
 /** Nominal window durations, used for pacing math when a reset time is unknown. */
 export declare const WINDOW_MS: Record<LimitWindow, number>;

package/dist/limits.js

@@ -42,6 +42,7 @@ export function loadLimitsState() {
                 snapshot: data.snapshot ?? null,
                 notified: data.notified ?? {},
                 headersLoggedAt: data.headersLoggedAt,
+                lastFetchAt: data.lastFetchAt,
             };
         }
     }

package/dist/report.d.ts

@@ -4,24 +4,42 @@
  *
  * 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 ExtraWindow } from "./limits.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[];
+    /** Extra display-only windows (per-model weekly) from the OAuth usage endpoint. */
+    extras: ExtraWindow[];
     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 +47,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 +61,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,54 @@ 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,
+                extras: snap.extras ?? [],
                 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: [],
+        extras: [],
         level: "ok",
+        cost,
     };
 }
 function bar(frac) {
@@ -84,30 +102,32 @@ 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.",
-            ];
+    // 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}`);
+        for (const e of limits.extras) {
+            const pct = `${Math.round(e.utilization * 100)}%`.padStart(4);
+            lines.push(`  ${bar(e.utilization)}  ${e.label} ${pct}`);
         }
-        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}`);
+        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.7",
   "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": {