claude-finops 0.13.0 → 0.15.0

package/finops/etl.py

@@ -14,9 +14,10 @@ import sys
 from datetime import datetime, timezone
 
 from .classify import classify
+from . import localtime
 from .pricing import Pricing
 
-from .paths import ROOT, DB_PATH, DESKTOP_SESSIONS
+from .paths import ROOT, DB_PATH, DESKTOP_SESSIONS, SETTINGS_PATH, LOCAL_SETTINGS_PATH
 DEFAULT_SOURCE = os.path.expanduser("~/.claude/projects")
 
 SCHEMA_VERSION = 3   # 3: cross-session request_id dedup (resumed sessions copy history)
@@ -202,9 +203,23 @@ def _slug_to_name(slug):
     return os.path.basename(p.rstrip("/")) or slug
 
 
+def keep_deleted_history():
+    """history.keep_deleted_transcripts (default on), local settings winning over shared."""
+    val = True
+    for path in (SETTINGS_PATH, LOCAL_SETTINGS_PATH):
+        try:
+            with open(path) as fh:
+                h = (json.load(fh) or {}).get("history") or {}
+            if isinstance(h.get("keep_deleted_transcripts"), bool):
+                val = h["keep_deleted_transcripts"]
+        except (OSError, ValueError, AttributeError):
+            pass
+    return val
+
+
 class Loader:
     def __init__(self, db_path=DB_PATH, source=DEFAULT_SOURCE, pricing=None, other_agents=True,
-                 desktop_roots=None):
+                 desktop_roots=None, keep_from=None):
         self.other_agents = other_agents
         # An explicit source means "load exactly this"; only the default also picks up
         # the desktop app's Cowork sessions (same JSONL format, different config dir).
@@ -220,11 +235,30 @@ class Loader:
         self.pending_results = {}
         self.group = None
         self.seen_request_ids = set()   # dedup request_id across sessions (resumed sessions)
+        # The warehouse this build replaces: sessions whose transcript has since been
+        # deleted are carried over from it, so history outlives Claude Code's cleanup.
+        self.keep_from = keep_from
 
     # ---------- infrastructure ----------
     def build(self, verbose=True):
+        prev = self.keep_from
+        moved = None
         if os.path.exists(self.db_path):
-            os.remove(self.db_path)
+            if prev is None and keep_deleted_history():
+                moved = prev = self.db_path + ".prev"
+                # fold the write-ahead log into the file first: moving the file without
+                # its -wal leaves a database SQLite can no longer read
+                try:
+                    c = sqlite3.connect(self.db_path)
+                    c.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+                    c.close()
+                except sqlite3.Error:
+                    pass
+                for suffix in ("", "-wal", "-shm"):
+                    if os.path.exists(self.db_path + suffix):
+                        os.replace(self.db_path + suffix, moved + suffix)
+            else:
+                os.remove(self.db_path)
         for suffix in ("-wal", "-shm"):
             p = self.db_path + suffix
             if os.path.exists(p):
@@ -237,7 +271,16 @@ class Loader:
             for n in names:
                 if n.endswith(".jsonl"):
                     files.append(os.path.join(dirpath, n))
-        files.sort()
+
+        def created(fp):
+            # A resumed session copies earlier responses into a new, later file; reading
+            # files oldest-created first credits each response to the session that made it.
+            try:
+                st = os.stat(fp)
+                return (getattr(st, "st_birthtime", None) or st.st_mtime, fp)
+            except OSError:
+                return (float("inf"), fp)
+        files.sort(key=created)
         marker = os.sep + os.path.join(".claude", "projects") + os.sep
         desktop = sorted(os.path.join(d, n) for root in self.desktop_roots
                          for d, _, names in os.walk(root) for n in names
@@ -257,16 +300,34 @@ class Loader:
             if verbose and counts:
                 print("  other agents: " + ", ".join(f"{k} {v:,} requests" for k, v in counts.items()),
                       file=sys.stderr)
+        carried = 0
+        if prev and keep_deleted_history() and os.path.exists(prev):
+            self.db.commit()              # the fresh read is safe whatever happens next
+            try:
+                carried = self.carry_over(prev)
+            except Exception as exc:     # an old or damaged warehouse must not stop a build
+                print(f"  ! kept no deleted history: {exc}", file=sys.stderr)
+                self.db.rollback()
+            if verbose and carried:
+                print(f"  kept {carried} sessions whose transcripts were deleted", file=sys.stderr)
+        if moved:
+            for suffix in ("", "-wal", "-shm"):
+                if os.path.exists(moved + suffix):
+                    os.remove(moved + suffix)
         self.rollup()
         self.db.execute(
             "INSERT INTO meta VALUES (?,?)",
             ("built_at", datetime.now(timezone.utc).isoformat()),
         )
+        self.db.execute("INSERT INTO meta VALUES (?,?)", ("kept_deleted_sessions", str(carried)))
         for k, v in (
             ("source_dir", self.source),
             ("transcript_files", str(len(files))),
             ("desktop_transcript_files", str(len(desktop))),
             ("pricing_updated", str(self.pricing.updated)),
+            # day/hour columns are local calendar days (finops/localtime.py); older
+            # warehouses cut them at UTC and the readers fall back accordingly
+            ("day_basis", "local"),
             ("pricing_source", str(self.pricing.source)),
             ("cost_basis", "estimated"),
             ("schema_version", str(SCHEMA_VERSION)),
@@ -452,7 +513,7 @@ class Loader:
             "INSERT INTO prompts (uuid, session_id, project_id, ts, day, text, char_len,"
             " word_len, category, category_confidence, category_evidence, source, norm_hash)"
             " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
-            (r.get("uuid"), session_id, pid, ts, (ts or "")[:10], text, len(text),
+            (r.get("uuid"), session_id, pid, ts, localtime.day(ts), text, len(text),
              len(text.split()), cat, conf, json.dumps(ev), src, norm_hash))
         return cur.lastrowid
 
@@ -520,7 +581,7 @@ class Loader:
             " tool_call_count, is_sidechain, agent_id, agent_type, agent_desc)"
             " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
             (first.get("uuid"), request_id, session_id, pid,
-             prompt_id, ts, (ts or "")[:10], (t.hour if t else None), model,
+             prompt_id, ts, localtime.day(ts), localtime.hour(ts), model,
              1 if self.pricing.is_known(model) else 0, first.get("effort"),
              u.get("service_tier"), msg.get("stop_reason"), inp, out, think, cr,
              c5, c1, cw, billable, context, cost, cost_no_cache,
@@ -530,7 +591,7 @@ class Loader:
                else (None, "inline" if first.get("isSidechain") else None, None))))
         rpk = cur.lastrowid
 
-        day = (ts or "")[:10]
+        day = localtime.day(ts)
         for c in tools:
             name = c.get("name")
             args = c.get("input") or {}
@@ -570,6 +631,109 @@ class Loader:
                     (session_id, pid, prompt_id, args["file_path"], FILE_TOOLS[name], ts))
 
     # ---------- aggregates ----------
+    def carry_over(self, prev):
+        """Copy sessions whose transcript no longer exists from the previous warehouse.
+
+        Claude Code deletes old transcripts (cleanupPeriodDays), and a rebuild reads only
+        what is on disk, so without this every sync would erase that history. Rows are
+        re-derived where the rules may have changed since: cost from the current price
+        table, day and hour in local time, and the prompt category. A session whose
+        file still exists is never carried (the fresh read wins), and a request already
+        loaded from another file is not copied twice.
+        """
+        d = self.db
+        d.execute("ATTACH DATABASE ? AS old", (prev,))
+        try:
+            d.row_factory = sqlite3.Row
+            cols = lambda db, t: [r[1] for r in d.execute(f"PRAGMA {db}.table_info({t})")]
+            common = lambda t: [c for c in cols("main", t) if c in set(cols("old", t)) and c != "id"]
+            gone = [r for r in d.execute(
+                "SELECT * FROM old.sessions WHERE id NOT IN (SELECT id FROM main.sessions)")
+                if r["source_file"] and not os.path.exists(r["source_file"])]
+            if not gone:
+                return 0
+            sids = [r["id"] for r in gone]
+            ph = ",".join("?" * len(sids))
+
+            proj = {}
+            for r in d.execute(f"SELECT * FROM old.projects WHERE id IN "
+                               f"(SELECT project_id FROM old.sessions WHERE id IN ({ph}))", sids):
+                hit = d.execute("SELECT id FROM main.projects WHERE slug=?", (r["slug"],)).fetchone()
+                if hit:
+                    proj[r["id"]] = hit[0]
+                else:
+                    c = common("projects")
+                    cur = d.execute(f"INSERT INTO main.projects ({','.join(c)}) VALUES ({','.join('?' * len(c))})",
+                                    [r[k] for k in c])
+                    proj[r["id"]] = cur.lastrowid
+
+            c = common("sessions") + ["id"]
+            for r in gone:
+                v = {k: r[k] for k in c}
+                v["project_id"] = proj.get(r["project_id"], r["project_id"])
+                d.execute(f"INSERT INTO main.sessions ({','.join(c)}) VALUES ({','.join('?' * len(c))})",
+                          [v[k] for k in c])
+
+            pmap = {}
+            c = common("prompts")
+            for r in d.execute(f"SELECT * FROM old.prompts WHERE session_id IN ({ph})", sids).fetchall():
+                v = {k: r[k] for k in c}
+                v["project_id"] = proj.get(r["project_id"], r["project_id"])
+                v["day"] = localtime.day(r["ts"])
+                if r["text"]:
+                    v["category"], v["category_confidence"], ev = classify(r["text"])
+                    v["category_evidence"] = json.dumps(ev)
+                cur = d.execute(f"INSERT INTO main.prompts ({','.join(c)}) VALUES ({','.join('?' * len(c))})",
+                                [v[k] for k in c])
+                pmap[r["id"]] = cur.lastrowid
+
+            rmap = {}
+            c = common("requests")
+            for r in d.execute(f"SELECT * FROM old.requests WHERE session_id IN ({ph})", sids).fetchall():
+                rid = r["request_id"]
+                if rid and (rid in self.seen_request_ids or d.execute(
+                        "SELECT 1 FROM main.requests WHERE request_id=?", (rid,)).fetchone()):
+                    continue
+                v = {k: r[k] for k in c}
+                v["project_id"] = proj.get(r["project_id"], r["project_id"])
+                v["prompt_id"] = pmap.get(r["prompt_id"])
+                v["day"], v["hour"] = localtime.day(r["ts"]), localtime.hour(r["ts"])
+                priced = r["priced_as"] or r["model"]
+                cost = self.pricing.estimate(priced, r["input_tokens"] or 0, r["output_tokens"] or 0,
+                                             r["cache_read_tokens"] or 0, r["cache_write_5m"] or 0,
+                                             r["cache_write_1h"] or 0)
+                no_cache, with_cache = self.pricing.uncached_baseline(
+                    priced, r["cache_read_tokens"] or 0, r["cache_write_5m"] or 0, r["cache_write_1h"] or 0)
+                v["est_cost_usd"], v["est_cost_no_cache_usd"] = cost, cost - with_cache + no_cache
+                v["model_known"] = 1 if self.pricing.is_known(r["model"]) else 0
+                cur = d.execute(f"INSERT INTO main.requests ({','.join(c)}) VALUES ({','.join('?' * len(c))})",
+                                [v[k] for k in c])
+                rmap[r["id"]] = cur.lastrowid
+                if rid:
+                    self.seen_request_ids.add(rid)
+
+            c = common("tool_calls")
+            for r in d.execute(f"SELECT * FROM old.tool_calls WHERE session_id IN ({ph})", sids).fetchall():
+                if r["request_pk"] not in rmap:
+                    continue
+                v = {k: r[k] for k in c}
+                v.update(request_pk=rmap[r["request_pk"]], prompt_id=pmap.get(r["prompt_id"]),
+                         project_id=proj.get(r["project_id"], r["project_id"]), day=localtime.day(r["ts"]))
+                d.execute(f"INSERT INTO main.tool_calls ({','.join(c)}) VALUES ({','.join('?' * len(c))})",
+                          [v[k] for k in c])
+
+            c = common("files_touched")
+            for r in d.execute(f"SELECT * FROM old.files_touched WHERE session_id IN ({ph})", sids).fetchall():
+                v = {k: r[k] for k in c}
+                v.update(prompt_id=pmap.get(r["prompt_id"]), project_id=proj.get(r["project_id"], r["project_id"]))
+                d.execute(f"INSERT INTO main.files_touched ({','.join(c)}) VALUES ({','.join('?' * len(c))})",
+                          [v[k] for k in c])
+            d.commit()
+            return len(gone)
+        finally:
+            d.row_factory = None
+            d.execute("DETACH DATABASE old")
+
     def rollup(self):
         d = self.db
         d.execute("""

package/finops/guard.py

@@ -0,0 +1,412 @@
+"""Session guard: a PreToolUse hook that keeps a human in the loop on token-heavy sessions.
+
+  claude-finops --guard            invoked by Claude Code before every tool call
+  claude-finops --install-guard    wire it into ~/.claude/settings.json (see integrate.py)
+
+It counts the session's billable tokens (input + output + cache read + cache
+write, the same figure as the dashboard's Tokens column) straight from the
+transcript, reading only what was appended since the last call. Below the
+budget it warns once at each configured percentage; at the budget it asks the
+user to approve the next tool call, then again every step_pct (or never, in
+"once" mode).
+
+A hook cannot end a session, and this one never blocks on its own failure:
+anything unexpected means exit 0 with no output, so Claude Code carries on as
+if the guard were not installed.
+"""
+import glob
+import json
+import os
+import re
+import sys
+import time
+
+from .paths import DATA_DIR, SETTINGS_PATH, LOCAL_SETTINGS_PATH
+
+try:
+    import fcntl
+except ImportError:          # Windows: no advisory locks, concurrent calls are rare there
+    fcntl = None
+
+STATE_DIR = os.path.join(DATA_DIR, "guard")
+MAX_READ = 64 * 1024 * 1024      # new bytes read per call; the rest waits for the next call
+STALE_S = 30 * 86400
+SWEEP_S = 3600
+SESSION_KEEP_S = 30 * 86400          # a per-session limit is forgotten after this long
+SAFE_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+REJECTED = ("User rejected tool use", "The user doesn't want to proceed with this tool use")
+
+
+# ---------------------------------------------------------------- settings ----
+
+def _num(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def validate_guard(g, default):
+    """Clean a guard block. Returns (cleaned, [bad paths]); bad leaves use the default."""
+    default = default or {}
+    if not isinstance(g, dict):
+        return json.loads(json.dumps(default)), (["guard"] if g is not None else [])
+    out, bad = dict(default), []
+    for k, v in g.items():
+        if k.startswith("_"):
+            out[k] = v
+        elif k == "session_tokens":
+            if v is None or (_num(v) and v > 0):
+                out[k] = v
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "warn_pct":
+            if isinstance(v, list) and all(_num(x) and 0 < x < 100 for x in v):
+                out[k] = sorted(set(v))
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "after_approval":
+            if v in ("step", "once"):
+                out[k] = v
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "step_pct":
+            if _num(v) and 1 <= v <= 1000:
+                out[k] = v
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "sessions":
+            if not isinstance(v, dict):
+                bad.append(f"guard.{k}")
+                continue
+            sessions = {}
+            for sid, o in v.items():
+                keep = {"set_at": o["set_at"]} if isinstance(o, dict) and isinstance(o.get("set_at"), str) else {}
+                if not SAFE_ID.match(str(sid)):
+                    bad.append(f"guard.sessions.{sid}")
+                elif isinstance(o, dict) and o.get("off") is True:
+                    sessions[sid] = dict(keep, off=True)
+                elif isinstance(o, dict) and _num(o.get("session_tokens")) and o["session_tokens"] > 0:
+                    sessions[sid] = dict(keep, session_tokens=o["session_tokens"])
+                else:
+                    bad.append(f"guard.sessions.{sid}")
+            out[k] = sessions
+        elif k == "projects":
+            if not isinstance(v, dict):
+                bad.append(f"guard.{k}")
+                continue
+            projects = {}
+            for path, o in v.items():
+                if isinstance(o, dict) and o.get("off") is True:
+                    projects[path] = {"off": True}
+                elif isinstance(o, dict) and _num(o.get("session_tokens")) and o["session_tokens"] > 0:
+                    projects[path] = {"session_tokens": o["session_tokens"]}
+                else:
+                    bad.append(f"guard.projects.{path}")
+            out[k] = projects
+        else:
+            out[k] = v
+    return out, bad
+
+
+def load_guard_settings():
+    """The guard block only: shipped default + settings.local.json, validated.
+
+    Deliberately not analytics.load_settings(): that also detects the account
+    from ~/.claude.json, which the hook has no use for on every tool call.
+    """
+    with open(SETTINGS_PATH) as fh:
+        default = json.load(fh).get("guard") or {}
+    local = {}
+    try:
+        with open(LOCAL_SETTINGS_PATH) as fh:
+            local = json.load(fh).get("guard") or {}
+    except (OSError, ValueError, AttributeError):
+        pass
+    merged = dict(default)
+    if isinstance(local, dict):
+        merged.update(local)
+    return validate_guard(merged, default)[0]
+
+
+def _norm(p):
+    return os.path.normcase(os.path.realpath(os.path.expanduser(p)))
+
+
+def prune_sessions(sessions, now=None):
+    """Drop per-session limits set more than 30 days ago (entries without a date stay)."""
+    now = now or time.time()
+    out = {}
+    for sid, o in (sessions or {}).items():
+        try:
+            age = now - time.mktime(time.strptime(o["set_at"], "%Y-%m-%dT%H:%M:%S"))
+        except (KeyError, TypeError, ValueError):
+            age = 0
+        if age <= SESSION_KEEP_S:
+            out[sid] = o
+    return out
+
+
+def has_any_budget(cfg):
+    """Is any per-session budget set: global, a project override, or one session's own?"""
+    return bool(cfg.get("session_tokens")) or any(
+        o.get("session_tokens") for sect in ("projects", "sessions")
+        for o in (cfg.get(sect) or {}).values())
+
+
+def budget_for(cfg, cwd, session_id=None):
+    """The budget that applies: this session's own limit, else the most specific
+    project override, else the global one."""
+    own = (cfg.get("sessions") or {}).get(session_id) if session_id else None
+    if own is not None:
+        return None if own.get("off") else own.get("session_tokens")
+    best, best_len = None, -1
+    if cwd:
+        here = _norm(cwd)
+        for path, o in (cfg.get("projects") or {}).items():
+            p = _norm(path)
+            if (here == p or here.startswith(p.rstrip(os.sep) + os.sep)) and len(p) > best_len:
+                best, best_len = o, len(p)
+    if best is not None:
+        return None if best.get("off") else best.get("session_tokens")
+    return cfg.get("session_tokens")
+
+
+# ---------------------------------------------------------------- counting ----
+
+def billable(u):
+    cc = u.get("cache_creation") or {}
+    cw = int(u.get("cache_creation_input_tokens") or 0) or (
+        int(cc.get("ephemeral_5m_input_tokens") or 0) + int(cc.get("ephemeral_1h_input_tokens") or 0))
+    return (int(u.get("input_tokens") or 0) + int(u.get("output_tokens") or 0)
+            + int(u.get("cache_read_input_tokens") or 0) + cw)
+
+
+def session_files(transcript_path, session_id):
+    """The transcript plus its subagents' transcripts, which the dashboard counts too."""
+    files = [transcript_path]
+    sub = os.path.join(os.path.dirname(transcript_path), session_id, "subagents")
+    files += sorted(glob.glob(os.path.join(sub, "*.jsonl")))
+    return files
+
+
+def _read_new(path, fs, budget_left, on_row):
+    """Feed complete lines appended since fs["offset"] to on_row. Returns bytes read."""
+    try:
+        size = os.path.getsize(path)
+    except OSError:
+        return 0
+    if size < fs.get("offset", 0):          # rewritten: start over
+        fs["offset"] = 0
+        fs.setdefault("requests", {}).clear()
+    if size == fs.get("offset", 0) or budget_left <= 0:
+        return 0
+    with open(path, "rb") as fh:
+        fh.seek(fs.get("offset", 0))
+        chunk = fh.read(min(size - fs.get("offset", 0), budget_left))
+    end = chunk.rfind(b"\n")
+    if end < 0:
+        return 0                               # a partial line: wait for the rest
+    for raw in chunk[:end].split(b"\n"):
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            row = json.loads(raw)
+        except ValueError:
+            continue
+        if isinstance(row, dict):
+            on_row(row)
+    fs["offset"] = fs.get("offset", 0) + end + 1
+    return end + 1
+
+
+def count_session(transcript_path, session_id, state, pending_tool=None):
+    """Update state["files"] with newly appended lines; return (total billable, tool outcome).
+
+    Each API request is counted once, from the last line carrying its usage (the
+    ETL keys requests the same way: requestId, else message.id, else uuid). The
+    outcome is "approved"/"rejected" once the result of pending_tool appears.
+    """
+    files = state.setdefault("files", {})
+    outcome = []
+    left = MAX_READ
+    for path in session_files(transcript_path, session_id):
+        fs = files.setdefault(path, {"offset": 0, "requests": {}})
+        reqs = fs.setdefault("requests", {})
+
+        def on_row(r):
+            msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+            if r.get("type") == "assistant" and isinstance(msg.get("usage"), dict):
+                key = r.get("requestId") or msg.get("id") or r.get("uuid")
+                if key:
+                    reqs[key] = billable(msg["usage"])
+            elif pending_tool and r.get("type") == "user":
+                for c in msg.get("content") or []:
+                    if isinstance(c, dict) and c.get("type") == "tool_result" \
+                            and c.get("tool_use_id") == pending_tool:
+                        text = json.dumps(c.get("content")) + json.dumps(r.get("toolUseResult"))
+                        outcome.append("rejected" if any(s in text for s in REJECTED) else "approved")
+
+        left -= _read_new(path, fs, left, on_row)
+    total = sum(sum(f.get("requests", {}).values()) for f in files.values())
+    return total, (outcome[-1] if outcome else None)
+
+
+def session_usage(transcript_path, session_id):
+    """The session's billable tokens, counted like the hook does, without saving state."""
+    state = {}
+    while True:
+        before = {p: f.get("offset", 0) for p, f in state.get("files", {}).items()}
+        total, _ = count_session(transcript_path, session_id, state)
+        after = {p: f.get("offset", 0) for p, f in state.get("files", {}).items()}
+        if after == before:                    # nothing new read: the whole session is counted
+            return total
+
+
+def find_transcript(session_id, roots):
+    """<root>/<project>/<session_id>.jsonl for a Claude Code session id, or None."""
+    if not SAFE_ID.match(str(session_id or "")):
+        return None
+    for root in roots:
+        hits = glob.glob(os.path.join(root, "*", f"{session_id}.jsonl"))
+        if hits:
+            return hits[0]
+    return None
+
+
+# ---------------------------------------------------------------- deciding ----
+
+def fmt_tokens(n):
+    for div, unit in ((1e9, "B"), (1e6, "M"), (1e3, "k")):
+        if n >= div:
+            s = f"{n / div:.1f}".rstrip("0").rstrip(".")
+            return f"{s}{unit}"
+    return str(int(n))
+
+
+def next_ask(cfg, state):
+    approved = state.get("approved_pct")
+    if approved is None:
+        return 100
+    if cfg.get("after_approval") == "once":
+        return None
+    return approved + (cfg.get("step_pct") or 25)
+
+
+def decide(total, budget, cfg, state, outcome=None, tool_use_id=None):
+    """The hook's answer for this tool call (a dict to print), or None to stay silent."""
+    if not budget:
+        return None
+    if state.get("asked_at") is not None and outcome == "approved":
+        state["approved_pct"], state["asked_at"], state["asked_tool"] = state["asked_at"], None, None
+    elif outcome == "rejected":
+        state["asked_at"], state["asked_tool"] = None, None     # declined: ask again next time
+    pct = 100.0 * total / budget
+    level = next_ask(cfg, state)
+    if level is not None and pct >= level:
+        state["asked_at"], state["asked_tool"] = level, tool_use_id
+        # the ask supersedes any warning it jumped past; don't replay them after approval
+        state["warned"] = sorted(set(state.get("warned") or [])
+                                 | {w for w in (cfg.get("warn_pct") or []) if pct >= w})
+        after = next_ask(cfg, dict(state, approved_pct=level))
+        hint = (f"Approving continues until {after:g}%." if after is not None
+                else "Approving turns the guard off for the rest of this session.")
+        return {"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason":
+                f"Session guard: this session has used {fmt_tokens(total)} tokens, "
+                f"{pct:.0f}% of its {fmt_tokens(budget)} budget. Allow this tool call? {hint}"}}
+    warned = set(state.get("warned") or [])
+    crossed = [w for w in (cfg.get("warn_pct") or []) if pct >= w and w not in warned]
+    if crossed:
+        state["warned"] = sorted(warned | set(crossed))
+        return {"systemMessage": f"Session guard: {fmt_tokens(total)} tokens, {pct:.0f}% of "
+                                 f"this session's {fmt_tokens(budget)} budget.",
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "additionalContext":
+                        f"This session has used {pct:.0f}% of its token budget. At a natural "
+                        "break, suggest the user run /compact or start a fresh session."}}
+    return None
+
+
+# ------------------------------------------------------------------- state ----
+
+def _state_path(session_id):
+    safe = "".join(ch for ch in session_id if ch.isalnum() or ch in "-_")
+    return os.path.join(STATE_DIR, f"{safe or 'unknown'}.json")
+
+
+def _load_state(path):
+    try:
+        with open(path) as fh:
+            s = json.load(fh)
+        return s if isinstance(s, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_state(path, state):
+    state["updated"] = time.strftime("%Y-%m-%dT%H:%M:%S")
+    tmp = f"{path}.{os.getpid()}.tmp"
+    with open(tmp, "w") as fh:
+        json.dump(state, fh)
+    os.replace(tmp, path)
+
+
+def _sweep():
+    """Drop state for sessions untouched for 30 days; at most once an hour."""
+    marker = os.path.join(STATE_DIR, ".swept")
+    now = time.time()
+    try:
+        if now - os.path.getmtime(marker) < SWEEP_S:
+            return
+    except OSError:
+        pass
+    for p in glob.glob(os.path.join(STATE_DIR, "*.json")) + glob.glob(os.path.join(STATE_DIR, "*.lock")):
+        try:
+            if now - os.path.getmtime(p) > STALE_S:
+                os.remove(p)
+        except OSError:
+            pass
+    with open(marker, "w"):
+        pass
+
+
+# -------------------------------------------------------------------- hook ----
+
+def run(payload, cfg=None):
+    """Decide for one PreToolUse payload. Returns the dict to print, or None."""
+    session_id = payload.get("session_id")
+    transcript = payload.get("transcript_path")
+    if not session_id or not transcript:
+        return None
+    cfg = cfg if cfg is not None else load_guard_settings()
+    budget = budget_for(cfg, payload.get("cwd"), session_id)
+    if not budget:
+        return None
+    os.makedirs(STATE_DIR, exist_ok=True)
+    path = _state_path(session_id)
+    lock = open(path + ".lock", "w")
+    try:
+        if fcntl:
+            fcntl.flock(lock, fcntl.LOCK_EX)     # parallel tool calls share one state file
+        state = _load_state(path)
+        total, outcome = count_session(transcript, session_id, state, state.get("asked_tool"))
+        out = decide(total, budget, cfg, state, outcome, payload.get("tool_use_id"))
+        _save_state(path, state)
+    finally:
+        lock.close()
+    _sweep()
+    return out
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+        out = run(payload) if isinstance(payload, dict) else None
+        if out:
+            print(json.dumps(out))
+    except Exception:
+        pass          # fail open: never stand between the user and their session
+    return 0