opencode-context-indicator 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ Notable user-facing changes per release. Dates are commit days (UTC).
 The package also ships a dual V1/V2 plugin — see the README for the surface
 matrix; everything below concerns the V2 path unless stated otherwise.
 
+## 1.5.0 — 2026-10-16
+
+Highlights: two new context-health signals — the **provider-reported prompt
+cache** (exact) and a **waste detector** for redundant tool output already in
+the context.
+
+- **Prompt cache (provider-reported)**: `session.step.ended` carries
+  `tokens.cache.{read,write}` — the provider's EXACT prompt-cache figures. Shown
+  as `prompt cache read=X (Y% of input) · write=Z` in `/context-breakdown`
+  (a `### Prompt cache` section), `/context`, the `./cx` panel and the live log.
+  It is a **subset of `input`**, so it is deliberately **not** added to the
+  category sum (no double-count). `n/a` when the provider reports nothing;
+  persisted as `cacheRead`/`cacheWrite` and inherited by mirror writes (a
+  non-measuring write cannot drop them).
+- **Waste detector**: finds tool output already in the context that is redundant
+  — the **same target** invoked repeatedly (the same file read twice, the same
+  URL fetched again) or **byte-identical output**. Reported as a `### Potential
+  reclaim (redundant tool output)` section in `/context-breakdown` (top findings
+  with tool + target) plus a `reclaim ~X redundant tool output (N dup)` panel/log
+  line. The number is the non-largest member of each duplicate group — an honest
+  *"N copies are in context; trimming/compaction could reclaim ~X"*, never "the
+  model wasted effort". Findings are **path-free** in the persisted/exported
+  form; the estimate is computed on both the hook and the fallback path.
+- Tests: T23/T23a/T23b (cache persistence, surfaces, sanitisation), T24–T24c
+  (reclaim algorithm, target extraction, hook capture via call-id correlation,
+  path-free persistence + rendering).
+- Legacy `state.json` entries (without the new fields) behave exactly as before.
+
 ## 1.4.1 — 2026-10-14
 
 Highlights: the `toolOut` category is now split **by tool name**, and a

package/README.md

@@ -40,6 +40,8 @@ For every served request the plugin estimates how the context window is split:
   tool schemas 1.4k (est tokens)
   other       5.6k (= input - sum of estimates)
   source      context-hook
+  prompt cache read=12.0k (27% of input) write=1.1k (provider-reported)
+  reclaim     ~9.8k redundant tool output (3 duplicate(s) — estimate)
   subagents   2 session(s): in=8.1k out=2.3k r=1.0k worst=12%
 ```
 
@@ -56,6 +58,18 @@ For every served request the plugin estimates how the context window is split:
 * `ctx` is OpenCode's native overflow count: `tokens.total` when present, else
   `input + output + cache.read + cache.write`. Percentages are **not clamped**
   at 100% — exceeding the window stays visible.
+* `prompt cache` is **provider-reported and exact** (`tokens.cache.read` /
+  `tokens.cache.write`), shown as a share of `input`. It is a *subset* of input,
+  so it is deliberately **not** added to the category sum: a cache read means the
+  provider served those prompt tokens from its prompt cache, not that they are
+  absent from the window. `n/a` when the provider reports nothing.
+* `reclaim` is the **waste detector**: tool output already in the context that is
+  redundant — the **same target** invoked repeatedly (the same file read twice,
+  the same URL fetched again) or **byte-identical output**. It is an estimate of
+  what trimming/compaction could reclaim (the non-largest member of each
+  duplicate group), reported honestly as *"N redundant tool outputs ≈ X tokens"*
+  — never as "the model wasted effort". Findings are per-session and **path-free
+  in the persisted/exported form**.
 * The denominator is the **opencode v2.0.23 compaction ceiling**: `window =
   limit.input || limit.context`; `reserve = max(floor(window * 0.1), window >=
   32_000 ? 16_000 : 0)`; the ceiling is `window - reserve`. When opencode
@@ -164,6 +178,13 @@ unavailable._
 
 ### Tool results by tool (main)
 webfetch 242.1k · read 18.4k · bash 4.9k · +3 more
+
+### Prompt cache (main, provider-reported)
+read 12.0k (27% of input) · write 1.1k
+
+### Potential reclaim (redundant tool output)
+- read src/a.ts x2 — ~9.8k reclaimable
+_~9.8k across 3 redundant tool output(s) — estimate of what trimming/compaction could reclaim._
 ```
 
 It is delivered with `resume:true` **and** a verbatim instruction prefix, so the
@@ -553,7 +574,7 @@ caller.
 ### Running tests
 
 ```bash
-npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1–T22 unit checks
+npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1–T24 unit checks
 npm run test:e2e              # full E2E: isolated plugin load + one "Say OK" round-trip
 npm run test:e2e:quick        # E2E load-only, no LLM call
 npm run test:drift            # OpenTUI pin vs the latest RELEASED opencode (also in CI)
@@ -574,7 +595,7 @@ STEP 80 s, ~3 min total.
 | (a) tarball composition | `package.json` `files[]` expands to the base files plus every `lib/*` module (count asserted dynamically) | no test/node_modules/tsconfig in the tarball |
 | (b) pragma regression | esbuild `--jsx=automatic` → `@opentui/solid/jsx-runtime` present, `react/jsx-runtime` absent | a removed/broken pragma kills the sidebar on npm install |
 | (c) resolve chain | replica install: host-bridged + peer packages resolve; local tui.tsx relative imports resolve via node from the entry (resolve-bridge.cjs) | broken peer/optional dep or a bad local import silently breaks the sidebar |
-| (d) unit harness T1–T22 | limit/agent/state fix assertions plus measureContributors, redacted-export, shared category-helper and sanitizer/unicode checks (51 total) | regressions in modelLimits, writeStateFile, hydrate, contributors, export |
+| (d) unit harness T1–T24 | limit/agent/state fix assertions plus measureContributors, redacted-export, shared category-helper, sanitizer/unicode, prompt-cache and waste-detector checks (58 total) | regressions in modelLimits, writeStateFile, hydrate, contributors, export |
 | (e) corporate-identifier scan | no forbidden identifiers in the published surface + test tree | compliance |
 | (f) non-English scan | no non-ASCII letters (`\p{L}` above U+007F) in any repo file | English-only source rule |
 

package/index.js

@@ -151,7 +151,7 @@
 
 import { makeV1 } from "./lib/v1.js";
 import { handleV2Event, onV2Context, estimateBreakdownFromContext, estimateBreakdownFromClientMessages } from "./lib/v2.js";
-import { breakdownCategories, estimateTokens, isSafeSessionKey, safeCell, safeToolOutByTool, sumCategories, toolOutEntries } from "./lib/estimate.js";
+import { breakdownCategories, computeReclaim, contentFingerprint, estimateTokens, extractToolTarget, isSafeSessionKey, safeCell, safeReclaim, safeSaneOrNull, safeToolOutByTool, sumCategories, toolOutEntries } from "./lib/estimate.js";
 import {
   commandContextBreakdown,
   commandContextSummary,
@@ -170,7 +170,7 @@ import {
   modelLimits,
   reserveFor,
 } from "./lib/limits.js";
-import { sessionAgentCache, sessionParentCache } from "./lib/cache.js";
+import { lastKnownCacheRead, lastKnownCacheWrite, sessionAgentCache, sessionParentCache } from "./lib/cache.js";
 import {
   logErr,
   readStateSnapshot,
@@ -211,6 +211,13 @@ export {
   safeCell,
   isSafeSessionKey,
   estimateTokens,
+  extractToolTarget,
+  contentFingerprint,
+  computeReclaim,
+  safeReclaim,
+  safeSaneOrNull,
+  lastKnownCacheRead,
+  lastKnownCacheWrite,
 };
 
 // ---------------------------------------------------------------------------

package/lib/cache.js

@@ -53,6 +53,12 @@ const lastKnownReasoningCache = new Map();
 // sessionID -> last native opencode overflow count (tokens.total, else
 // input + output + cache.read + cache.write)
 const lastKnownCtxCache = new Map();
+// sessionID -> last provider-reported prompt-cache figures from
+// session.step.ended (`tokens.cache.read` / `tokens.cache.write`). These are
+// EXACT provider numbers (not estimates) and are a subset of `input`, so they
+// are shown as a separate metric and never folded into the category sum.
+const lastKnownCacheReadCache = new Map();
+const lastKnownCacheWriteCache = new Map();
 
 // sessionID -> last time we wrote a live breakdown snapshot
 const lastBdWrite = new Map();
@@ -92,6 +98,16 @@ function lastKnownReasoning(sessionID) {
 function lastKnownCtx(sessionID) {
   return lastKnownCtxCache.get(sessionID) || 0;
 }
+// Provider-reported prompt-cache figures; null when the provider never reported
+// them (a plain "n/a" rather than a misleading 0).
+function lastKnownCacheRead(sessionID) {
+  const v = lastKnownCacheReadCache.get(sessionID);
+  return typeof v === "number" ? v : null;
+}
+function lastKnownCacheWrite(sessionID) {
+  const v = lastKnownCacheWriteCache.get(sessionID);
+  return typeof v === "number" ? v : null;
+}
 
 // ---------------------------------------------------------------------------
 // Clear per-session tracking. Full wipe on session.idle / session.deleted;
@@ -118,6 +134,8 @@ function clearSessionTracking(sessionID, keepToastDedup = false) {
   lastKnownInputCache.delete(sessionID);
   lastKnownReasoningCache.delete(sessionID);
   lastKnownCtxCache.delete(sessionID);
+  lastKnownCacheReadCache.delete(sessionID);
+  lastKnownCacheWriteCache.delete(sessionID);
   lastBdWrite.delete(sessionID);
   // V2 subagent accumulation for this session.
   sessionTotals.delete(sessionID);
@@ -145,6 +163,8 @@ export {
   lastKnownInputCache,
   lastKnownReasoningCache,
   lastKnownCtxCache,
+  lastKnownCacheReadCache,
+  lastKnownCacheWriteCache,
   lastBdWrite,
   lastErrorToast,
   lastCompactedToast,
@@ -157,5 +177,7 @@ export {
   lastKnownInput,
   lastKnownReasoning,
   lastKnownCtx,
+  lastKnownCacheRead,
+  lastKnownCacheWrite,
   clearSessionTracking,
 };

package/lib/commands.js

@@ -14,6 +14,8 @@ import {
   safeCategories,
   safeCell,
   safeCount,
+  safeReclaim,
+  safeSaneOrNull,
   safeToolOutByTool,
   sumCategories,
   toolOutEntries,
@@ -21,6 +23,8 @@ import {
 } from "./estimate.js";
 import {
   breakdownCache,
+  lastKnownCacheRead,
+  lastKnownCacheWrite,
   lastKnownCtx,
   lastKnownInput,
   lastKnownModel,
@@ -272,6 +276,19 @@ async function collectSessionReport(ctx, sessionID, state, deadline) {
     : safeToolOutByTool(entry?.toolOutByTool) ||
       safeToolOutByTool(fallbackParts?.toolOutByTool);
   const compactStale = entry?.compactStale === true;
+  // Provider-reported prompt cache (exact; subset of input). Live cache first,
+  // then the persisted snapshot.
+  const cacheRead =
+    safeSaneOrNull(lastKnownCacheRead(sessionID)) ??
+    safeSaneOrNull(entry?.cacheRead);
+  const cacheWrite =
+    safeSaneOrNull(lastKnownCacheWrite(sessionID)) ??
+    safeSaneOrNull(entry?.cacheWrite);
+  // Redundant tool output. The live breakdown owns targets; the persisted entry
+  // has them stripped (path-free) — sanitise both.
+  const reclaim = bd
+    ? safeReclaim(bd.reclaim, true)
+    : safeReclaim(entry?.reclaim, false);
   return {
     sessionID,
     parentID,
@@ -279,10 +296,14 @@ async function collectSessionReport(ctx, sessionID, state, deadline) {
     modelID,
     providerID,
     ctxTokens,
+    inputTokens: lastKnownInput(sessionID) || entry?.input || 0,
     usable,
     reserve,
     categories,
     toolOutByTool,
+    reclaim,
+    cacheRead,
+    cacheWrite,
     compactStale,
     source,
     updatedAt,
@@ -321,6 +342,41 @@ function renderToolOutLine(toolOutByTool, limit) {
   return parts.join(" · ");
 }
 
+// Provider-reported prompt cache for the main session — EXACT numbers, a
+// SUBSET of input (so the percentage is "of input", never a category). Empty
+// when the provider never reported cache tokens.
+function renderCacheLine(r) {
+  if (!r || (r.cacheRead == null && r.cacheWrite == null)) return "";
+  const read = r.cacheRead != null ? fmt(r.cacheRead) : "0";
+  const write = r.cacheWrite != null ? fmt(r.cacheWrite) : "0";
+  const pct =
+    r.cacheRead != null && r.inputTokens > 0
+      ? ` (${((r.cacheRead / r.inputTokens) * 100).toFixed(0)}% of input)`
+      : "";
+  return `read ${read}${pct} · write ${write}`;
+}
+
+// Redundant tool output already in context (repeated target / identical output).
+// Targets are shown only when present (the live breakdown has them; the
+// persisted/redacted path strips them).
+function renderReclaimSection(r) {
+  const rc = r?.reclaim;
+  if (!rc || rc.tokens <= 0) return "";
+  const lines = ["", "### Potential reclaim (redundant tool output)"];
+  for (const f of rc.findings || []) {
+    const label = f.target
+      ? `${safeCell(f.name)} ${safeCell(f.target)}`
+      : f.kind === "content"
+        ? `${safeCell(f.name)} (identical output)`
+        : safeCell(f.name);
+    lines.push(`- ${label} x${f.n} — ~${fmt(f.tokens)} reclaimable`);
+  }
+  lines.push(
+    `_~${fmt(rc.tokens)} across ${rc.count} redundant tool output(s) — estimate of what trimming/compaction could reclaim._`,
+  );
+  return lines.join("\n");
+}
+
 function renderBreakdownTable(rows, childCount, mainReport) {
   const lines = [];
   lines.push("### Context breakdown");
@@ -346,6 +402,16 @@ function renderBreakdownTable(rows, childCount, mainReport) {
     lines.push("### Tool results by tool (main)");
     lines.push(byTool);
   }
+  // Provider-reported prompt cache (exact; a subset of input).
+  const cache = renderCacheLine(mainReport);
+  if (cache) {
+    lines.push("");
+    lines.push("### Prompt cache (main, provider-reported)");
+    lines.push(cache);
+  }
+  // Redundant tool output (waste detector).
+  const reclaim = renderReclaimSection(mainReport);
+  if (reclaim) lines.push(reclaim);
   return lines.join("\n");
 }
 
@@ -416,6 +482,10 @@ function shortSummaryText(r) {
     }
     lines.push(compact);
   }
+  // Provider-reported prompt cache (exact; subset of input) — shown when the
+  // provider reported it.
+  const cache = renderCacheLine(r);
+  if (cache) lines.push(`prompt cache ${cache}`);
   lines.push(`updated ${timeOnly(r.updatedAt)} (${sourceTag(r.source)})`);
   if (r.compactStale) {
     lines.push(

package/lib/estimate.js

@@ -81,6 +81,18 @@ function safeCountOrNull(v) {
   return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
 }
 
+// A finite, non-negative, SANE number or null — for persisted provider-reported
+// figures (cache read/write). Like safeCountOrNull but also rejects absurd
+// magnitudes, so a poisoned state.json cannot render garbage (fmt(NaN), 1e15).
+function safeSaneOrNull(v) {
+  return typeof v === "number" &&
+    Number.isFinite(v) &&
+    v >= 0 &&
+    v <= MAX_SANE_LIMIT
+    ? v
+    : null;
+}
+
 // Normalise a categories object from untrusted input (state.json) into the 8
 // known numeric fields — never trust its shape. `toolOut` is 0 for legacy
 // entries written before the category existed (their tool results stay folded
@@ -198,6 +210,210 @@ function toolOutEntries(map, limit = 8) {
     .slice(0, Math.max(0, limit));
 }
 
+// ---------------------------------------------------------------------------
+// Waste detection: find redundant tool output already sitting in the context.
+// Pure transforms — the caller supplies per-call instances captured from the
+// request payload; nothing here touches the fs or the caches.
+// ---------------------------------------------------------------------------
+
+// Best-effort TARGET of a tool call, from the per-call input. A short, stable
+// string used only to group repeated calls (the same file read twice) and to
+// label a finding. Returns null when no suitable string field exists. The value
+// is untrusted (tool args); it is whitespace-collapsed and bounded here, and
+// display layers sanitise it further.
+const TARGET_FIELD_MAP = {
+  webfetch: ["url", "uri"],
+  fetch: ["url", "uri"],
+  bash: ["command", "cmd"],
+  shell: ["command", "cmd"],
+  grep: ["pattern", "query", "regex", "path"],
+  search: ["query", "pattern"],
+  glob: ["pattern", "path"],
+  read: ["filePath", "file", "path", "filename"],
+  read_file: ["filePath", "file", "path", "filename"],
+  write: ["filePath", "file", "path", "filename"],
+  edit: ["filePath", "file", "path", "filename"],
+  list: ["path", "dir"],
+  ls: ["path", "dir"],
+  task: ["description", "prompt"],
+  agent: ["description", "prompt"],
+};
+function extractToolTarget(name, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const n = typeof name === "string" ? name.toLowerCase() : "";
+  const fields = TARGET_FIELD_MAP[n];
+  const pick = (keys) => {
+    for (const k of keys) {
+      const v = input[k];
+      if (typeof v === "string" && v.length > 0) return v;
+    }
+    return null;
+  };
+  let t = fields ? pick(fields) : null;
+  if (t == null) {
+    // Generic fallback: the first non-empty string-valued field. Bounded scan
+    // (the input object is untrusted) so a crafted huge input cannot stall us.
+    let scanned = 0;
+    for (const k of Object.keys(input)) {
+      if (++scanned > 32) break;
+      const v = input[k];
+      if (typeof v === "string" && v.length > 0) {
+        t = v;
+        break;
+      }
+    }
+  }
+  if (typeof t !== "string" || t.length === 0) return null;
+  // Slice BEFORE the whitespace pass: normalising an untrusted multi-MB string
+  // is the expensive part, so cap the work first.
+  return t.slice(0, 400).replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
+// Cheap content fingerprint of a tool RESULT (length + FNV-1a over the first
+// 4KB). Used to detect byte-identical outputs already in context. Not
+// cryptographic — deliberately cheap (runs on every model request).
+function contentFingerprint(text) {
+  if (typeof text !== "string" || text.length === 0) return "";
+  const s = text.length > 4096 ? text.slice(0, 4096) : text;
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `${text.length}:${(h >>> 0).toString(36)}`;
+}
+
+// Group per-call instances and estimate the tool-output tokens that are
+// redundant (the same target invoked repeatedly, or byte-identical outputs).
+// `instances`: [{ name, target, tokens, fp }]. Reclaim = the sum of the
+// NON-largest member of every group of size >= 2, unioned across target- and
+// content-groups so an instance is counted once. This is a LOWER bound of what
+// compaction/trim could reclaim — labelled as an estimate everywhere.
+function computeReclaim(instances, maxFindings = 8) {
+  const list = Array.isArray(instances) ? instances : [];
+  const byTarget = new Map();
+  const byContent = new Map();
+  const push = (map, key, idx) => {
+    const a = map.get(key);
+    if (a) a.push(idx);
+    else map.set(key, [idx]);
+  };
+  for (let i = 0; i < list.length; i++) {
+    const it = list[i];
+    if (safeCount(it?.tokens) <= 0) continue;
+    const name = typeof it?.name === "string" && it.name ? it.name : "?";
+    const target =
+      typeof it?.target === "string" && it.target ? it.target : null;
+    if (target) push(byTarget, `${name}\u0000${target}`, i);
+    const fp = typeof it?.fp === "string" && it.fp ? it.fp : "";
+    if (fp) push(byContent, fp, i);
+  }
+  // Resolve each group's keeper (largest member) once.
+  const buildGroups = (map) => {
+    const out = [];
+    for (const idxs of map.values()) {
+      if (idxs.length < 2) continue;
+      let maxI = idxs[0];
+      for (const i of idxs) {
+        if (safeCount(list[i]?.tokens) > safeCount(list[maxI]?.tokens)) maxI = i;
+      }
+      let groupTokens = 0;
+      for (const i of idxs) {
+        if (i !== maxI) groupTokens += safeCount(list[i]?.tokens);
+      }
+      out.push({ idxs, maxI, groupTokens });
+    }
+    out.sort((a, b) => b.groupTokens - a.groupTokens);
+    return out;
+  };
+  const targetGroups = buildGroups(byTarget);
+  const contentGroups = buildGroups(byContent);
+
+  // The authoritative total: every instance that is NOT the largest member of
+  // at least one duplicate group, counted ONCE (union across group kinds).
+  const removable = new Set();
+  for (const g of targetGroups) {
+    for (const i of g.idxs) if (i !== g.maxI) removable.add(i);
+  }
+  for (const g of contentGroups) {
+    for (const i of g.idxs) if (i !== g.maxI) removable.add(i);
+  }
+  let tokens = 0;
+  for (const i of removable) tokens += safeCount(list[i]?.tokens);
+
+  // Findings: target groups first (they carry the target label), then content
+  // groups only for instances not already covered — so the rendered findings
+  // never sum to more than the headline total.
+  const findings = [];
+  const covered = new Set();
+  for (const g of targetGroups) {
+    const rep = list[g.maxI] || {};
+    findings.push({
+      kind: "target",
+      name: typeof rep.name === "string" ? rep.name : "?",
+      target: typeof rep.target === "string" ? rep.target : null,
+      n: g.idxs.length,
+      tokens: g.groupTokens,
+    });
+    for (const i of g.idxs) covered.add(i);
+  }
+  for (const g of contentGroups) {
+    let t = 0;
+    for (const i of g.idxs) {
+      if (i === g.maxI || covered.has(i)) continue;
+      t += safeCount(list[i]?.tokens);
+    }
+    if (t > 0) {
+      const rep = list[g.maxI] || {};
+      findings.push({
+        kind: "content",
+        name: typeof rep.name === "string" ? rep.name : "?",
+        target: null,
+        n: g.idxs.length,
+        tokens: t,
+      });
+    }
+  }
+  findings.sort((a, b) => b.tokens - a.tokens);
+  return {
+    tokens,
+    count: removable.size,
+    findings: findings.slice(0, Math.max(0, maxFindings)),
+  };
+}
+
+// Sanitise a reclaim summary from a live estimate OR persisted state.json
+// (untrusted). `keepTarget=false` drops the per-finding target so a persisted /
+// exported payload stays free of file paths and URLs. Returns null when there
+// is nothing worth showing.
+function safeReclaim(raw, keepTarget = true, maxFindings = 8) {
+  if (!raw || typeof raw !== "object") return null;
+  const tokens = safeCount(raw.tokens);
+  const count = safeCount(raw.count);
+  if (tokens <= 0 || count <= 0) return null;
+  const findings = [];
+  const src = Array.isArray(raw.findings) ? raw.findings : [];
+  for (const f of src) {
+    if (!f || typeof f !== "object") continue;
+    const name = isSafeSessionKey(f.name) && f.name.length <= 64 ? f.name : "?";
+    const ft = safeCount(f.tokens);
+    const fn = safeCount(f.n);
+    if (ft <= 0 || fn < 2) continue;
+    const item = {
+      kind: f.kind === "content" ? "content" : "target",
+      name,
+      n: fn,
+      tokens: ft,
+    };
+    if (keepTarget && typeof f.target === "string" && f.target.length > 0) {
+      item.target = f.target.slice(0, 200);
+    }
+    findings.push(item);
+    if (findings.length >= Math.max(0, maxFindings)) break;
+  }
+  return { tokens, count, findings };
+}
+
 function fmt(n) {
   return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
 }
@@ -307,6 +523,7 @@ export {
   finitePos,
   safeCount,
   safeCountOrNull,
+  safeSaneOrNull,
   safeCategories,
   sumCategories,
   breakdownCategories,
@@ -314,6 +531,10 @@ export {
   safeToolOutByTool,
   toolOutEntries,
   TOOL_OUT_MAX_KEYS,
+  extractToolTarget,
+  contentFingerprint,
+  computeReclaim,
+  safeReclaim,
   fmt,
   estimateTokens,
   estJson,

package/lib/state.js

@@ -27,6 +27,8 @@ import {
   oneLine,
   safeCount,
   safeCountOrNull,
+  safeReclaim,
+  safeSaneOrNull,
   safeToolOutByTool,
   sumCategories,
 } from "./estimate.js";
@@ -434,6 +436,23 @@ function writeStateFile(
         ? safeToolOutByTool(bd.toolOutByTool)
         : safeToolOutByTool(prevEntry?.toolOutByTool);
 
+      // Redundant tool output (waste detector). Persisted WITHOUT targets
+      // (keepTarget=false): state.json is a local temp file, but keeping it
+      // path-free matches the redacted-export policy. A present breakdown owns
+      // the value; otherwise inherit the persisted one.
+      const reclaim = bd
+        ? safeReclaim(bd.reclaim, false)
+        : safeReclaim(prevEntry?.reclaim, false);
+
+      // Provider-reported prompt cache (EXACT; a subset of input — never added
+      // to the category sum). Inherit when this write carries no fresh figure
+      // (idle / compaction mirror writes must not drop it).
+      const cacheRead =
+        safeSaneOrNull(opts?.cacheRead) ?? safeSaneOrNull(prevEntry?.cacheRead);
+      const cacheWrite =
+        safeSaneOrNull(opts?.cacheWrite) ??
+        safeSaneOrNull(prevEntry?.cacheWrite);
+
       // Compaction staleness: a `session.compacted` write re-persists the
       // pre-compaction numbers (the compaction flow fires no context hook), so
       // the entry is stale BY CONSTRUCTION — even when this instance has no live
@@ -526,6 +545,9 @@ function writeStateFile(
           other,
         },
         toolOutByTool,
+        reclaim,
+        cacheRead,
+        cacheWrite,
         compactedAt,
         compactStale,
         updatedAt: new Date().toISOString(),

package/lib/tui-data.d.ts

@@ -31,6 +31,20 @@ export interface StateEntry {
   categories?: Categories
   /** Per-tool tool-result split: tool name -> estimated tokens. */
   toolOutByTool?: Record<string, number>
+  /** Provider-reported prompt-cache tokens (exact; a subset of input). */
+  cacheRead?: number | null
+  cacheWrite?: number | null
+  /** Redundant tool output (waste detector). Findings here are path-free. */
+  reclaim?: {
+    tokens: number
+    count: number
+    findings?: Array<{
+      kind?: string
+      name?: string
+      n?: number
+      tokens?: number
+    }>
+  } | null
   /** ISO time of the last session.compacted (marker only). */
   compactedAt?: string | null
   /** True while the entry still shows pre-compaction numbers. */

package/lib/tui-panel.tsx

@@ -570,6 +570,29 @@ export function BreakdownPanel(props: {
                 : "")}
           </text>
         </Show>
+        <Show
+          when={
+            num(data().root?.cacheRead) > 0 ||
+            num(data().root?.cacheWrite) > 0
+          }
+        >
+          <text fg={muted()}>
+            {"  prompt cache r " +
+              fmt(num(data().root?.cacheRead)) +
+              " / w " +
+              fmt(num(data().root?.cacheWrite)) +
+              " (provider-reported)"}
+          </text>
+        </Show>
+        <Show when={num(data().root?.reclaim?.tokens) > 0}>
+          <text fg={muted()}>
+            {"  reclaim ~" +
+              fmt(num(data().root?.reclaim?.tokens)) +
+              " redundant tool output (" +
+              num(data().root?.reclaim?.count) +
+              " dup)"}
+          </text>
+        </Show>
         <Show when={messages().available}>
           <text fg={base()}>{"largest contributors (measured)"}</text>
           <Show

package/lib/v2.js

@@ -8,11 +8,15 @@
 
 import {
   breakdownCategories,
+  computeReclaim,
+  contentFingerprint,
   estJson,
   estimateTokens,
+  extractToolTarget,
   fmt,
   isSafeSessionKey,
   oneLine,
+  safeSaneOrNull,
   tokenCountOf,
   TOOL_OUT_MAX_KEYS,
   withTimeout,
@@ -25,6 +29,10 @@ import {
   lastBdWrite,
   lastKnownCtx,
   lastKnownCtxCache,
+  lastKnownCacheRead,
+  lastKnownCacheReadCache,
+  lastKnownCacheWrite,
+  lastKnownCacheWriteCache,
   lastKnownInput,
   lastKnownInputCache,
   lastKnownModel,
@@ -144,6 +152,34 @@ function toolResultChars(p) {
   return estJson(r.value); // json | error | unexpected shapes
 }
 
+// Concatenated text of a ToolResultPart payload, for content FINGERPRINTING
+// (bounded — the first ~4KB is enough to spot byte-identical outputs). Mirrors
+// the shapes handled by toolResultChars; file items are URI references, skipped.
+function toolResultText(p) {
+  const r = p?.result;
+  if (!r || typeof r !== "object") return "";
+  if (r.type === "content" && Array.isArray(r.value)) {
+    let out = "";
+    for (const item of r.value) {
+      if (item?.type === "text" && typeof item.text === "string") {
+        out += item.text;
+        if (out.length > 4096) break;
+      }
+    }
+    return out;
+  }
+  if (r.type === "text" && typeof r.value === "string") return r.value;
+  try {
+    return JSON.stringify(r.value);
+  } catch {
+    return "";
+  }
+}
+
+// Bound on tool-call instances tracked per request for waste detection (the
+// message history is untrusted and a runaway session could be huge).
+const MAX_WASTE_INSTANCES = 256;
+
 // Accumulate the per-tool tool-result estimate. Tool names are untrusted
 // (host tool ids, plugin-defined tools): unsafe names and any name beyond the
 // cap fold into "other tools" so the bucket never becomes a prototype vector
@@ -174,6 +210,11 @@ function estimateBreakdownFromContext(context, sessionID) {
   const toolOutByTool = {};
 
   const messages = Array.isArray(context?.messages) ? context.messages : [];
+  // Waste detection: correlate tool-call (input -> target) with its tool-result
+  // (-> tokens + content fingerprint) by call id, over the calls still present
+  // in the assembled context.
+  const callById = new Map();
+  const instances = [];
   for (const msg of messages) {
     const parts = Array.isArray(msg?.content) ? msg.content : [];
     for (const p of parts) {
@@ -184,6 +225,16 @@ function estimateBreakdownFromContext(context, sessionID) {
         const chars = toolResultChars(p);
         toolOutChars += chars;
         addToolOut(toolOutByTool, p?.name, chars);
+        if (chars > 0 && instances.length < MAX_WASTE_INSTANCES) {
+          const call = p?.id != null ? callById.get(p.id) : null;
+          const name = p?.name || call?.name || null;
+          instances.push({
+            name,
+            target: extractToolTarget(name, call?.input),
+            tokens: chars,
+            fp: contentFingerprint(toolResultText(p)),
+          });
+        }
         continue;
       }
       if (msg?.role === "user") {
@@ -195,10 +246,15 @@ function estimateBreakdownFromContext(context, sessionID) {
           reasoningChars += estimateTokens(p.text);
         } else if (p?.type === "tool-call") {
           toolArgsChars += estJson(p.input);
+          if (p?.id != null && callById.size < MAX_WASTE_INSTANCES && !callById.has(p.id)) {
+            callById.set(p.id, { name: p.name, input: p.input });
+          }
         }
       }
     }
   }
+  const reclaimRaw = instances.length > 0 ? computeReclaim(instances) : null;
+  const reclaim = reclaimRaw && reclaimRaw.tokens > 0 ? reclaimRaw : null;
 
   let systemChars = 0;
   const system = Array.isArray(context?.system) ? context.system : [];
@@ -239,6 +295,7 @@ function estimateBreakdownFromContext(context, sessionID) {
     toolOutByTool,
     systemChars,
     toolSchemasChars,
+    reclaim,
   };
 }
 
@@ -291,6 +348,7 @@ function estimateBreakdownFromClientMessages(messages) {
   let toolArgsChars = 0;
   let toolOutChars = 0;
   const toolOutByTool = {};
+  const instances = [];
   for (const m of messages || []) {
     if (!m || typeof m !== "object") continue;
     if (m.type === "user") {
@@ -315,20 +373,32 @@ function estimateBreakdownFromClientMessages(messages) {
           const content = p?.state?.content;
           if (Array.isArray(content)) {
             let outChars = 0;
+            let text = "";
             for (const item of content) {
               if (item?.type === "text" && typeof item.text === "string") {
                 outChars += estimateTokens(item.text);
+                if (text.length <= 4096) text += item.text;
               }
             }
             toolOutChars += outChars;
             // The persisted tool part carries its name on `p.name`
             // (SessionMessageAssistantTool.name) — same field as the hook path.
             addToolOut(toolOutByTool, p?.name, outChars);
+            if (outChars > 0 && instances.length < MAX_WASTE_INSTANCES) {
+              instances.push({
+                name: p?.name || null,
+                target: extractToolTarget(p?.name, input),
+                tokens: outChars,
+                fp: contentFingerprint(text),
+              });
+            }
           }
         }
       }
     }
   }
+  const reclaimRaw = instances.length > 0 ? computeReclaim(instances) : null;
+  const reclaim = reclaimRaw && reclaimRaw.tokens > 0 ? reclaimRaw : null;
   return {
     userChars,
     assistantChars,
@@ -338,6 +408,7 @@ function estimateBreakdownFromClientMessages(messages) {
     toolOutByTool,
     systemChars: null,
     toolSchemasChars: null,
+    reclaim,
   };
 }
 
@@ -496,6 +567,25 @@ function buildLiveLinesV2(sessionID, modelID, providerID, inputTokens, ctxTokens
   lines.push(`  other       ${fmt(other)} (= input - sum of estimates)`);
   lines.push(`  source      ${source}`);
 
+  // Provider-reported prompt cache (EXACT, not an estimate; a subset of input —
+  // never folded into the category sum). Absent when the provider stays silent.
+  const cr = lastKnownCacheRead(sessionID);
+  const cw = lastKnownCacheWrite(sessionID);
+  lines.push(
+    cr == null && cw == null
+      ? `  prompt cache n/a (provider reported no cache tokens)`
+      : `  prompt cache read=${fmt(cr || 0)} write=${fmt(cw || 0)} (provider-reported; subset of input)`,
+  );
+
+  // Redundant tool output already in context (repeated target / identical
+  // output). An estimate of what trimming/compaction could reclaim.
+  const rcl = bd?.reclaim || null;
+  if (rcl && rcl.tokens > 0) {
+    lines.push(
+      `  reclaim     ~${fmt(rcl.tokens)} redundant tool output (${rcl.count} duplicate(s) — estimate)`,
+    );
+  }
+
   try {
     const sub = aggregateSubagentsV2(sessionID);
     if (sub.count > 0) {
@@ -606,7 +696,11 @@ async function handleV2Event(ctx, event) {
         // flow fires no context hook — see README): mark the entry stale so the
         // UI shows the numbers as pre-compaction until the next model request
         // refreshes them.
-        { compacted: true },
+        {
+          compacted: true,
+          cacheRead: lastKnownCacheRead(sid),
+          cacheWrite: lastKnownCacheWrite(sid),
+        },
       );
       pushFinalSummary(
         `compacted:${event.id ?? sid}`,
@@ -646,6 +740,10 @@ async function handleV2Event(ctx, event) {
         lastKnownInput(sid),
         lastKnownCtx(sid),
         lastKnownReasoning(sid),
+        {
+          cacheRead: lastKnownCacheRead(sid),
+          cacheWrite: lastKnownCacheWrite(sid),
+        },
       );
       pushFinalSummary(`final:${event.id ?? sid}`, [
         `[${new Date().toISOString()}] FINAL session=${sid}`,
@@ -668,10 +766,16 @@ async function handleV2Event(ctx, event) {
     const output = typeof t.output === "number" ? t.output : 0;
     const reasoning = typeof t.reasoning === "number" ? t.reasoning : 0;
     const contextTokens = tokenCountOf(t);
+    // Provider-reported prompt-cache figures (exact): a subset of `input`.
+    // Sanitised — a NaN/negative/absurd provider value must never be persisted.
+    const cacheRead = safeSaneOrNull(t.cache?.read ?? t.cacheRead);
+    const cacheWrite = safeSaneOrNull(t.cache?.write ?? t.cacheWrite);
 
     lastKnownInputCache.set(sid, input);
     lastKnownCtxCache.set(sid, contextTokens);
     lastKnownReasoningCache.set(sid, reasoning);
+    if (cacheRead != null) lastKnownCacheReadCache.set(sid, cacheRead);
+    if (cacheWrite != null) lastKnownCacheWriteCache.set(sid, cacheWrite);
     if (!lastKnownModelCache.has(sid) && data.model) {
       // Some builds put the model on the step payload; harmless when absent.
       if (typeof data.model.id === "string") lastKnownModelCache.set(sid, data.model.id);
@@ -682,6 +786,8 @@ async function handleV2Event(ctx, event) {
     pruneMap(lastKnownInputCache, MAX_TRACKED_SESSIONS);
     pruneMap(lastKnownCtxCache, MAX_TRACKED_SESSIONS);
     pruneMap(lastKnownReasoningCache, MAX_TRACKED_SESSIONS);
+    pruneMap(lastKnownCacheReadCache, MAX_TRACKED_SESSIONS);
+    pruneMap(lastKnownCacheWriteCache, MAX_TRACKED_SESSIONS);
     pruneMap(lastKnownModelCache, MAX_TRACKED_SESSIONS);
     pruneMap(lastKnownProviderCache, MAX_TRACKED_SESSIONS);
 
@@ -740,6 +846,10 @@ async function handleV2Event(ctx, event) {
           input,
           contextTokens,
           reasoning,
+          {
+            cacheRead: lastKnownCacheRead(sid),
+            cacheWrite: lastKnownCacheWrite(sid),
+          },
         );
         writeLog(lines);
       } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context-indicator",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Real-time context-window usage for OpenCode: per-category token breakdown, a zero-LLM /cx panel with per-session cost and a searchable family-session picker, and a TUI sidebar. Dual V1 + V2 plugin entry.",
   "type": "module",
   "license": "MIT",
@@ -64,7 +64,7 @@
     "@opentui/solid": "0.5.17"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.0.28",
+    "@opencode/plugin": "2.0.30",
     "@opentui/core": "0.5.17",
     "@types/node": "26.6.3",
     "esbuild": "^0.28.2",