@kill-switch/agent-guard 0.1.1 → 0.1.2

package/README.md

@@ -107,6 +107,55 @@ AGENT_GUARD_SESSION_HARD=10 claude          # one-off $10 ceiling
 
 A cap of `0` disables that check.
 
+## Subscription limits (Claude Code Pro / Max)
+
+Dollar caps are the wrong currency for a **Pro/Max subscription**: you pay a flat fee, so the
+scarce resource isn't dollars — it's your plan's rate-limit quota, in two rolling windows:
+
+- 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:
+
+```sh
+agent-guard proxy                                    # meters Anthropic + reads limit headers
+ANTHROPIC_BASE_URL=http://localhost:8787 claude
+```
+
+Once those headers are seen, the session is in **subscription mode**: alert-only. agent-guard
+**never blocks** a flat-fee plan (you already paid; Anthropic's own limit is the real wall) —
+instead it *paces* you. For each window it computes burn-rate vs. a sustainable pace and
+projects whether you'll exhaust the window **before it resets**, then warns in-session and via
+your alert channels:
+
+```
+🟥 Claude Code plan limits  ·  observed just now
+  [████████████░░░░░░░░]  weekly limit 62% used, resets Sat 6:00 PM, burning 3.1× pace,
+                          → lockout in ~14h (5.1d before reset)
+```
+
+`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):
+
+```sh
+ks guard config --plan max5        # auto | pro | max5 | max20
+```
+
+Tune the thresholds (0–1 utilization) if the defaults are too eager:
+
+| Setting | Meaning | Default |
+|---|---|---|
+| `--plan` (`AGENT_GUARD_PLAN`) | `auto` (headers only) or a tier for estimation | `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 |
+
+> Because subscription mode is alert-only, the "don't run both hook *and* proxy" caveat below
+> doesn't bite here — running Claude Code through the proxy is exactly what feeds the limit
+> headers, and dollars no longer gate anything.
+
 ## Alerts
 
 On the first soft/hard trip per scope, agent-guard:
@@ -132,8 +181,9 @@ rates so the guard never *under*-counts. Override any model in
 ```
 agent-guard install [--global] [--command <cmd>]   wire the Claude Code hook
 agent-guard proxy   [--port 8787] [--flavor anthropic|openai] [--upstream URL]
-agent-guard status  [--json]                        spend vs budget
+agent-guard status  [--json]                        spend vs budget + plan limits
 agent-guard config  [--session-hard N ...]          view/set caps
+agent-guard config  [--plan max5 --weekly-soft 0.6 ...]   view/set plan limits
 agent-guard reset   [--all|--today|--session <id>]  clear the ledger
 agent-guard hook                                    (internal) Claude Code entrypoint
 ```

package/dist/alert.d.ts

@@ -11,17 +11,27 @@
  * delay (or crash) the agent's tool call.
  */
 import { type GuardConfig } from "./config.js";
-import type { Verdict } from "./budget.js";
+/** Spend verdicts are ok/warn/block; pacing assessments are ok/warn/danger. */
+export type AlertLevel = "ok" | "warn" | "block" | "danger";
 export interface AlertEvent {
     ts: number;
     source: "hook" | "proxy";
+    /** "spend" = dollar budget trip (default); "limit" = subscription pacing alert. */
+    kind?: "spend" | "limit";
     sessionId: string;
-    level: Verdict["level"];
+    level: AlertLevel;
     sessionUSD: number;
     dailyUSD: number;
     reasons: string[];
     action: string;
     cwd?: string;
+    /** For kind:"limit" — per-window utilization summary (0–1) for the payload. */
+    limits?: Array<{
+        window: string;
+        utilization: number;
+        resetAt: number | null;
+        level: string;
+    }>;
 }
 /** Dispatch an alert across all configured channels. Resolves once all attempts settle. */
 export declare function dispatchAlert(cfg: GuardConfig, evt: AlertEvent): Promise<void>;

package/dist/alert.js

@@ -43,6 +43,17 @@ function writeLocal(evt) {
     }
 }
 function slackText(evt) {
+    if (evt.kind === "limit") {
+        const icon = evt.level === "danger" ? "🟥" : "🟡";
+        return [
+            `${icon} *Kill Switch — Claude Code subscription pacing*`,
+            `• Status: ${evt.action}`,
+            evt.cwd ? `• Project: \`${evt.cwd}\`` : "",
+            ...evt.reasons.map((r) => `• ${r}`),
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
     const icon = evt.level === "block" ? "🛑" : "⚠️";
     const verb = evt.level === "block" ? "BLOCKED a coding agent" : "warning on a coding agent";
     return [

package/dist/cli.js

@@ -17,7 +17,8 @@ import { loadConfig, configPath, isPaused, pauseExpiry, writePause, clearPause,
 import { loadLedger, rollingDailyCost } from "./ledger.js";
 import { evaluate } from "./budget.js";
 import { fmtUSD } from "./cost.js";
-import { installHook, setBudget, resetLedger } from "./ops.js";
+import { installHook, setBudget, setLimits, resetLedger } from "./ops.js";
+import { buildStatusReport, formatLimitsLines } from "./report.js";
 const program = new Command();
 program
     .name("agent-guard")
@@ -77,6 +78,7 @@ program
             verdict: verdict.level,
             reasons: verdict.reasons,
             sessions: sessions.map(([id, s]) => ({ id, ...s })),
+            limits: buildStatusReport(now).limits,
         }, null, 2));
         return;
     }
@@ -109,6 +111,13 @@ program
         for (const r of verdict.reasons)
             console.log(`  • ${r}`);
     }
+    // Subscription rate-limit pacing (Claude Code Pro/Max).
+    const limitLines = formatLimitsLines(buildStatusReport(now).limits, now);
+    if (limitLines.length) {
+        console.log("");
+        for (const line of limitLines)
+            console.log(line);
+    }
 });
 // ── pause / resume (escape hatch) ────────────────────────────────────────────
 program
@@ -153,31 +162,53 @@ program
 // ── config ───────────────────────────────────────────────────────────────────
 program
     .command("config")
-    .description("View or set budget caps (written to ~/.kill-switch/agent-guard/config.json)")
+    .description("View or set budget caps + Claude Code plan limits (written to ~/.kill-switch/agent-guard/config.json)")
     .option("--session-soft <usd>", "Per-session soft cap (warn)")
     .option("--session-hard <usd>", "Per-session hard cap (block)")
     .option("--daily-soft <usd>", "Daily rolling soft cap (warn)")
     .option("--daily-hard <usd>", "Daily rolling hard cap (block)")
     .option("--slack-webhook <url>", "Slack incoming-webhook for breach alerts")
+    .option("--plan <tier>", "Claude Code plan: auto | pro | max5 | max20 (subscription limit awareness)")
+    .option("--weekly-soft <pct>", "Weekly limit soft threshold, 0–1 (warn)")
+    .option("--weekly-danger <pct>", "Weekly limit danger threshold, 0–1")
+    .option("--5h-soft <pct>", "5-hour limit soft threshold, 0–1 (warn)")
+    .option("--5h-danger <pct>", "5-hour limit danger threshold, 0–1")
+    .option("--burn-ratio <n>", "Burn-rate multiplier that triggers a pacing warning")
     .action((opts) => {
-    const anySet = ["sessionSoft", "sessionHard", "dailySoft", "dailyHard", "slackWebhook"]
-        .some((k) => opts[k] !== undefined);
-    if (!anySet) {
+    const budgetKeys = ["sessionSoft", "sessionHard", "dailySoft", "dailyHard", "slackWebhook"];
+    const limitKeys = ["plan", "weeklySoft", "weeklyDanger", "5hSoft", "5hDanger", "burnRatio"];
+    const anyBudget = budgetKeys.some((k) => opts[k] !== undefined);
+    const anyLimit = limitKeys.some((k) => opts[k] !== undefined);
+    if (!anyBudget && !anyLimit) {
         const cfg = loadConfig();
-        console.log(JSON.stringify({ budget: cfg.budget, slackWebhook: cfg.slackWebhook ? "(set)" : undefined }, null, 2));
+        console.log(JSON.stringify({ budget: cfg.budget, limits: cfg.limits, slackWebhook: cfg.slackWebhook ? "(set)" : undefined }, null, 2));
         console.log(`\nConfig file: ${configPath()}`);
         return;
     }
     const num = (v) => (v !== undefined ? Number(v) : undefined);
-    const budget = setBudget({
-        sessionSoftUSD: num(opts.sessionSoft),
-        sessionHardUSD: num(opts.sessionHard),
-        dailySoftUSD: num(opts.dailySoft),
-        dailyHardUSD: num(opts.dailyHard),
-        slackWebhook: opts.slackWebhook,
-    });
-    console.log(`✅ Saved → ${configPath()}`);
-    console.log(JSON.stringify(budget, null, 2));
+    if (anyBudget) {
+        const budget = setBudget({
+            sessionSoftUSD: num(opts.sessionSoft),
+            sessionHardUSD: num(opts.sessionHard),
+            dailySoftUSD: num(opts.dailySoft),
+            dailyHardUSD: num(opts.dailyHard),
+            slackWebhook: opts.slackWebhook,
+        });
+        console.log(`✅ Budget saved → ${configPath()}`);
+        console.log(JSON.stringify(budget, null, 2));
+    }
+    if (anyLimit) {
+        const limits = setLimits({
+            plan: opts.plan,
+            weeklySoftPct: num(opts.weeklySoft),
+            weeklyDangerPct: num(opts.weeklyDanger),
+            fiveHourSoftPct: num(opts["5hSoft"]),
+            fiveHourDangerPct: num(opts["5hDanger"]),
+            burnRatioWarn: num(opts.burnRatio),
+        });
+        console.log(`✅ Plan limits saved → ${configPath()}`);
+        console.log(JSON.stringify(limits, null, 2));
+    }
 });
 // ── reset ────────────────────────────────────────────────────────────────────
 program

package/dist/config.d.ts

@@ -8,8 +8,30 @@
  */
 import type { Budget } from "./budget.js";
 import type { ModelPricing } from "./pricing.js";
+/**
+ * Subscription rate-limit config. Separate from the dollar {@link Budget}
+ * because a Claude Code Pro/Max session pays a flat fee — the scarce resource is
+ * the plan's 5-hour and weekly quota, not dollars. This is alert-only: the guard
+ * never blocks on these (you already paid), it just warns before you lock out.
+ */
+export interface LimitsConfig {
+    /**
+     * Plan tier. "auto" = derive everything from observed `unified-*` headers
+     * (proxy path); a pinned tier additionally enables hook-only estimation when
+     * no fresh header snapshot exists. See estimate.ts.
+     */
+    plan: "auto" | "pro" | "max5" | "max20";
+    /** Per-window soft (warn) / danger thresholds, as 0–1 utilization fractions. */
+    fiveHourSoftPct: number;
+    fiveHourDangerPct: number;
+    weeklySoftPct: number;
+    weeklyDangerPct: number;
+    /** Burn ratio (actual/expected pace) above which we escalate on pacing alone. */
+    burnRatioWarn: number;
+}
 export interface GuardConfig {
     budget: Budget;
+    limits: LimitsConfig;
     /** Optional pricing overrides merged onto the built-in table. */
     pricingOverrides?: Record<string, ModelPricing>;
     /** Kill Switch API key (ks_live_…) for reporting kill events to Guardian. */
@@ -20,6 +42,7 @@ export interface GuardConfig {
     slackWebhook?: string;
 }
 export declare const DEFAULT_BUDGET: Budget;
+export declare const DEFAULT_LIMITS: LimitsConfig;
 /** ~/.kill-switch/agent-guard — created on demand. */
 export declare function guardDir(): string;
 export declare function ensureGuardDir(): string;
@@ -27,6 +50,8 @@ export declare const ledgerPath: () => string;
 export declare const configPath: () => string;
 export declare const pricingPath: () => string;
 export declare const eventsPath: () => string;
+/** Subscription rate-limit state (latest unified-header snapshot + dedup). */
+export declare const limitsPath: () => string;
 /**
  * Escape hatch. The hook/proxy fail OPEN while this sentinel exists, so a human
  * can always disable enforcement from outside the agent loop — even with zero

package/dist/config.js

@@ -15,6 +15,14 @@ export const DEFAULT_BUDGET = {
     dailySoftUSD: 25,
     dailyHardUSD: 100,
 };
+export const DEFAULT_LIMITS = {
+    plan: "auto",
+    fiveHourSoftPct: 0.7,
+    fiveHourDangerPct: 0.9,
+    weeklySoftPct: 0.6,
+    weeklyDangerPct: 0.85,
+    burnRatioWarn: 1.5,
+};
 /** ~/.kill-switch/agent-guard — created on demand. */
 export function guardDir() {
     return join(homedir(), ".kill-switch", "agent-guard");
@@ -28,6 +36,8 @@ export const ledgerPath = () => join(guardDir(), "ledger.json");
 export const configPath = () => join(guardDir(), "config.json");
 export const pricingPath = () => join(guardDir(), "pricing.json");
 export const eventsPath = () => join(guardDir(), "events.jsonl");
+/** Subscription rate-limit state (latest unified-header snapshot + dedup). */
+export const limitsPath = () => join(guardDir(), "limits.json");
 /**
  * Escape hatch. The hook/proxy fail OPEN while this sentinel exists, so a human
  * can always disable enforcement from outside the agent loop — even with zero
@@ -95,8 +105,20 @@ export function loadConfig() {
         dailySoftUSD: num(process.env.AGENT_GUARD_DAILY_SOFT, fileBudget.dailySoftUSD ?? DEFAULT_BUDGET.dailySoftUSD),
         dailyHardUSD: num(process.env.AGENT_GUARD_DAILY_HARD, fileBudget.dailyHardUSD ?? DEFAULT_BUDGET.dailyHardUSD),
     };
+    const fileLimits = fileCfg.limits ?? {};
+    const envPlan = process.env.AGENT_GUARD_PLAN;
+    const validPlan = (p) => p === "auto" || p === "pro" || p === "max5" || p === "max20";
+    const limits = {
+        plan: validPlan(envPlan) ? envPlan : validPlan(fileLimits.plan) ? fileLimits.plan : DEFAULT_LIMITS.plan,
+        fiveHourSoftPct: fileLimits.fiveHourSoftPct ?? DEFAULT_LIMITS.fiveHourSoftPct,
+        fiveHourDangerPct: fileLimits.fiveHourDangerPct ?? DEFAULT_LIMITS.fiveHourDangerPct,
+        weeklySoftPct: fileLimits.weeklySoftPct ?? DEFAULT_LIMITS.weeklySoftPct,
+        weeklyDangerPct: fileLimits.weeklyDangerPct ?? DEFAULT_LIMITS.weeklyDangerPct,
+        burnRatioWarn: fileLimits.burnRatioWarn ?? DEFAULT_LIMITS.burnRatioWarn,
+    };
     return {
         budget,
+        limits,
         pricingOverrides: { ...(fileCfg.pricingOverrides ?? {}), ...(filePricing ?? {}) },
         apiKey: process.env.KILL_SWITCH_API_KEY ?? fileCfg.apiKey,
         apiUrl: process.env.KILL_SWITCH_API_URL ?? fileCfg.apiUrl ?? "https://api.kill-switch.net",

package/dist/estimate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hook-only fallback estimate of subscription utilization.
+ *
+ * Ground truth for plan limits lives in the `anthropic-ratelimit-unified-*`
+ * response headers, which only the proxy sees. A user running just the Claude
+ * Code hook (the common, zero-config setup) never sees those headers — so when
+ * they've told us their plan tier, we *estimate* where they stand by summing the
+ * tokens the ledger recorded inside each rolling window and dividing by a
+ * per-tier token budget.
+ *
+ * This is deliberately approximate and always labelled as such:
+ *   - Anthropic meters opaque "prompts" / "active hours", not tokens, so the
+ *     token budgets below are calibrated rough equivalents, not contractual.
+ *   - The ledger stores a session's cumulative tokens against a single
+ *     `lastAt`, not a time series, so a long session is counted wholesale into
+ *     whichever window its last activity falls in.
+ *
+ * It exists to give hook-only users *a* signal and to nudge them toward
+ * `ks guard proxy` for exact numbers — never to block (subscription mode is
+ * alert-only). When in doubt it under-claims utilization so it won't cry wolf.
+ */
+import { type LimitSnapshot } from "./limits.js";
+import type { Ledger } from "./ledger.js";
+export type PlanTier = "pro" | "max5" | "max20";
+/**
+ * Rough per-tier token-equivalent budgets per window. Pro is the published
+ * baseline; Max 5x / 20x scale the 5-hour burst ~linearly with the multiplier,
+ * while the weekly cap scales more conservatively (Anthropic's weekly multiplier
+ * is smaller than the per-session one). Tune via config if your mileage differs.
+ */
+export interface TierBudget {
+    fiveHourTokens: number;
+    weeklyTokens: number;
+}
+export declare const TIER_BUDGETS: Record<PlanTier, TierBudget>;
+/**
+ * Build an estimated {@link LimitSnapshot} from the ledger for a known tier.
+ * Reset times are derived from the rolling window assumption (oldest in-window
+ * activity + window length is unknowable here, so we report the window end from
+ * `now` as a conservative upper bound on time remaining).
+ */
+export declare function estimateSnapshot(ledger: Ledger, tier: PlanTier, now: number, budgets?: Record<PlanTier, TierBudget>): LimitSnapshot;
+/** True when a snapshot came from {@link estimateSnapshot} rather than real headers. */
+export declare function isEstimated(snap: LimitSnapshot | null): boolean;

package/dist/estimate.js

@@ -0,0 +1,71 @@
+/**
+ * Hook-only fallback estimate of subscription utilization.
+ *
+ * Ground truth for plan limits lives in the `anthropic-ratelimit-unified-*`
+ * response headers, which only the proxy sees. A user running just the Claude
+ * Code hook (the common, zero-config setup) never sees those headers — so when
+ * they've told us their plan tier, we *estimate* where they stand by summing the
+ * tokens the ledger recorded inside each rolling window and dividing by a
+ * per-tier token budget.
+ *
+ * This is deliberately approximate and always labelled as such:
+ *   - Anthropic meters opaque "prompts" / "active hours", not tokens, so the
+ *     token budgets below are calibrated rough equivalents, not contractual.
+ *   - The ledger stores a session's cumulative tokens against a single
+ *     `lastAt`, not a time series, so a long session is counted wholesale into
+ *     whichever window its last activity falls in.
+ *
+ * It exists to give hook-only users *a* signal and to nudge them toward
+ * `ks guard proxy` for exact numbers — never to block (subscription mode is
+ * alert-only). When in doubt it under-claims utilization so it won't cry wolf.
+ */
+import { WINDOW_MS } from "./limits.js";
+export const TIER_BUDGETS = {
+    // Calibrated rough equivalents — Pro ≈ 45 prompts / 5h, modest weekly cap.
+    pro: { fiveHourTokens: 8_000_000, weeklyTokens: 120_000_000 },
+    max5: { fiveHourTokens: 40_000_000, weeklyTokens: 480_000_000 },
+    max20: { fiveHourTokens: 160_000_000, weeklyTokens: 1_400_000_000 },
+};
+const FIVE_HOUR_MS = WINDOW_MS["5h"];
+const WEEK_MS = WINDOW_MS.weekly;
+/** Sum tokens (input+output) across sessions whose last activity is within `windowMs`. */
+function tokensInWindow(ledger, now, windowMs) {
+    let total = 0;
+    for (const s of Object.values(ledger.sessions)) {
+        if (now - s.lastAt < windowMs)
+            total += (s.inputTokens || 0) + (s.outputTokens || 0);
+    }
+    return total;
+}
+/**
+ * Build an estimated {@link LimitSnapshot} from the ledger for a known tier.
+ * Reset times are derived from the rolling window assumption (oldest in-window
+ * activity + window length is unknowable here, so we report the window end from
+ * `now` as a conservative upper bound on time remaining).
+ */
+export function estimateSnapshot(ledger, tier, now, budgets = TIER_BUDGETS) {
+    const b = budgets[tier];
+    const fiveTokens = tokensInWindow(ledger, now, FIVE_HOUR_MS);
+    const weekTokens = tokensInWindow(ledger, now, WEEK_MS);
+    const clamp = (n) => Math.max(0, Math.min(1, n));
+    return {
+        fiveHour: {
+            utilization: clamp(fiveTokens / b.fiveHourTokens),
+            // Without a per-event time series we can't know the true rolling reset;
+            // report a full window from now as a conservative (latest-possible) reset.
+            resetAt: now + FIVE_HOUR_MS,
+            status: "estimated",
+        },
+        weekly: {
+            utilization: clamp(weekTokens / b.weeklyTokens),
+            resetAt: now + WEEK_MS,
+            status: "estimated",
+        },
+        status: "estimated",
+        observedAt: now,
+    };
+}
+/** True when a snapshot came from {@link estimateSnapshot} rather than real headers. */
+export function isEstimated(snap) {
+    return !!snap && snap.status === "estimated";
+}

package/dist/hook.js

@@ -24,6 +24,7 @@ import { parseTranscript } from "./transcript.js";
 import { loadLedger, saveLedger, setSessionCost, rollingDailyCost, prune, } from "./ledger.js";
 import { evaluate, warnKey } from "./budget.js";
 import { dispatchAlert } from "./alert.js";
+import { buildStatusReport } from "./report.js";
 function readStdin() {
     return new Promise((resolve) => {
         let data = "";
@@ -146,20 +147,53 @@ export async function runHook() {
             emit(blockDecision(event, reason, `🛑 Kill Switch stopped this agent — ${verdict.reasons[0] ?? "budget exceeded"}.`));
             process.exit(0);
         }
+        // Subscription rate-limit pacing — alert-only, surfaced in-session. Reads the
+        // snapshot the proxy persisted from Anthropic's headers (or a tier estimate),
+        // so even a hook-only session learns when it's about to lock out. Deduped per
+        // window+level so it doesn't repeat every tool call.
+        const limitMsg = limitNudge(rec, ledger, now);
         // Surface the warn nudge only on the first trip per scope (shouldAlert), not
         // on every subsequent tool call — otherwise the agent's context fills with
         // duplicate notices. After that, warnings stay silent until the hard cap.
         if (verdict.level === "warn" && shouldAlert) {
-            const ctx = renderWarnContext(verdict);
+            const ctx = limitMsg ? `${renderWarnContext(verdict)} ${limitMsg}` : renderWarnContext(verdict);
             emit(warnDecision(event, ctx, `⚠️ Kill Switch: ${verdict.reasons[0] ?? "approaching budget"}.`));
             process.exit(0);
         }
+        if (limitMsg) {
+            emit(warnDecision(event, `Kill Switch — Claude Code plan pacing (informational, you may continue): ${limitMsg}`, `⚠️ Kill Switch: ${limitMsg}`));
+            process.exit(0);
+        }
         process.exit(0);
     }
     catch {
         process.exit(0); // fail open on any unexpected error
     }
 }
+/**
+ * Most-urgent subscription-window nudge, fired once per window+level. Mutates the
+ * session's notified map (and persists it) so the same warning doesn't repeat on
+ * every tool call. Returns null when there's nothing to surface.
+ */
+function limitNudge(rec, ledger, now) {
+    try {
+        const limits = buildStatusReport(now).limits;
+        if (!limits.windows.length)
+            return null;
+        const urgent = limits.windows.find((w) => w.level === "danger") ?? limits.windows.find((w) => w.level === "warn");
+        if (!urgent)
+            return null;
+        const key = `limit:${urgent.window}:${urgent.level}`;
+        if (rec.notified[key])
+            return null;
+        rec.notified[key] = true;
+        saveLedger(ledger);
+        return urgent.message;
+    }
+    catch {
+        return null;
+    }
+}
 /** Absolute path to this CLI, so recovery commands work without PATH / npm-link. */
 function selfCmd() {
     try {

package/dist/index.d.ts

@@ -12,9 +12,12 @@ export { costForUsage, totalTokens, fmtUSD, type TokenUsage } from "./cost.js";
 export { evaluate, warnKey, type Budget, type Verdict, type Spend, type VerdictLevel } from "./budget.js";
 export { loadLedger, saveLedger, setSessionCost, addSessionCost, rollingDailyCost, prune, emptyLedger, type Ledger, type SessionRecord, } from "./ledger.js";
 export { parseTranscript, type TranscriptTotals } from "./transcript.js";
-export { loadConfig, DEFAULT_BUDGET, guardDir, ensureGuardDir, configPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, type GuardConfig, } from "./config.js";
-export { dispatchAlert, type AlertEvent } from "./alert.js";
+export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, configPath, limitsPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, type GuardConfig, type LimitsConfig, } from "./config.js";
+export { dispatchAlert, type AlertEvent, type AlertLevel } from "./alert.js";
 export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport, type StatusReport } from "./report.js";
-export { installHook, setBudget, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, } from "./ops.js";
+export { buildStatusReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, 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

@@ -12,9 +12,12 @@ export { costForUsage, totalTokens, fmtUSD } from "./cost.js";
 export { evaluate, warnKey } from "./budget.js";
 export { loadLedger, saveLedger, setSessionCost, addSessionCost, rollingDailyCost, prune, emptyLedger, } from "./ledger.js";
 export { parseTranscript } from "./transcript.js";
-export { loadConfig, DEFAULT_BUDGET, guardDir, ensureGuardDir, configPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, } from "./config.js";
+export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, configPath, limitsPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, } from "./config.js";
 export { dispatchAlert } from "./alert.js";
 export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport } from "./report.js";
-export { installHook, setBudget, resetLedger, } from "./ops.js";
+export { buildStatusReport, formatLimitsLines } from "./report.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, 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

@@ -0,0 +1,83 @@
+/**
+ * Subscription rate-limit awareness — the "how much of my Claude Code plan have
+ * I burned" half of the guard, complementary to the dollar ledger.
+ *
+ * Claude Code on a Pro/Max subscription is NOT billed per token — the scarce
+ * resource is the plan's rate-limit quota, measured in two rolling windows:
+ *   - a 5-hour window (burst protection), and
+ *   - a 7-day window (the real lockout risk, "resets a couple times a month").
+ *
+ * Anthropic reports exactly where you stand in both windows on every API
+ * response, via `anthropic-ratelimit-unified-*` headers. The proxy already sees
+ * every response, so it can read these and know the *real* remaining quota and
+ * the *real* reset times — no estimation, no guessing when limits reset.
+ *
+ * This module owns: parsing those headers into a {@link LimitSnapshot}, and the
+ * small global state file (`limits.json`) that persists the latest snapshot plus
+ * whether we've ever seen subscription headers (so the rest of the guard can
+ * switch into alert-only subscription mode).
+ *
+ * Header formats are owned by Anthropic, not us, and aren't fully contract-
+ * documented, so parsing is deliberately defensive: utilization is accepted as
+ * either a 0–1 fraction or a 0–100 percent; reset is accepted as an ISO 8601
+ * timestamp, an epoch (s or ms), or a relative seconds-until-reset.
+ */
+export type LimitWindow = "5h" | "weekly";
+/** State of one rolling rate-limit window. */
+export interface WindowState {
+    /** Fraction of the window consumed, 0–1. */
+    utilization: number;
+    /** Epoch ms when this window resets, or null if the header didn't say. */
+    resetAt: number | null;
+    /** Raw per-window status string from Anthropic (e.g. "allowed" / "warning"), if any. */
+    status?: string;
+}
+/** A point-in-time read of the account's subscription rate-limit standing. */
+export interface LimitSnapshot {
+    fiveHour: WindowState | null;
+    weekly: WindowState | null;
+    /** Raw overall `anthropic-ratelimit-unified-status`, if present. */
+    status: string | null;
+    /** Epoch ms when this snapshot was observed. */
+    observedAt: number;
+}
+/** Persisted global state (account-wide, not per-session). */
+export interface LimitsState {
+    version: 1;
+    /** True once we've ever observed unified subscription headers. Latches on. */
+    subscriptionDetected: boolean;
+    snapshot: LimitSnapshot | null;
+    /** Dedup flags so a given window/level/reset only alerts once. */
+    notified: Record<string, boolean>;
+}
+/** Nominal window durations, used for pacing math when a reset time is unknown. */
+export declare const WINDOW_MS: Record<LimitWindow, number>;
+export declare function emptyLimitsState(): LimitsState;
+export declare function loadLimitsState(): LimitsState;
+export declare function saveLimitsState(state: LimitsState): void;
+/** A header bag that works for both a fetch `Headers` and a plain record. */
+export interface HeaderGetter {
+    get(name: string): string | null | undefined;
+}
+/** Wrap a plain `Record<string,string>` so it satisfies {@link HeaderGetter}. */
+export declare function recordHeaders(rec: Record<string, string | string[] | undefined>): HeaderGetter;
+/**
+ * Parse a utilization header value into a 0–1 fraction.
+ * Accepts "0.62", "62", "62%". Values >1.5 are treated as percentages.
+ */
+export declare function parseUtilization(raw: string | null | undefined): number | null;
+/**
+ * Parse a reset header value into an absolute epoch-ms timestamp.
+ * Accepts ISO 8601 ("2026-06-13T18:00:00Z"), epoch seconds, epoch ms, or a
+ * relative seconds-until-reset (small numbers). `now` anchors the relative case.
+ */
+export declare function parseReset(raw: string | null | undefined, now: number): number | null;
+/**
+ * Read the `anthropic-ratelimit-unified-*` family into a {@link LimitSnapshot}.
+ * Returns null when no unified headers are present (i.e. not a subscription
+ * session, or an endpoint that doesn't emit them) — callers use that null to
+ * mean "stay in dollar mode for this response".
+ */
+export declare function parseUnifiedHeaders(h: HeaderGetter, now: number): LimitSnapshot | null;
+/** Stable dedup key for a pacing alert: re-alerts when the window resets. */
+export declare function limitNotifyKey(window: LimitWindow, level: string, resetAt: number | null): string;

package/dist/limits.js

@@ -0,0 +1,133 @@
+/**
+ * Subscription rate-limit awareness — the "how much of my Claude Code plan have
+ * I burned" half of the guard, complementary to the dollar ledger.
+ *
+ * Claude Code on a Pro/Max subscription is NOT billed per token — the scarce
+ * resource is the plan's rate-limit quota, measured in two rolling windows:
+ *   - a 5-hour window (burst protection), and
+ *   - a 7-day window (the real lockout risk, "resets a couple times a month").
+ *
+ * Anthropic reports exactly where you stand in both windows on every API
+ * response, via `anthropic-ratelimit-unified-*` headers. The proxy already sees
+ * every response, so it can read these and know the *real* remaining quota and
+ * the *real* reset times — no estimation, no guessing when limits reset.
+ *
+ * This module owns: parsing those headers into a {@link LimitSnapshot}, and the
+ * small global state file (`limits.json`) that persists the latest snapshot plus
+ * whether we've ever seen subscription headers (so the rest of the guard can
+ * switch into alert-only subscription mode).
+ *
+ * Header formats are owned by Anthropic, not us, and aren't fully contract-
+ * documented, so parsing is deliberately defensive: utilization is accepted as
+ * either a 0–1 fraction or a 0–100 percent; reset is accepted as an ISO 8601
+ * timestamp, an epoch (s or ms), or a relative seconds-until-reset.
+ */
+import { readFileSync, writeFileSync, renameSync } from "node:fs";
+import { limitsPath, ensureGuardDir } from "./config.js";
+/** Nominal window durations, used for pacing math when a reset time is unknown. */
+export const WINDOW_MS = {
+    "5h": 5 * 60 * 60 * 1000,
+    weekly: 7 * 24 * 60 * 60 * 1000,
+};
+export function emptyLimitsState() {
+    return { version: 1, subscriptionDetected: false, snapshot: null, notified: {} };
+}
+export function loadLimitsState() {
+    try {
+        const data = JSON.parse(readFileSync(limitsPath(), "utf8"));
+        if (data && data.version === 1) {
+            return {
+                version: 1,
+                subscriptionDetected: data.subscriptionDetected ?? false,
+                snapshot: data.snapshot ?? null,
+                notified: data.notified ?? {},
+            };
+        }
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return emptyLimitsState();
+}
+export function saveLimitsState(state) {
+    ensureGuardDir();
+    const path = limitsPath();
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2));
+    renameSync(tmp, path);
+}
+/** Wrap a plain `Record<string,string>` so it satisfies {@link HeaderGetter}. */
+export function recordHeaders(rec) {
+    const lower = {};
+    for (const [k, v] of Object.entries(rec)) {
+        if (v === undefined)
+            continue;
+        lower[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    return { get: (name) => lower[name.toLowerCase()] ?? null };
+}
+/**
+ * Parse a utilization header value into a 0–1 fraction.
+ * Accepts "0.62", "62", "62%". Values >1.5 are treated as percentages.
+ */
+export function parseUtilization(raw) {
+    if (raw == null)
+        return null;
+    const n = Number(String(raw).replace(/%$/, "").trim());
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    const frac = n > 1.5 ? n / 100 : n;
+    return Math.max(0, Math.min(1, frac));
+}
+/**
+ * Parse a reset header value into an absolute epoch-ms timestamp.
+ * Accepts ISO 8601 ("2026-06-13T18:00:00Z"), epoch seconds, epoch ms, or a
+ * relative seconds-until-reset (small numbers). `now` anchors the relative case.
+ */
+export function parseReset(raw, now) {
+    if (raw == null)
+        return null;
+    const s = String(raw).trim();
+    if (!s)
+        return null;
+    // Numeric: disambiguate ms / seconds / relative-seconds by magnitude.
+    if (/^\d+(\.\d+)?$/.test(s)) {
+        const n = Number(s);
+        if (!Number.isFinite(n))
+            return null;
+        if (n > 1e12)
+            return Math.round(n); // epoch ms
+        if (n > 1e9)
+            return Math.round(n * 1000); // epoch seconds
+        return Math.round(now + n * 1000); // relative seconds-until-reset
+    }
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? null : t;
+}
+function parseWindow(h, prefix, key, now) {
+    const util = parseUtilization(h.get(`${prefix}-${key === "5h" ? "5h" : "7d"}-utilization`));
+    const reset = parseReset(h.get(`${prefix}-${key === "5h" ? "5h" : "7d"}-reset`), now);
+    const status = h.get(`${prefix}-${key === "5h" ? "5h" : "7d"}-status`) || undefined;
+    if (util == null && reset == null && !status)
+        return null;
+    return { utilization: util ?? 0, resetAt: reset, status };
+}
+/**
+ * Read the `anthropic-ratelimit-unified-*` family into a {@link LimitSnapshot}.
+ * Returns null when no unified headers are present (i.e. not a subscription
+ * session, or an endpoint that doesn't emit them) — callers use that null to
+ * mean "stay in dollar mode for this response".
+ */
+export function parseUnifiedHeaders(h, now) {
+    const prefix = "anthropic-ratelimit-unified";
+    const fiveHour = parseWindow(h, prefix, "5h", now);
+    const weekly = parseWindow(h, prefix, "weekly", now);
+    const status = h.get(`${prefix}-status`) || null;
+    if (!fiveHour && !weekly && !status)
+        return null;
+    return { fiveHour, weekly, status, observedAt: now };
+}
+/** Stable dedup key for a pacing alert: re-alerts when the window resets. */
+export function limitNotifyKey(window, level, resetAt) {
+    return `${window}:${level}:${resetAt ?? 0}`;
+}

package/dist/ops.d.ts

@@ -3,6 +3,7 @@
  * subcommands, so both drive the same logic instead of duplicating it (or
  * shelling out). Pure side-effecting helpers over config + Claude Code settings.
  */
+import { type LimitsConfig } from "./config.js";
 import type { Budget } from "./budget.js";
 export interface InstallOptions {
     /** Install into ~/.claude/settings.json instead of ./.claude/settings.json */
@@ -33,6 +34,17 @@ export interface BudgetPatch {
 }
 /** Write budget/webhook overrides to the config file. Returns the saved budget. */
 export declare function setBudget(patch: BudgetPatch): Budget;
+/** Partial subscription-limits update. Merges onto the existing config file. */
+export interface LimitsPatch {
+    plan?: LimitsConfig["plan"];
+    fiveHourSoftPct?: number;
+    fiveHourDangerPct?: number;
+    weeklySoftPct?: number;
+    weeklyDangerPct?: number;
+    burnRatioWarn?: number;
+}
+/** Write subscription-limit overrides to the config file. Returns the saved limits. */
+export declare function setLimits(patch: LimitsPatch): LimitsConfig;
 /** Clear the spend ledger. Scope: all | a single session | today's sessions. */
 export declare function resetLedger(opts: {
     all?: boolean;

package/dist/ops.js

@@ -6,7 +6,7 @@
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
-import { configPath, ensureGuardDir, DEFAULT_BUDGET } from "./config.js";
+import { configPath, ensureGuardDir, DEFAULT_BUDGET, DEFAULT_LIMITS } from "./config.js";
 import { loadLedger, saveLedger, emptyLedger } from "./ledger.js";
 /**
  * Wire the agent-guard hook into Claude Code settings for PreToolUse,
@@ -73,6 +73,32 @@ export function setBudget(patch) {
     writeFileSync(configPath(), JSON.stringify(file, null, 2) + "\n");
     return budget;
 }
+/** Write subscription-limit overrides to the config file. Returns the saved limits. */
+export function setLimits(patch) {
+    let file = {};
+    try {
+        file = JSON.parse(readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        /* new */
+    }
+    const limits = { ...DEFAULT_LIMITS, ...(file.limits ?? {}) };
+    if (patch.plan && ["auto", "pro", "max5", "max20"].includes(patch.plan))
+        limits.plan = patch.plan;
+    const setPct = (k, v) => {
+        if (v !== undefined && Number.isFinite(v))
+            limits[k] = v;
+    };
+    setPct("fiveHourSoftPct", patch.fiveHourSoftPct);
+    setPct("fiveHourDangerPct", patch.fiveHourDangerPct);
+    setPct("weeklySoftPct", patch.weeklySoftPct);
+    setPct("weeklyDangerPct", patch.weeklyDangerPct);
+    setPct("burnRatioWarn", patch.burnRatioWarn);
+    file.limits = limits;
+    ensureGuardDir();
+    writeFileSync(configPath(), JSON.stringify(file, null, 2) + "\n");
+    return limits;
+}
 /** Clear the spend ledger. Scope: all | a single session | today's sessions. */
 export function resetLedger(opts) {
     if (opts.all) {

package/dist/pacing.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pacing engine — the "intelligent" half the user asked for.
+ *
+ * Blocking at "90% of weekly" is dumb: 90% on day 6 is fine, but 60% on day 2
+ * means you'll be locked out mid-week. The resource you're spending is a budget
+ * that should last until the window resets, so the real question isn't "how much
+ * is left" — it's "at this burn rate, will I run out before the window resets?".
+ *
+ * For each window we compute:
+ *   - expected utilization = fraction of the window already elapsed
+ *   - burn ratio           = actual / expected   (1.0 = perfectly on pace)
+ *   - projected exhaustion  = when utilization hits 1.0 at the current rate
+ *   - will-lock-out-before-reset = exhaustion lands before the reset
+ *
+ * The level (ok / warn / danger) is the worse of two signals: absolute
+ * utilization against soft/danger thresholds, and pacing (burning fast enough to
+ * lock out before reset). In subscription mode the guard never blocks on this —
+ * it surfaces the assessment as a warning so the human can ease off or switch to
+ * a cheaper model before Anthropic's own limit stops them mid-task.
+ */
+import { type LimitSnapshot, type LimitWindow, type WindowState } from "./limits.js";
+export interface PacingThresholds {
+    /** Per-window soft / danger utilization thresholds (0–1). */
+    fiveHourSoftPct: number;
+    fiveHourDangerPct: number;
+    weeklySoftPct: number;
+    weeklyDangerPct: number;
+    /** Burn ratio above which pacing alone escalates (with meaningful utilization). */
+    burnRatioWarn: number;
+}
+export type PacingLevel = "ok" | "warn" | "danger";
+export interface PacingAssessment {
+    window: LimitWindow;
+    /** 0–1 fraction of the window consumed. */
+    utilization: number;
+    /** Epoch ms the window resets, or null if unknown. */
+    resetAt: number | null;
+    /** actual / expected utilization; null when elapsed is unknown (no reset time). */
+    burnRatio: number | null;
+    /** Epoch ms we project utilization hits 100% at the current rate, or null. */
+    projectedExhaustionAt: number | null;
+    /** True when projected exhaustion lands before the window resets. */
+    willLockOutBeforeReset: boolean;
+    level: PacingLevel;
+    /** One-line human summary. */
+    message: string;
+}
+/** Assess a single window's pacing. `now` is epoch ms. */
+export declare function assessWindow(window: LimitWindow, state: WindowState, thresholds: PacingThresholds, now: number): PacingAssessment;
+/** Assess every window present in a snapshot. */
+export declare function assessSnapshot(snap: LimitSnapshot, thresholds: PacingThresholds, now: number): PacingAssessment[];
+/** Worst level across a set of assessments. */
+export declare function worstLevel(assessments: PacingAssessment[]): PacingLevel;

package/dist/pacing.js

@@ -0,0 +1,127 @@
+/**
+ * Pacing engine — the "intelligent" half the user asked for.
+ *
+ * Blocking at "90% of weekly" is dumb: 90% on day 6 is fine, but 60% on day 2
+ * means you'll be locked out mid-week. The resource you're spending is a budget
+ * that should last until the window resets, so the real question isn't "how much
+ * is left" — it's "at this burn rate, will I run out before the window resets?".
+ *
+ * For each window we compute:
+ *   - expected utilization = fraction of the window already elapsed
+ *   - burn ratio           = actual / expected   (1.0 = perfectly on pace)
+ *   - projected exhaustion  = when utilization hits 1.0 at the current rate
+ *   - will-lock-out-before-reset = exhaustion lands before the reset
+ *
+ * The level (ok / warn / danger) is the worse of two signals: absolute
+ * utilization against soft/danger thresholds, and pacing (burning fast enough to
+ * lock out before reset). In subscription mode the guard never blocks on this —
+ * it surfaces the assessment as a warning so the human can ease off or switch to
+ * a cheaper model before Anthropic's own limit stops them mid-task.
+ */
+import { WINDOW_MS } from "./limits.js";
+function windowLabel(w) {
+    return w === "5h" ? "5-hour" : "weekly";
+}
+function fmtClock(epochMs, now) {
+    const dt = new Date(epochMs);
+    const sameDay = new Date(now).toDateString() === dt.toDateString();
+    // Day-of-week + time reads naturally for a multi-day weekly window.
+    return sameDay
+        ? dt.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })
+        : dt.toLocaleString([], { weekday: "short", hour: "numeric", minute: "2-digit" });
+}
+function fmtDuration(ms) {
+    if (ms <= 0)
+        return "now";
+    const h = ms / (60 * 60 * 1000);
+    if (h < 1)
+        return `${Math.round(ms / 60000)}m`;
+    if (h < 24)
+        return `${h.toFixed(h < 10 ? 1 : 0)}h`;
+    return `${(h / 24).toFixed(1)}d`;
+}
+/** Assess a single window's pacing. `now` is epoch ms. */
+export function assessWindow(window, state, thresholds, now) {
+    const util = Math.max(0, Math.min(1, state.utilization));
+    const soft = window === "5h" ? thresholds.fiveHourSoftPct : thresholds.weeklySoftPct;
+    const danger = window === "5h" ? thresholds.fiveHourDangerPct : thresholds.weeklyDangerPct;
+    const duration = WINDOW_MS[window];
+    // elapsed = duration - timeUntilReset; only known when we have a reset time.
+    let elapsed = null;
+    if (state.resetAt != null) {
+        const untilReset = state.resetAt - now;
+        elapsed = Math.max(0, Math.min(duration, duration - untilReset));
+    }
+    let burnRatio = null;
+    let projectedExhaustionAt = null;
+    let willLockOut = false;
+    if (elapsed != null && elapsed > 0) {
+        const expected = elapsed / duration;
+        burnRatio = expected > 0 ? util / expected : null;
+        if (util > 0 && util < 1) {
+            const ratePerMs = util / elapsed; // utilization per ms so far
+            const msToFull = (1 - util) / ratePerMs;
+            projectedExhaustionAt = now + msToFull;
+            if (state.resetAt != null)
+                willLockOut = projectedExhaustionAt < state.resetAt;
+        }
+        else if (util >= 1) {
+            projectedExhaustionAt = now;
+            willLockOut = true;
+        }
+    }
+    // Level: worse of absolute-utilization and pacing signals. A projected lockout
+    // only escalates once you've used a meaningful slice of the window — otherwise
+    // tiny noise near a linear burn (e.g. 15% used, exhaustion landing a few hours
+    // before a reset days away) would scream danger far too early. We gate it at
+    // half the soft threshold.
+    const lockoutFloor = soft * 0.5;
+    const lockoutMatters = willLockOut && util >= lockoutFloor;
+    let level = "ok";
+    if (util >= danger || (lockoutMatters && util >= soft))
+        level = "danger";
+    else if (util >= soft ||
+        lockoutMatters ||
+        (burnRatio != null && burnRatio >= thresholds.burnRatioWarn && util >= lockoutFloor))
+        level = "warn";
+    const pct = Math.round(util * 100);
+    const label = windowLabel(window);
+    const parts = [`${label} limit ${pct}% used`];
+    if (state.resetAt != null)
+        parts.push(`resets ${fmtClock(state.resetAt, now)}`);
+    if (burnRatio != null && burnRatio >= 1.2 && level !== "ok")
+        parts.push(`burning ${burnRatio.toFixed(1)}× pace`);
+    // Only surface the lockout projection once it actually drives the level —
+    // keeps low-utilization projection noise out of the message.
+    if (lockoutMatters && projectedExhaustionAt != null && state.resetAt != null) {
+        const before = state.resetAt - projectedExhaustionAt;
+        parts.push(`→ lockout in ~${fmtDuration(projectedExhaustionAt - now)} (${fmtDuration(before)} before reset)`);
+    }
+    return {
+        window,
+        utilization: util,
+        resetAt: state.resetAt,
+        burnRatio,
+        projectedExhaustionAt,
+        willLockOutBeforeReset: willLockOut,
+        level,
+        message: parts.join(", "),
+    };
+}
+/** Assess every window present in a snapshot. */
+export function assessSnapshot(snap, thresholds, now) {
+    const out = [];
+    if (snap.fiveHour)
+        out.push(assessWindow("5h", snap.fiveHour, thresholds, now));
+    if (snap.weekly)
+        out.push(assessWindow("weekly", snap.weekly, thresholds, now));
+    return out;
+}
+/** Worst level across a set of assessments. */
+export function worstLevel(assessments) {
+    if (assessments.some((a) => a.level === "danger"))
+        return "danger";
+    if (assessments.some((a) => a.level === "warn"))
+        return "warn";
+    return "ok";
+}

package/dist/proxy.js

@@ -24,6 +24,8 @@ import { loadLedger, saveLedger, addSessionCost, rollingDailyCost, prune, } from
 import { evaluate } from "./budget.js";
 import { dispatchAlert } from "./alert.js";
 import { assertSafeEndpoint, warnIfUnexpectedHost } from "./net.js";
+import { parseUnifiedHeaders, loadLimitsState, saveLimitsState, limitNotifyKey, } from "./limits.js";
+import { assessSnapshot, worstLevel } from "./pacing.js";
 const UPSTREAMS = {
     anthropic: "https://api.anthropic.com",
     openai: "https://api.openai.com",
@@ -134,6 +136,49 @@ function meter(cfg, ledger, sessionId, parsed, now) {
     prune(ledger, now);
     saveLedger(ledger);
 }
+/**
+ * Read Anthropic's `unified-*` rate-limit headers off a response, persist the
+ * snapshot, latch subscription mode on, and fire a deduped pacing alert when a
+ * window crosses into warn/danger. Returns true if subscription headers were
+ * seen. Alert-only by design — this never blocks (a subscription session already
+ * paid a flat fee; the scarce resource is quota, and Anthropic's own limit is
+ * the real wall).
+ */
+function captureLimits(cfg, headers, sessionId, now) {
+    const snap = parseUnifiedHeaders(headers, now);
+    if (!snap)
+        return false;
+    const state = loadLimitsState();
+    state.subscriptionDetected = true;
+    state.snapshot = snap;
+    const assessments = assessSnapshot(snap, cfg.limits, now);
+    const fresh = assessments.filter((a) => {
+        if (a.level === "ok")
+            return false;
+        const key = limitNotifyKey(a.window, a.level, a.resetAt);
+        if (state.notified[key])
+            return false;
+        state.notified[key] = true;
+        return true;
+    });
+    saveLimitsState(state);
+    if (fresh.length) {
+        const level = worstLevel(fresh);
+        dispatchAlert(cfg, {
+            ts: now,
+            source: "proxy",
+            kind: "limit",
+            sessionId,
+            level: level === "danger" ? "danger" : "warn",
+            sessionUSD: 0,
+            dailyUSD: 0,
+            reasons: fresh.map((a) => a.message),
+            action: level === "danger" ? "on pace to lock out before reset" : "approaching plan limit",
+            limits: fresh.map((a) => ({ window: a.window, utilization: a.utilization, resetAt: a.resetAt, level: a.level })),
+        }).catch(() => { });
+    }
+    return true;
+}
 export function startProxy(opts) {
     const cfg = loadConfig();
     const upstreamOrigin = assertSafeEndpoint(opts.upstream, "upstream").replace(/\/$/, "");
@@ -143,11 +188,15 @@ export function startProxy(opts) {
         const sessionId = req.headers["x-agent-guard-session"] || `proxy:${todayKey(now)}`;
         // 1) Pre-flight budget check — block before spending anything.
         // Escape hatch: while a human has paused enforcement, never block (but still meter).
+        // Subscription mode is ALERT-ONLY: once we've seen Anthropic's unified
+        // rate-limit headers, the session is on a flat-fee plan where dollars are
+        // meaningless, so we never 402 it — we only pace + warn.
+        const subscriptionMode = loadLimitsState().subscriptionDetected;
         const ledger = loadLedger();
         const sessionUSD = ledger.sessions[sessionId]?.costUSD ?? 0;
         const dailyUSD = rollingDailyCost(ledger, now);
         const verdict = evaluate({ sessionUSD, dailyUSD }, cfg.budget);
-        if (verdict.level === "block" && !isPaused(now)) {
+        if (verdict.level === "block" && !isPaused(now) && !subscriptionMode) {
             if (!blockedNotified[sessionId]) {
                 blockedNotified[sessionId] = true;
                 dispatchAlert(cfg, {
@@ -190,6 +239,15 @@ export function startProxy(opts) {
             res.end(JSON.stringify({ error: "kill-switch proxy: upstream fetch failed", detail: String(err) }));
             return;
         }
+        // 2.5) Read Anthropic's subscription rate-limit headers (alert-only).
+        if (opts.flavor === "anthropic") {
+            try {
+                captureLimits(cfg, upstream.headers, sessionId, Date.now());
+            }
+            catch {
+                /* limit capture must never break the proxied response */
+            }
+        }
         // 3) Relay status + headers.
         const respHeaders = {};
         upstream.headers.forEach((v, k) => {
@@ -248,6 +306,9 @@ export function startProxy(opts) {
     server.listen(opts.port, "127.0.0.1", () => {
         process.stdout.write(`🛡  agent-guard proxy on http://localhost:${opts.port} → ${upstreamOrigin} (${opts.flavor})\n` +
             `   Caps: session hard ${fmtUSD(cfg.budget.sessionHardUSD)}, daily hard ${fmtUSD(cfg.budget.dailyHardUSD)}\n` +
+            (opts.flavor === "anthropic"
+                ? `   Subscription mode: reads Anthropic rate-limit headers → paces your Pro/Max plan (alert-only)\n`
+                : "") +
             `   Point your agent at it, e.g.:\n` +
             (opts.flavor === "anthropic"
                 ? `     ANTHROPIC_BASE_URL=http://localhost:${opts.port} claude\n`

package/dist/report.d.ts

@@ -1,9 +1,26 @@
 /**
  * Shared status report — the single computation behind `agent-guard status` and
  * `ks guard status`, so both emit an identical JSON shape and never drift.
+ *
+ * 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.
  */
 import { type SessionRecord } from "./ledger.js";
 import { type Budget, type VerdictLevel } from "./budget.js";
+import { type PacingAssessment, type PacingLevel } from "./pacing.js";
+export interface LimitsReport {
+    /** Where the numbers came from. "none" = no data and no pinned plan to estimate from. */
+    source: "headers" | "estimated" | "none";
+    plan: string;
+    subscriptionDetected: boolean;
+    /** Epoch ms the snapshot was observed (headers) or computed (estimated). */
+    observedAt: number | null;
+    windows: PacingAssessment[];
+    level: PacingLevel;
+}
 export interface StatusReport {
     budget: Budget;
     dailyUSD: number;
@@ -15,6 +32,14 @@ export interface StatusReport {
     sessions: Array<{
         id: string;
     } & SessionRecord>;
+    /** Subscription rate-limit pacing — present whenever we have data to show. */
+    limits: 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.
+ */
+export declare function formatLimitsLines(limits: LimitsReport, now?: number): string[];
 /** Build the current status report from the on-disk config + ledger. */
 export declare function buildStatusReport(now?: number): StatusReport;

package/dist/report.js

@@ -1,12 +1,101 @@
 /**
  * Shared status report — the single computation behind `agent-guard status` and
  * `ks guard status`, so both emit an identical JSON shape and never drift.
+ *
+ * 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.
  */
 import { loadConfig } from "./config.js";
 import { isPaused, pauseExpiry } from "./config.js";
 import { loadLedger, rollingDailyCost } from "./ledger.js";
 import { evaluate } from "./budget.js";
+import { loadLimitsState } from "./limits.js";
+import { assessSnapshot, worstLevel } from "./pacing.js";
+import { estimateSnapshot } from "./estimate.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
+function buildLimitsReport(cfg, ledger, now) {
+    const state = loadLimitsState();
+    const thresholds = cfg.limits;
+    const plan = cfg.limits.plan;
+    // Prefer real header data when we have it.
+    if (state.snapshot) {
+        const windows = assessSnapshot(state.snapshot, thresholds, now);
+        return {
+            source: "headers",
+            plan,
+            subscriptionDetected: state.subscriptionDetected,
+            observedAt: state.snapshot.observedAt,
+            windows,
+            level: worstLevel(windows),
+        };
+    }
+    // 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),
+        };
+    }
+    return {
+        source: "none",
+        plan,
+        subscriptionDetected: state.subscriptionDetected,
+        observedAt: null,
+        windows: [],
+        level: "ok",
+    };
+}
+function bar(frac) {
+    const pct = Math.max(0, Math.min(100, Math.round(frac * 100)));
+    const filled = Math.round(pct / 5);
+    return `[${"█".repeat(filled)}${"░".repeat(20 - filled)}]`;
+}
+function ageString(observedAt, now) {
+    const ms = now - observedAt;
+    if (ms < 60_000)
+        return "just now";
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m ago`;
+    if (ms < 86_400_000)
+        return `${Math.round(ms / 3_600_000)}h ago`;
+    return `${Math.round(ms / 86_400_000)}d ago`;
+}
+/**
+ * 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.
+ */
+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}`);
+    }
+    return lines;
+}
 /** Build the current status report from the on-disk config + ledger. */
 export function buildStatusReport(now = Date.now()) {
     const cfg = loadConfig();
@@ -26,5 +115,6 @@ export function buildStatusReport(now = Date.now()) {
         paused: isPaused(now),
         pauseUntil: pauseExpiry(),
         sessions,
+        limits: buildLimitsReport(cfg, ledger, now),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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": {
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "e2e": "tsc && node scripts/e2e-subscription.mjs"
   },
   "dependencies": {
     "commander": "^12.1.0"