opencode-token-norm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 salitaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# opencode-token-norm
+
+**Your token rules are advice. This makes them mechanical.**
+
+You wrote a token budget into `AGENTS.md`. It loads into every session. The agent
+reads it, agrees with it, and then runs 184 tool calls and 3.0M effective tokens
+on a task that should have been three sessions.
+
+That is not a prompting failure. Rules that survive are the ones that do not
+depend on the agent choosing to follow them. This plugin does not add advice —
+it **counts**, and at thresholds it staples an instruction onto tool output the
+agent is already reading.
+
+Two halves:
+
+- **`TokenNormBudget`** — counts tool calls, fires un-skippable reminders at
+  thresholds, and runs the usage audit *for* the agent so there is no step to defer.
+- **`TokenNormHandoff`** — a `handoff` tool that makes the session split a single
+  tool call instead of three manual steps.
+
+---
+
+## Install
+
+```json
+// ~/.config/opencode/opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-token-norm"]
+}
+```
+
+Restart OpenCode. Pin a version if you want stability:
+
+```json
+{ "plugin": ["opencode-token-norm@0.1.0"] }
+```
+
+Requires OpenCode with plugin support (`@opencode-ai/plugin` ≥ 1.15.12).
+The audit checkpoint additionally needs `python3` — without it, the reminder
+still fires and tells the agent to run the audit manually.
+
+---
+
+## What it actually does
+
+### 1. Task boundary detection (the one nobody has)
+
+The expensive failure is not a long task. It is a **new** task inheriting an old
+task's context and an old task's permission.
+
+Real session: 195k tokens deep, the agent had the norm in context, ran the audit,
+reported *"77x cache, bloat HIGH"* — and continued anyway. Why? A second request
+(*"now do all of them"*) was treated as a continuation of the `do everything`
+override granted for the first. Overrides are per-task. Nothing enforced that.
+
+When a new user message arrives in a session already past `BOUNDARY_AT` calls
+(default 40), the next tool call carries:
+
+```
+TOKEN NORM -- new request arrived 47 tool calls deep. This is a TASK BOUNDARY.
+A prior "do everything" / "don't ask" was scoped to the PREVIOUS task. It does not carry.
+...
+Do NOT justify continuing with "finishing here beats reloading cold". That reasoning
+is always available, feels free only because this context is already warm, and is the
+exact rationalization the norm exists to block.
+```
+
+That last line matters. Every agent talks itself past a split with *"reloading
+cold costs more than finishing here."* It is always available and almost always
+wrong — the marginal call feels free precisely because the context is warm.
+
+### 2. Cost statement at 25 calls
+
+The norm wants a cost statement **before** a big task. In practice the agent only
+learns the true size once it is underway. So this fires at the first moment the
+task is provably big and forces the statement then: remaining calls, caps in
+effect, and which part could ship now behind a handoff.
+
+### 3. Audit checkpoint every 60 calls — **already run**
+
+"Run this command and report the number" is advice, and advice at a checkpoint
+loses to the task in flight every time. One session was told to audit at call 79,
+kept working, and produced the number only when the user asked afterwards.
+
+So the plugin runs it. The command is cheap, deterministic, and opens OpenCode's
+sqlite DB **read-only**. The agent gets the result stapled to its tool output:
+
+```
+TOKEN NORM -- 60 tool calls. Audit checkpoint (ran for you):
+
+totals  : input 23k  output 15k  cache_read 891k  cache_write 87k
+effective fresh tokens: 220k   (input + 0.1·cache_read + 1.25·cache_write — the money number)
+calls   : 22   context/call min 23k med 49k max 61k
+cache   : 23x fresh tokens — bloat driver ok
+
+In your NEXT message, before continuing the task: report the effective-token
+number and the cache multiplier to the user, and say whether you are splitting.
+```
+
+No step to defer. Only a fact to report.
+
+### 4. Compaction context
+
+Compaction is the one moment the agent provably re-reads its own rules. The
+plugin injects the call count there, because *"you are 180 calls deep"* changes
+behavior and *"be frugal"* does not.
+
+### 5. The `handoff` tool
+
+The norm says split at phase boundaries. It does not happen, because splitting
+means leaving the TUI, opening a new session, and re-typing context by hand —
+three manual steps at exactly the moment the warm session feels cheapest to continue.
+
+One tool call instead:
+
+```
+handoff({
+  task:  "Fix token expiry off-by-one in auth middleware",
+  done:  "Diagnosed: TokenValidator.isExpired() at src/auth/token.ts:88 uses < not <=",
+  next:  "Change the comparison, add a boundary test at exactly expiresAt",
+  files: ["src/auth/token.ts:88", "src/auth/__tests__/token.test.ts"],
+})
+```
+
+The plugin writes the note to disk, opens a new TUI session, and pre-fills the
+prompt. You press enter.
+
+**Design decisions worth knowing:**
+
+- **Not auto-submitted by default.** An auto-submitted handoff starts burning
+  tokens on a task you may have wanted to redirect — and the beat before enter
+  is the entire point of splitting. Pass `submit: true` for unattended work.
+- **Persisted before the TUI switch.** If the switch fails, the note still exists
+  on disk. The reverse ordering loses it on exactly the failure that matters.
+- **Refused for subagents.** Plugin tools register for every agent. A subagent
+  calling `handoff` would hijack your screen mid-task. Subagent status is resolved
+  from the live agent list, so agents you add later classify correctly.
+- **Structured args, not a freeform summary.** `task`/`done`/`next`/`files`/`notes`
+  forces the agent to name real paths and real identifiers it verified — the next
+  session cannot see the scrollback.
+
+---
+
+## Safety
+
+- Never blocks a tool call, never edits args, never throws. A wrong threshold
+  guess costs a few lines of text, not a broken session.
+- The audit opens `~/.local/share/opencode/opencode.db` **read-only** and never writes.
+- No network calls. No telemetry. Nothing leaves your machine.
+- Handoff notes are written to `~/.local/share/opencode/handoff/`.
+
+---
+
+## Configuration
+
+All optional, all environment variables.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `TOKEN_NORM_ANNOUNCE_AT` | `25` | Calls before the cost-statement reminder |
+| `TOKEN_NORM_AUDIT_EVERY` | `60` | Calls between audit checkpoints |
+| `TOKEN_NORM_BOUNDARY_AT` | `40` | Session size above which a new user message is a task boundary |
+| `TOKEN_NORM_CHEAP_TOOLS` | `todowrite,question,skill` | Tools that do not count toward the budget |
+| `TOKEN_NORM_HANDOFF_DIR` | `~/.local/share/opencode/handoff` | Where handoff notes are written |
+| `TOKEN_NORM_LOG` | `~/.local/share/opencode/token-norm.log` | Threshold event log |
+| `TOKEN_NORM_PYTHON` | `python3` | Interpreter for the audit script |
+| `TOKEN_NORM_AUDIT_SCRIPT` | bundled | Override the audit script path |
+| `TOKEN_NORM_SETTLE_MS` | `350` | Wait after `session_new` before pre-filling the prompt |
+| `TOKEN_NORM_BUDGET` | `1` | Set `0` to disable the budget half |
+| `TOKEN_NORM_HANDOFF` | `1` | Set `0` to disable the handoff tool |
+
+Cheap tools do not count because reads and greps are how you *avoid* waste —
+scaring the agent off them makes sessions more expensive, not less.
+
+---
+
+## Run the audit yourself
+
+```bash
+python3 node_modules/opencode-token-norm/scripts/usage-audit.py --last
+python3 node_modules/opencode-token-norm/scripts/usage-audit.py --top 5
+python3 node_modules/opencode-token-norm/scripts/usage-audit.py --top 5 --json
+```
+
+`effective fresh tokens = input + 0.1·cache_read + 1.25·cache_write` — the number
+that maps to money. Raw `cache_read` does not.
+
+---
+
+## Pairs with
+
+A rules file the reminders can point at. The plugin enforces; your `AGENTS.md`
+still supplies the specifics (read windows, smallest test target, subagent
+delegation, output caps).
+
+---
+
+## License
+
+MIT

package/dist/audit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Run the usage audit and return a compact result. Must never throw and must
+ * never hang: a checkpoint that breaks the session is worse than no checkpoint.
+ */
+export declare function runAudit(): string;

package/dist/audit.js

@@ -0,0 +1,32 @@
+import { execFileSync } from "node:child_process";
+import { AUDIT_SCRIPT, PYTHON } from "./config.js";
+const KEEP_LINE = /^(totals|effective|calls|cacheR?|cache)\b/;
+/**
+ * Run the usage audit and return a compact result. Must never throw and must
+ * never hang: a checkpoint that breaks the session is worse than no checkpoint.
+ */
+export function runAudit() {
+    try {
+        const out = execFileSync(PYTHON, [AUDIT_SCRIPT, "--last"], {
+            encoding: "utf8",
+            timeout: 20_000,
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 1024 * 1024,
+        });
+        // Keep only the lines that change a decision; the full table is noise here.
+        const keep = out
+            .split("\n")
+            .filter((l) => KEEP_LINE.test(l.trim()))
+            .join("\n");
+        return keep.trim() || out.trim().slice(0, 800);
+    }
+    catch (err) {
+        const reason = String(err instanceof Error ? err.message : err).slice(0, 160);
+        return [
+            `(usage-audit did not run: ${reason})`,
+            `It needs python3 and opencode's local db. Run it manually:`,
+            `  ${PYTHON} ${AUDIT_SCRIPT} --last`,
+        ].join("\n");
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAElD,MAAM,SAAS,GAAG,2CAA2C,CAAA;AAE7D;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE;YACzD,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,SAAS,EAAE,IAAI,GAAG,IAAI;SACvB,CAAC,CAAA;QACF,4EAA4E;QAC5E,MAAM,IAAI,GAAG,GAAG;aACb,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;aACvC,IAAI,CAAC,IAAI,CAAC,CAAA;QACb,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;QAC7E,OAAO;YACL,6BAA6B,MAAM,GAAG;YACtC,4DAA4D;YAC5D,KAAK,MAAM,IAAI,YAAY,SAAS;SACrC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+/** Norm: ">~30 tool calls" needs an up-front cost statement. Warn slightly
+ * early so the announcement can still change the plan instead of narrating it. */
+export declare const ANNOUNCE_AT: number;
+/** Norm: "once midway through long tasks". Then keep reminding, because one
+ * notice 120 calls ago is not a live constraint. */
+export declare const AUDIT_EVERY: number;
+/** A session that is already large is where a NEW user request should start a
+ * fresh session instead of inheriting the old context. Below this, the handoff
+ * costs more than it saves. */
+export declare const BOUNDARY_AT: number;
+/** Cheap reads/greps are how you AVOID waste; do not scare the agent off them. */
+export declare const CHEAP_TOOLS: Set<string>;
+export declare const HANDOFF_DIR: string;
+export declare const LOG_PATH: string;
+/** Resolved relative to the installed package, not to the user's config dir,
+ * so the bundled script is found wherever npm/bun placed the package. */
+export declare const AUDIT_SCRIPT: string;
+export declare const PYTHON: string;
+/** Opt out of one half without uninstalling the package. */
+export declare const BUDGET_ENABLED: boolean;
+export declare const HANDOFF_ENABLED: boolean;

package/dist/config.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+function num(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/** Norm: ">~30 tool calls" needs an up-front cost statement. Warn slightly
+ * early so the announcement can still change the plan instead of narrating it. */
+export const ANNOUNCE_AT = num("TOKEN_NORM_ANNOUNCE_AT", 25);
+/** Norm: "once midway through long tasks". Then keep reminding, because one
+ * notice 120 calls ago is not a live constraint. */
+export const AUDIT_EVERY = num("TOKEN_NORM_AUDIT_EVERY", 60);
+/** A session that is already large is where a NEW user request should start a
+ * fresh session instead of inheriting the old context. Below this, the handoff
+ * costs more than it saves. */
+export const BOUNDARY_AT = num("TOKEN_NORM_BOUNDARY_AT", 40);
+/** Cheap reads/greps are how you AVOID waste; do not scare the agent off them. */
+export const CHEAP_TOOLS = new Set((process.env.TOKEN_NORM_CHEAP_TOOLS ?? "todowrite,question,skill")
+    .split(",")
+    .map((t) => t.trim())
+    .filter(Boolean));
+const DATA_HOME = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+export const HANDOFF_DIR = process.env.TOKEN_NORM_HANDOFF_DIR || path.join(DATA_HOME, "opencode", "handoff");
+export const LOG_PATH = process.env.TOKEN_NORM_LOG || path.join(DATA_HOME, "opencode", "token-norm.log");
+/** Resolved relative to the installed package, not to the user's config dir,
+ * so the bundled script is found wherever npm/bun placed the package. */
+export const AUDIT_SCRIPT = process.env.TOKEN_NORM_AUDIT_SCRIPT ||
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts", "usage-audit.py");
+export const PYTHON = process.env.TOKEN_NORM_PYTHON || "python3";
+/** Opt out of one half without uninstalling the package. */
+export const BUDGET_ENABLED = process.env.TOKEN_NORM_BUDGET !== "0";
+export const HANDOFF_ENABLED = process.env.TOKEN_NORM_HANDOFF !== "0";
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,SAAS,GAAG,CAAC,IAAY,EAAE,QAAgB;IACzC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAA;IACzB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IACvC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAA;AAClE,CAAC;AAED;kFACkF;AAClF,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAA;AAE5D;oDACoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAA;AAE5D;;+BAE+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAA;AAE5D,kFAAkF;AAClF,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,GAAG,CAChC,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,0BAA0B,CAAC;KAC/D,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KACpB,MAAM,CAAC,OAAO,CAAC,CACnB,CAAA;AAED,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;AAEzF,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAA;AAE5G,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAA;AAExG;yEACyE;AACzE,MAAM,CAAC,MAAM,YAAY,GACvB,OAAO,CAAC,GAAG,CAAC,uBAAuB;IACnC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAA;AAE5F,MAAM,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,SAAS,CAAA;AAEhE,4DAA4D;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG,CAAA;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,GAAG,CAAA"}

package/dist/handoff.d.ts

@@ -0,0 +1,2 @@
+import { type Plugin } from "@opencode-ai/plugin";
+export declare const HandoffPlugin: Plugin;

package/dist/handoff.js

@@ -0,0 +1,150 @@
+// Session handoff ("new session per task with a 3-line handoff").
+//
+// The norm says split at phase boundaries. In practice the split does not
+// happen, because splitting means the user leaving the TUI, opening a new
+// session, and re-typing context by hand -- three manual steps at exactly the
+// moment the warm session feels cheapest to continue. So the rule loses to
+// friction every time.
+//
+// This makes the split one tool call. The agent writes the handoff, the plugin
+// persists it to disk, opens a NEW TUI session, and pre-fills that session's
+// prompt with the handoff text. The user lands in a cold session with the
+// context already typed, and presses enter.
+//
+// The prompt is pre-filled but NOT submitted by default. An auto-submitted
+// handoff would start burning tokens on a task the user may have wanted to
+// redirect, and the whole point of the split is to give them that beat. Pass
+// submit: true when the continuation is genuinely unattended.
+import { tool } from "@opencode-ai/plugin";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { HANDOFF_DIR } from "./config.js";
+import { log } from "./log.js";
+// The TUI processes /tui/execute-command asynchronously: the request returns
+// once the command is dispatched, not once the new session is mounted.
+// Appending the prompt too early lands the text in the OLD session's editor,
+// which is worse than not splitting at all -- the user sees nothing and the
+// handoff is lost.
+const SWITCH_SETTLE_MS = Number.parseInt(process.env.TOKEN_NORM_SETTLE_MS ?? "", 10) || 350;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Plugin tools register for EVERY agent, subagents included. A subagent calling
+// handoff would open a new TUI session in the middle of the parent's task --
+// hijacking the user's screen for work they did not ask to split. Only a
+// primary agent owns the session, so only a primary agent may end it.
+//
+// Resolved from the live agent list instead of a hardcoded name list, so agents
+// the user adds later are classified correctly without touching this file.
+async function isSubagent(client, agentName) {
+    if (!agentName)
+        return false;
+    try {
+        const res = await client.app.agents();
+        const agents = res?.data ?? res;
+        const found = Array.isArray(agents) ? agents.find((a) => a.name === agentName) : undefined;
+        return found?.mode === "subagent";
+    }
+    catch {
+        // If the lookup fails, allow. A false block would strand the primary agent
+        // with no way to split, which is the failure this plugin exists to prevent.
+        return false;
+    }
+}
+function stamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+}
+function renderHandoff({ task, done, next, files, notes }) {
+    const lines = [`## Handoff`, ``, `**Task:** ${task}`, `**Done:** ${done}`, `**Next:** ${next}`];
+    if (files?.length) {
+        lines.push(``, `**Files in play:**`);
+        for (const f of files)
+            lines.push(`- ${f}`);
+    }
+    if (notes)
+        lines.push(``, `**Notes:**`, notes);
+    return lines.join("\n");
+}
+export const HandoffPlugin = async ({ client, directory }) => {
+    return {
+        tool: {
+            handoff: tool({
+                description: [
+                    "End the current session at a phase boundary and continue in a FRESH session.",
+                    "Persists a handoff note to disk, opens a new TUI session, and pre-fills its prompt",
+                    "with that note so the user only has to press enter.",
+                    "",
+                    "Use when: diagnosis is done and implementation has not started; the user asks for a",
+                    "new/clean session; context is large and the remaining work does not need the",
+                    "accumulated tool output; or the session-budget audit says to split.",
+                    "",
+                    "Write the handoff for a reader with ZERO context. Name real file paths and real",
+                    "identifiers you verified this session -- the new session cannot see your scrollback.",
+                ].join("\n"),
+                args: {
+                    task: tool.schema.string().describe("The one-line task the next session must accomplish."),
+                    done: tool.schema
+                        .string()
+                        .describe("What is already finished and verified. Be concrete; include findings worth keeping."),
+                    next: tool.schema.string().describe("The exact next action the fresh session should take first."),
+                    files: tool.schema
+                        .array(tool.schema.string())
+                        .optional()
+                        .describe("Absolute paths (file:line where useful) the next session will need to open."),
+                    notes: tool.schema
+                        .string()
+                        .optional()
+                        .describe("Decisions, constraints, dead ends already ruled out, verified identifiers/commands."),
+                    submit: tool.schema
+                        .boolean()
+                        .optional()
+                        .describe("Auto-submit the handoff in the new session. Default false: the user presses enter."),
+                },
+                async execute(args, ctx) {
+                    if (await isSubagent(client, ctx.agent)) {
+                        return {
+                            title: "Handoff refused",
+                            output: [
+                                `handoff is not available to subagents (you are "${ctx.agent}", mode: subagent).`,
+                                `Return your findings to the parent agent and let it decide whether to split.`,
+                            ].join("\n"),
+                            metadata: { refused: "subagent", agent: ctx.agent },
+                        };
+                    }
+                    const body = renderHandoff(args);
+                    await fs.mkdir(HANDOFF_DIR, { recursive: true });
+                    const notePath = path.join(HANDOFF_DIR, `${stamp()}-${ctx.sessionID}.md`);
+                    // Persist BEFORE switching. If the TUI call fails, the handoff still
+                    // exists on disk and the user can recover it manually; the reverse
+                    // ordering would lose the note on exactly the failure that matters.
+                    await fs.writeFile(notePath, `${body}\n\n_from session ${ctx.sessionID} in ${directory}_\n`, "utf8");
+                    log(`${ctx.sessionID} handoff written to ${notePath}`);
+                    const prompt = `${body}\n\n_Handoff note: ${notePath}_\n`;
+                    await client.tui.executeCommand({ body: { command: "session_new" } });
+                    await sleep(SWITCH_SETTLE_MS);
+                    await client.tui.appendPrompt({ body: { text: prompt } });
+                    if (args.submit)
+                        await client.tui.submitPrompt();
+                    await client.tui.showToast({
+                        body: {
+                            title: "Handoff",
+                            message: args.submit ? "New session started" : "New session ready — press enter",
+                            variant: "success",
+                        },
+                    });
+                    return {
+                        title: "Handed off to new session",
+                        output: [
+                            `Handoff written to ${notePath}`,
+                            `New session opened; prompt ${args.submit ? "submitted" : "pre-filled (awaiting enter)"}.`,
+                            ``,
+                            `STOP HERE. This session is over. Do not continue the task, do not make further`,
+                            `tool calls, and do not summarize beyond one line — the work now belongs to the`,
+                            `new session. Continuing here spends the context the handoff exists to discard.`,
+                        ].join("\n"),
+                        metadata: { notePath, submitted: !!args.submit },
+                    };
+                },
+            }),
+        },
+    };
+};
+//# sourceMappingURL=handoff.js.map

package/dist/handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../src/handoff.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const TokenNormBudget: Plugin;
+export declare const TokenNormHandoff: Plugin;

package/dist/index.js

@@ -0,0 +1,9 @@
+import { BUDGET_ENABLED, HANDOFF_ENABLED } from "./config.js";
+import { SessionBudgetPlugin } from "./session-budget.js";
+import { HandoffPlugin } from "./handoff.js";
+const noop = async () => ({});
+// Both halves are exported so a user can load one without the other, and both
+// respect an env kill switch so opting out never requires uninstalling.
+export const TokenNormBudget = BUDGET_ENABLED ? SessionBudgetPlugin : noop;
+export const TokenNormHandoff = HANDOFF_ENABLED ? HandoffPlugin : noop;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,MAAM,IAAI,GAAW,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;AAErC,8EAA8E;AAC9E,wEAAwE;AACxE,MAAM,CAAC,MAAM,eAAe,GAAW,cAAc,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAA;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAW,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAA"}

package/dist/log.d.ts

@@ -0,0 +1 @@
+export declare function log(line: string): void;

package/dist/log.js

@@ -0,0 +1,13 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { LOG_PATH } from "./config.js";
+export function log(line) {
+    try {
+        mkdirSync(dirname(LOG_PATH), { recursive: true });
+        appendFileSync(LOG_PATH, `${new Date().toISOString()} ${line}\n`);
+    }
+    catch {
+        /* logging must never break a session */
+    }
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACjD,cAAc,CAAC,QAAQ,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC,CAAA;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;IAC1C,CAAC;AACH,CAAC"}

package/dist/session-budget.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const SessionBudgetPlugin: Plugin;

package/dist/session-budget.js

@@ -0,0 +1,175 @@
+// Session budget enforcement (always-on, all projects).
+//
+// WHY THIS EXISTS
+// A token norm written into AGENTS.md loads into every session and is still
+// broken, because the rules that survive are the ones that do not depend on the
+// agent choosing to follow them. Capping bash output works every time because a
+// plugin rewrites the command and nobody has to remember it. The two rules with
+// no mechanism -- "announce the cost before a big task" and "run the audit
+// midway" -- were the exact two that failed in a 184-call, 3.0M effective-token
+// session where the norm was in context the whole time.
+//
+// So this plugin does not add advice. It counts, and at thresholds it staples
+// a notice onto tool output the agent is already reading. An instruction the
+// agent cannot skip past beats an instruction it merely has.
+//
+// It never blocks, never edits args, never fails a tool call: a wrong guess
+// here must cost a few lines of text, not a broken session.
+import { runAudit } from "./audit.js";
+import { log } from "./log.js";
+import { ANNOUNCE_AT, AUDIT_EVERY, BOUNDARY_AT, CHEAP_TOOLS } from "./config.js";
+const state = new Map();
+function track(sessionID, tool) {
+    let s = state.get(sessionID);
+    if (!s) {
+        s = { calls: 0, announced: false, lastAudit: 0, tools: new Map(), seenMessages: new Set(), pendingBoundary: false };
+        state.set(sessionID, s);
+    }
+    if (!CHEAP_TOOLS.has(tool))
+        s.calls++;
+    s.tools.set(tool, (s.tools.get(tool) ?? 0) + 1);
+    return s;
+}
+function topTools(s) {
+    return [...s.tools.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([t, n]) => `${t} ${n}`)
+        .join(", ");
+}
+function note(lines) {
+    return `\n\n<system-reminder>\n${lines.join("\n")}\n</system-reminder>`;
+}
+export const SessionBudgetPlugin = async () => {
+    return {
+        // A new user message in an already-large session is the task boundary the
+        // norm cares about most, and the one with no mechanism until now. In a
+        // 195k-token session the agent had the rule in context, ran the audit,
+        // reported "77x cache, bloat HIGH" -- and then continued anyway, because a
+        // second task ("do all of them") was treated as a continuation of the
+        // "do everything" override granted for the first. Overrides are per-task;
+        // nothing enforced that. This fires on the NEXT tool call after such a
+        // message, which is the earliest point the agent cannot skip past.
+        event: async ({ event }) => {
+            try {
+                if (event?.type !== "message.updated")
+                    return;
+                const info = event.properties?.info;
+                if (info?.role !== "user")
+                    return;
+                const s = state.get(info.sessionID);
+                if (!s || s.calls < BOUNDARY_AT)
+                    return;
+                // Dedupe on MESSAGE IDENTITY, not on call count.
+                //
+                // `message.updated` fires many times for the SAME user message (it is
+                // an update event: streaming, metadata, revisions). An earlier guard
+                // compared `boundaryAt === s.calls`, but `s.calls` increments on every
+                // tool call, so it went stale after one tool call and re-armed. One
+                // live session fired this reminder 61 times for a single user message
+                // -- on nearly every tool call for the rest of the session.
+                //
+                // That is worse than not firing at all. A warning that repeats on
+                // every tool call becomes wallpaper, and the agent learns to skip ALL
+                // system-reminders -- including the audit checkpoint, which in that
+                // same session was ignored precisely because it arrived buried in the
+                // 61st copy of this one. Cry wolf once per wolf.
+                if (!info.id || s.seenMessages.has(info.id))
+                    return;
+                s.seenMessages.add(info.id);
+                s.pendingBoundary = true;
+                log(`${info.sessionID} task-boundary at ${s.calls} calls (msg ${info.id})`);
+            }
+            catch {
+                /* a missed boundary must never break the session */
+            }
+        },
+        "tool.execute.after": async (input, output) => {
+            let s;
+            try {
+                s = track(input.sessionID, input.tool);
+            }
+            catch {
+                return;
+            }
+            // Threshold 0 -- task boundary. Highest priority: acting on it avoids
+            // the spend the other two thresholds only measure after the fact.
+            if (s.pendingBoundary) {
+                s.pendingBoundary = false;
+                output.output += note([
+                    `TOKEN NORM -- new request arrived ${s.calls} tool calls deep. This is a TASK BOUNDARY.`,
+                    `A prior "do everything" / "don't ask" was scoped to the PREVIOUS task. It does not carry.`,
+                    `Before continuing, in your next message:`,
+                    `  1. Say whether this request names new files/subsystems (-> new task, not a continuation).`,
+                    `  2. If new: propose finishing here with a 3-line handoff (done / state / next),`,
+                    `     and let the user start it fresh. Cold start = system floor + a few targeted reads.`,
+                    `  3. If the user re-grants the override, proceed -- but state the cost first.`,
+                    `Do NOT justify continuing with "finishing here beats reloading cold". That reasoning`,
+                    `is always available, feels free only because this context is already warm, and is the`,
+                    `exact rationalization the norm exists to block.`,
+                ]);
+                return;
+            }
+            // Threshold 1 -- the startup reflex, fired late but before the bulk of
+            // the spend. The norm wants this BEFORE the work; in practice the agent
+            // only discovers the true size once it is underway, so catch it at the
+            // first moment the task is provably "big" and force the statement then.
+            if (!s.announced && s.calls >= ANNOUNCE_AT) {
+                s.announced = true;
+                log(`${input.sessionID} announce-threshold at ${s.calls} calls (${topTools(s)})`);
+                output.output += note([
+                    `TOKEN NORM -- ${s.calls} tool calls in this session (${topTools(s)}).`,
+                    `This is now a "big task" under the norm, which required a cost statement BEFORE starting.`,
+                    `Do this now, in your next message to the user, before more tool calls:`,
+                    `  1. State remaining expected tool calls and what will drive them.`,
+                    `  2. State your caps (read windows, smallest test target, no whole-file reads).`,
+                    `  3. Offer a session split: which part could ship now with a 3-line handoff?`,
+                    `If the user already said "do everything", the split is overridden -- the cost`,
+                    `statement and the audit are NOT. Say so explicitly rather than staying silent.`,
+                ]);
+                return;
+            }
+            // Threshold 2 -- the midway audit. Recurring, because the norm's real
+            // failure mode is a session that quietly runs 3x past where a split
+            // should have happened.
+            if (s.calls > 0 && s.calls - s.lastAudit >= AUDIT_EVERY) {
+                s.lastAudit = s.calls;
+                log(`${input.sessionID} audit-threshold at ${s.calls} calls (${topTools(s)})`);
+                // Run the audit HERE rather than asking the agent to run it.
+                //
+                // "Run this command and report the number" is advice, and advice at a
+                // checkpoint loses to the task in flight every time: one session was
+                // told to audit at call 79, kept working, and produced the number only
+                // when the user asked afterwards. The command is cheap, deterministic
+                // and read-only, so the plugin runs it and staples the RESULT on. The
+                // agent then has the number in hand and no step to defer -- only a
+                // fact to report.
+                const audit = runAudit();
+                output.output += note([
+                    `TOKEN NORM -- ${s.calls} tool calls. Audit checkpoint (ran for you):`,
+                    ``,
+                    audit,
+                    ``,
+                    `In your NEXT message, before continuing the task: report the effective-token`,
+                    `number and the cache multiplier to the user, and say whether you are splitting.`,
+                    `If work remains: state/done/next in a NOTES file, then propose a fresh session.`,
+                ]);
+            }
+        },
+        // Compaction is the one moment the agent provably re-reads its own rules.
+        // Adding the number matters, because "you are 180 calls deep" is a fact
+        // that changes behavior and "be frugal" is not.
+        "experimental.session.compacting": async (input, output) => {
+            const s = state.get(input.sessionID);
+            if (!s)
+                return;
+            output.context.push(`## Session budget at compaction
+This session has made ${s.calls} tool calls (${topTools(s)}).
+Compaction is itself evidence the session ran too long for one task.
+- Run the usage audit and report the effective-token number to the user.
+- Put state/done/next in a NOTES file, not in the rebuilt context.
+- Propose finishing here with a 3-line handoff and starting the next task fresh.`);
+        },
+    };
+};
+//# sourceMappingURL=session-budget.js.map

package/dist/session-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-budget.js","sourceRoot":"","sources":["../src/session-budget.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "opencode-token-norm",
+  "version": "0.1.0",
+  "description": "Enforces a token budget in OpenCode: counts tool calls, staples un-skippable reminders at thresholds, runs the usage audit for you, and makes the session split a single tool call",
+  "type": "module",
+  "license": "MIT",
+  "author": "salitaba",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/salitaba/opencode-token-norm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/salitaba/opencode-token-norm/issues"
+  },
+  "homepage": "https://github.com/salitaba/opencode-token-norm#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tokens",
+    "cost",
+    "context",
+    "budget",
+    "handoff",
+    "session"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.15.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/scripts/usage-audit.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""
+usage-audit — read-only token-usage audit for opencode sessions.
+
+Reports the four numbers that matter (calls, context/call, cache reads, read
+hogs) plus a cause breakdown, straight from opencode's local sqlite DB.
+Safe to run anytime: opens the DB read-only, never writes.
+
+Usage:
+  python3 usage-audit.py --last              # most recently updated session
+  python3 usage-audit.py --session <id>      # a specific session
+  python3 usage-audit.py --top 5             # rank recent sessions by cache reads
+  python3 usage-audit.py --top 5 --json      # machine-readable
+
+DB path: ~/.local/share/opencode/opencode.db (override with OPENCODE_DB).
+"""
+import argparse
+import json
+import os
+import sqlite3
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+DB = Path(os.environ.get("OPENCODE_DB", Path.home() / ".local/share/opencode/opencode.db"))
+
+
+def connect() -> sqlite3.Connection:
+    if not DB.exists():
+        sys.exit(f"no opencode db at {DB}")
+    c = sqlite3.connect(f"file:{DB}?mode=ro", uri=True)
+    c.row_factory = sqlite3.Row
+    return c
+
+
+def fmt(n: float) -> str:
+    if n >= 1e6:
+        return f"{n/1e6:.1f}M"
+    if n >= 1e3:
+        return f"{n/1e3:.0f}k"
+    return f"{n:.0f}"
+
+
+def effective_fresh(input_tok: int, cache_read: int, cache_write: int) -> float:
+    """Cost-normalized input: cache reads ~0.1x, writes ~1.25x (5-min TTL,
+    Anthropic list; other providers similar). This is the number that maps to
+    money — raw cache_read does not."""
+    return input_tok + 0.1 * cache_read + 1.25 * cache_write
+
+
+def session_rows(c: sqlite3.Connection, limit: int = 20):
+    return c.execute(
+        """select id, title, model, cost, tokens_input, tokens_output,
+                  tokens_cache_read, tokens_cache_write, time_updated
+           from session
+           where tokens_cache_read > 0 or tokens_input > 0
+           order by time_updated desc
+           limit ?""",
+        (limit,),
+    ).fetchall()
+
+
+def part_series(c: sqlite3.Connection, sid: str):
+    """Per-call token series + part-level byte hogs, from the parts table."""
+    try:
+        rows = c.execute(
+            """select p.data from part p
+                join message m on m.id = p.message_id
+                where p.session_id = ? and p.data like '%step-finish%'
+                order by p.time_created""",
+            (sid,),
+        ).fetchall()
+    except sqlite3.Error:
+        return None, None
+    calls = []
+    for (data,) in rows:
+        try:
+            p = json.loads(data)
+        except Exception:
+            continue
+        if p.get("type") != "step-finish" or not p.get("tokens"):
+            continue
+        t = p["tokens"]
+        calls.append(
+            {
+                "input": t.get("input", 0),
+                "output": t.get("output", 0),
+                "cache_read": t.get("cache", {}).get("read", 0),
+                "total": t.get("total", 0),
+            }
+        )
+    hogs = defaultdict(int)
+    cnt = Counter()
+    images = []
+    try:
+        rows2 = c.execute(
+            """select p.data from part p
+                join message m on m.id = p.message_id
+                where p.session_id = ?""",
+            (sid,),
+        ).fetchall()
+    except sqlite3.Error:
+        rows2 = []
+    for (data,) in rows2:
+        try:
+            p = json.loads(data)
+        except Exception:
+            continue
+        if p.get("type") != "tool":
+            continue
+        tool = p.get("tool", "?")
+        size = len(data)
+        hogs[tool] += size
+        cnt[tool] += 1
+        if tool == "read":
+            fp = p.get("state", {}).get("input", {}).get("filePath", "?")
+            if fp.lower().endswith((".png", ".jpg", ".jpeg", ".webp", ".gif")):
+                images.append((size, fp))
+    top_files = Counter()
+    try:
+        rows3 = c.execute(
+            """select p.data from part p
+                join message m on m.id = p.message_id
+                where p.session_id = ? and p.data like '%"tool":"read"%'""",
+            (sid,),
+        ).fetchall()
+    except sqlite3.Error:
+        rows3 = []
+    for (data,) in rows3:
+        try:
+            p = json.loads(data)
+        except Exception:
+            continue
+        if p.get("type") != "tool" or p.get("tool") != "read":
+            continue
+        fp = p.get("state", {}).get("input", {}).get("filePath", "?")
+        top_files[fp] += len(data)
+    return calls, {"tools": hogs, "counts": cnt, "top_files": top_files, "images": sorted(images, reverse=True)}
+
+
+def med(xs):
+    if not xs:
+        return 0
+    s = sorted(xs)
+    return s[len(s) // 2]
+
+
+def audit(sid: str) -> dict:
+    c = connect()
+    r = c.execute(
+        """select id, title, model, cost, tokens_input, tokens_output,
+                  tokens_cache_read, tokens_cache_write, time_updated
+           from session where id = ?""",
+        (sid,),
+    ).fetchone()
+    if not r:
+        sys.exit(f"no session {sid}")
+    calls, hogs = part_series(c, sid)
+    out = {
+        "session": r["id"],
+        "title": r["title"],
+        "model": json.loads(r["model"]).get("id") if r["model"] else None,
+        "totals": {
+            "input": r["tokens_input"] or 0,
+            "output": r["tokens_output"] or 0,
+            "cache_read": r["tokens_cache_read"] or 0,
+            "cache_write": r["tokens_cache_write"] or 0,
+            "effective_fresh": effective_fresh(
+                r["tokens_input"] or 0, r["tokens_cache_read"] or 0, r["tokens_cache_write"] or 0
+            ),
+            "cost_usd": r["cost"] or 0,
+        },
+    }
+    if calls:
+        out["calls"] = len(calls)
+        for k in ("input", "cache_read", "total"):
+            xs = [x[k] for x in calls]
+            out[f"per_call_{k}"] = {
+                "min": min(xs),
+                "median": med(xs),
+                "max": max(xs),
+            }
+        # first-call floor ~= system prompt + tools + skills tax
+        out["first_call_total"] = calls[0]["total"]
+    if hogs:
+        out["tool_bytes"] = {k: v for k, v in sorted(hogs["tools"].items(), key=lambda kv: -kv[1])}
+        out["top_file_reads"] = [
+            (fp, b) for fp, b in hogs["top_files"].most_common(10)
+        ]
+        out["image_attachments"] = [
+            (fp, b) for b, fp in hogs["images"][:6]
+        ]
+    c.close()
+    return out
+
+
+def rank(top: int) -> list:
+    c = connect()
+    rows = session_rows(c, top)
+    out = []
+    for r in rows:
+        model = None
+        try:
+            model = json.loads(r["model"]).get("id") if r["model"] else None
+        except Exception:
+            pass
+        out.append(
+            {
+                "id": r["id"],
+                "title": (r["title"] or "")[:60],
+                "model": model,
+                "input": r["tokens_input"] or 0,
+                "output": r["tokens_output"] or 0,
+                "cache_read": r["tokens_cache_read"] or 0,
+                "effective_fresh": effective_fresh(
+                    r["tokens_input"] or 0, r["tokens_cache_read"] or 0, r["tokens_cache_write"] or 0
+                ),
+            }
+        )
+    c.close()
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="audit opencode session token usage")
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--last", action="store_true", help="most recently updated session")
+    g.add_argument("--session", metavar="ID", help="session id")
+    g.add_argument("--top", type=int, metavar="N", help="rank the N most recent sessions")
+    ap.add_argument("--json", action="store_true", help="raw json output")
+    args = ap.parse_args()
+
+    if args.top:
+        rows = rank(args.top)
+        if args.json:
+            print(json.dumps(rows, indent=2))
+            return
+        rows.sort(key=lambda r: -r["effective_fresh"])
+        print(f"{'effective':>12} {'cache_read':>10} {'input':>8}  title")
+        for r in rows:
+            print(
+                f"{fmt(r['effective_fresh']):>12} {fmt(r['cache_read']):>10} {fmt(r['input']):>8}  "
+                f"{r['title']}  ({r['id'][4:16]}…)  {r['model']}"
+            )
+        return
+
+    sid = None
+    if args.session:
+        sid = args.session
+    elif args.last:
+        c = connect()
+        r = c.execute("select id from session order by time_updated desc limit 1").fetchone()
+        c.close()
+        sid = r["id"] if r else None
+    if not sid:
+        sys.exit("no session found")
+    a = audit(sid)
+    if args.json:
+        print(json.dumps(a, indent=2))
+        return
+
+    t = a["totals"]
+    eff = t["effective_fresh"]
+    print(f"session : {a['session']}  «{a['title']}»")
+    print(f"model   : {a['model']}")
+    print(f"totals  : input {fmt(t['input'])}  output {fmt(t['output'])}  "
+          f"cache_read {fmt(t['cache_read'])}  cache_write {fmt(t['cache_write'])}")
+    print(f"effective fresh tokens: {fmt(eff)}   (input + 0.1·cache_read + 1.25·cache_write — the money number)   cost ${t['cost_usd']:.4f}")
+    if "calls" in a:
+        p = a["per_call_total"]
+        c = a["per_call_cache_read"]
+        print(f"calls   : {a['calls']}   context/call min {fmt(p['min'])} med {fmt(p['median'])} max {fmt(p['max'])}")
+        print(f"cacheR  : per-call med {fmt(c['median'])}  (first-call total {fmt(a['first_call_total'])} = system floor)")
+        ratio = t["cache_read"] / max(1, t["input"] + t["output"])
+        print(f"cache   : {ratio:.0f}x fresh tokens — bloat driver "
+              + ("HIGH" if p["median"] > 120000 else "ok" if p["median"] <= 60000 else "watch"))
+    print("tool bytes (payload that re-enters the conversation):")
+    for tool, b in a.get("tool_bytes", {}).items():
+        print(f"  {tool:10s} {fmt(b):>8} B")
+    print("biggest file reads (bytes re-entering context):")
+    for fp, b in a.get("top_file_reads", [])[:8]:
+        print(f"  {fmt(b):>8} B  {fp}")
+    imgs = a.get("image_attachments", [])
+    if imgs:
+        print("image attachments — each is ~1.3k-1.6k vision tokens per call "
+              "it stays in history (28x28-px tiles), NOT priced by file bytes:")
+        for fp, b in imgs:
+            print(f"  {fmt(b):>8} B  {fp}")
+
+
+if __name__ == "__main__":
+    main()