@yawlabs/ctxlint 0.24.1 → 0.25.0

package/.pre-commit-hooks.yaml

@@ -4,7 +4,7 @@
   # Version-pinned so a checkout at `rev: vX.Y.Z` runs exactly that release
   # of ctxlint — matches the pinning done by `ctxlint init`. release.sh keeps
   # this in sync with package.json on each bump.
-  entry: npx @yawlabs/ctxlint@0.24.1 --strict
+  entry: npx @yawlabs/ctxlint@0.25.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/AGENT_SESSION_LINT_SPEC.md

@@ -15,7 +15,7 @@ This specification defines a standard set of lint rules for validating agent ses
 
 The specification includes:
 - A reference of session data locations across 8 AI coding agents
-- 12 lint rules in the `session` category with defined severities
+- 13 lint rules in the `session` category with defined severities
 - A machine-readable rule catalog ([`agent-session-lint-rules.json`](./agent-session-lint-rules.json))
 - Sibling-repo detection for cross-project checks
 
@@ -51,6 +51,7 @@ This is the third pillar alongside context file linting (`CLAUDE.md`, `.cursorru
   - [2.10 session/unverified-gate-claimed-clean](#210-sessionunverified-gate-claimed-clean)
   - [2.11 session/default-branch-accumulation](#211-sessiondefault-branch-accumulation)
   - [2.12 session/unresolvable-sha](#212-sessionunresolvable-sha)
+  - [2.13 session/large-read](#213-sessionlarge-read)
 - [3. Rule Catalog (machine-readable)](#3-rule-catalog-machine-readable)
 - [4. Implementing This Specification](#4-implementing-this-specification)
 - [5. Contributing](#5-contributing)
@@ -106,7 +107,7 @@ Session data varies enormously in size and format. This specification targets on
 
 **What we explicitly DO NOT scan:**
 
-- **Full session transcripts** -- too large. Active projects can accumulate hundreds of megabytes of transcript data. Scanning these would be slow and yield low-signal results.
+- **Full session transcripts** -- too large. Active projects can accumulate hundreds of megabytes of transcript data. Scanning these would be slow and yield low-signal results. Rules whose signal is what the agent *did* read a bounded, project-scoped slice instead -- see §3, "Data sources".
 - **SQLite databases** -- Goose's `sessions.db` requires a SQLite dependency. Out of scope for v1. Future versions may add opt-in SQLite support.
 - **File history or shell snapshots** -- some agents capture filesystem state or shell output. These are agent-internal data and not useful for cross-project linting.
 
@@ -132,7 +133,7 @@ Skip hidden directories (starting with `.`) and `node_modules`.
 
 ## 2. Lint Rules
 
-12 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection or per-project history analysis.
+13 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection or per-project history analysis.
 
 Severity levels:
 - **error** -- the session data reveals a verifiably missing configuration. Should fail CI.
@@ -459,6 +460,36 @@ Detects a memory that cites a git SHA which no longer resolves in the repository
 
 ---
 
+### 2.13 session/large-read
+
+Measures how much of a project's session context goes to **whole-file Reads of large files**. It is a baseline, not a defect report.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/large-read` |
+| **Severity** | info |
+| **Trigger** | One or more whole-file `Read` calls (no `offset`, `limit` or `pages`) in the project transcript whose result is 4,000 tokens or more |
+| **Message** | `<count> whole-file Read(s) of 4,000+ tokens (<tokens> tokens); est. <carry> tokens of cache-read carry on later turns` |
+| **Source** | Claude Code transcript format; measured corpus (see Notes) |
+
+**Detection algorithm:**
+
+1. Read the project transcript (see §3, "Data sources"). For each `Read` tool_use, record whether it was partial (`offset`, `limit` or `pages` set), and pair it with its tool_result to count the result's tokens.
+2. Count each session's turns as distinct assistant `message.id`s, falling back to `requestId`, then to one turn per record. Claude Code writes one API response as several records that share an id. Harness-written `<synthetic>` records and sidechain records are not turns. Record the turn count at each `compact_boundary`.
+3. Keep whole-file, non-error Reads whose result is at least 4,000 tokens. A Read that appears twice -- a continued session copies earlier records into its own file under a new session id -- is counted once, by its `tool_use` id.
+4. For each, carry = result tokens × the later turns of its session that re-sent it: from the turn after the Read to the session's last turn or its next compaction, whichever comes first.
+5. When anything qualified, emit ONE info finding per project with the count, total tokens, summed carry, and the top three files by tokens with their read counts. Emit nothing otherwise. When the transcript read was capped, say so in the finding.
+
+**Notes:**
+- Why it matters: a tool_result stays in the prompt of every later turn. With prompt caching each re-send bills as a cache read -- cheap per token, but paid per turn for the rest of the session. A large file read whole early in a long session is re-sent hundreds of times, when `grep -n` plus a ranged Read would have carried the few lines needed.
+- It is a baseline for judging read-routing changes against, which is why it is one summary at `info` severity rather than a finding per Read. Reading a file whole is often correct.
+- The threshold: across 739 whole-file Reads in a real corpus of 149 transcripts, Read output (line-number prefixes included) ran at a median 13.5 tokens per line, so 4,000 tokens is roughly 300 lines. An implementation counting with a chars/4 estimate instead measures 12.2 tokens per line on the same corpus, crossing the threshold at roughly 330 lines.
+- Turn counting matters: counting records instead of message ids roughly doubles every carry (one measured transcript held 1,338 assistant records for 640 ids), and ignoring compaction overstates any session that compacted (25 of 150 transcripts in the same corpus did).
+- The carry is an estimate. Tokens come from a proxy tokenizer -- cl100k where the implementation can load one, a chars/4 approximation otherwise, which is what the reference implementation's published bundle uses -- a result's first re-send is a cache write rather than a read, and a Read copied into a continued session is counted with the smaller of its two carries. Figures are not converted to cost, since token prices vary by model and change.
+- Remediation: find the region with `grep -n` (or the Grep tool) and Read it with `offset`/`limit`, or delegate the whole-file question to a subagent, whose reads stay in its own context.
+
+---
+
 ## 3. Rule Catalog (machine-readable)
 
 A machine-readable JSON catalog of all rules is available at [`agent-session-lint-rules.json`](./agent-session-lint-rules.json). It conforms to the shared catalog schema ([`schemas/ctxlint-catalog.schema.json`](./schemas/ctxlint-catalog.schema.json)) used by all four pillars: each rule entry carries `id`, `category`, `severity`, `description`, `trigger`, `message`, `fixable`, and `stability`, plus rule-specific extras (e.g. `canonicalFiles` on `session/diverged-file`).
@@ -483,6 +514,7 @@ Catalog rule IDs use the pillar-stable `session/<slug>` form -- these are the cr
 | `session/unverified-gate-claimed-clean` | `session-unverified-gate-claimed-clean/unverified-gate-claimed-clean` |
 | `session/default-branch-accumulation` | `session-default-branch-accumulation/default-branch-accumulation` |
 | `session/unresolvable-sha` | `session-unresolvable-sha/unresolvable-sha` |
+| `session/large-read` | `session-large-read/large-read` |
 
 ### Data sources: history vs. transcript
 

package/README.md

@@ -4,6 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/ctxlint)](https://github.com/YawLabs/ctxlint/stargazers)
 [![MCP Compliance](https://raw.githubusercontent.com/YawLabs/ctxlint/main/compliance-badge.svg)](https://github.com/YawLabs/mcp-compliance)
+[![Follow @TokenLimitNews on X](https://img.shields.io/badge/follow-%40TokenLimitNews-000000?logo=x&logoColor=white)](https://x.com/TokenLimitNews)
 
 **Lint your AI agent context files, MCP server configs, and session data against your actual codebase.** Context linting + MCP config linting + session auditing. 16 AI tools, 8 MCP clients, cross-project consistency, auto-fix. Works as a CLI, CI step, pre-commit hook, or MCP server.
 
@@ -89,6 +90,11 @@ Useful if you want `ctxlint` available in every project without per-project setu
 | **Duplicate memory**  | Near-duplicate memories across projects (>60% content overlap)                                                                                                                                                                                                                   |
 | **Loop detection**    | Agent stuck in loops — repeated commands or cyclic patterns in session history                                                                                                                                                                                                   |
 | **Memory overflow**   | `MEMORY.md` past Claude Code's 200-line / 25KB session-load cap — entries beyond it are invisible to the agent                                                                                                                                                                   |
+| **Shared temp path**  | A fixed temp path (e.g. `/tmp/pkg.bak`) the agent writes and later reads back — any concurrent session can overwrite it in between                                                                                                                                               |
+| **Unverified gate**   | A lint/typecheck/test/build run that errored or printed nothing, followed by agent prose claiming it passed                                                                                                                                                                      |
+| **Default-branch edits** | 10+ files edited on `main`/`master` with no intervening commit or branch-away                                                                                                                                                                                                 |
+| **Unresolvable SHA**  | A memory cites a commit SHA that does not resolve in this repository                                                                                                                                                                                                             |
+| **Large reads**       | Whole-file Reads of 4,000+ tokens, with an estimate of the tokens they re-send as cached context on later turns (an info-level baseline)                                                                                                                                         |
 
 ## Supported Context Files
 
@@ -201,6 +207,8 @@ Session checks are **opt-in** because they access files outside the project dire
 | Claude Code | `~/.claude/history.jsonl` | `~/.claude/projects/*/memory/*.md` |
 | Codex CLI   | `~/.codex/history.jsonl`  | —                                  |
 
+Checks whose signal is what the agent did (commands run, files written or read) also read the current project's Claude Code session transcripts, `~/.claude/projects/<encoded-project>/*.jsonl`, bounded to the 5 most recent.
+
 ### What session checks catch
 
 | Check                     | What it finds                                                                                                                                    |
@@ -212,6 +220,11 @@ Session checks are **opt-in** because they access files outside the project dire
 | **Duplicate memory**      | Near-duplicate memory entries across projects (>60% overlap)                                                                                     |
 | **Loop detection**        | Agent stuck in a loop — 3+ consecutive identical commands, or cyclic A,B,A,B patterns                                                            |
 | **Memory index overflow** | `MEMORY.md` exceeds Claude Code's documented 200-line / 25KB session-load cap, so entries past the cap are invisible to the agent                |
+| **Shared temp path**      | A fixed temp path (e.g. `/tmp/pkg.bak`) the agent writes and later reads back — any concurrent session can overwrite it in between               |
+| **Unverified gate**       | A lint/typecheck/test/build run that errored or printed nothing, followed by agent prose claiming it passed                                      |
+| **Default-branch edits**  | 10+ files edited on `main`/`master` with no intervening commit or branch-away                                                                    |
+| **Unresolvable SHA**      | A memory cites a commit SHA that does not resolve in this repository                                                                             |
+| **Large reads**           | Whole-file Reads of 4,000+ tokens, with an estimate of the tokens they re-send as cached context on later turns (an info-level baseline)         |
 
 ### Session Linting Specification
 
@@ -221,7 +234,7 @@ Session checks are **opt-in** because they access files outside the project dire
 ## Example Output
 
 ```
-ctxlint v0.9.10
+ctxlint v0.25.0
 
 Scanning /Users/you/my-app...
 
@@ -282,7 +295,7 @@ Commands:
   init                 Set up a git pre-commit hook
 ```
 
-**Available checks:** `paths`, `commands`, `staleness`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `ci-coverage`, `ci-secrets`, `content-secrets`, `hook-coverage`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`, `session-missing-secret`, `session-diverged-file`, `session-missing-workflow`, `session-stale-memory`, `session-duplicate-memory`, `session-loop-detection`, `session-memory-index-overflow`, `skill-frontmatter`, `skill-broken-ref`, `skill-trigger-collision`, `skill-orphaned`, `skill-dead-tool-restriction`
+**Available checks:** `paths`, `commands`, `staleness`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `ci-coverage`, `ci-secrets`, `content-secrets`, `hook-coverage`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`, `session-missing-secret`, `session-diverged-file`, `session-missing-workflow`, `session-stale-memory`, `session-duplicate-memory`, `session-loop-detection`, `session-memory-index-overflow`, `session-shared-temp-path`, `session-unverified-gate-claimed-clean`, `session-default-branch-accumulation`, `session-unresolvable-sha`, `session-large-read`, `skill-frontmatter`, `skill-broken-ref`, `skill-trigger-collision`, `skill-orphaned`, `skill-dead-tool-restriction`
 
 Passing any `mcp-*` check name implies `--mcp`. Passing any `session-*` check name implies `--session`. Passing any `skill-*` check name implies `--skills`.
 
@@ -364,7 +377,7 @@ Add to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yawlabs/ctxlint
-    rev: v0.9.10
+    rev: v0.25.0
     hooks:
       - id: ctxlint
 ```
@@ -519,7 +532,7 @@ ctxlint is the reference implementation of four open specifications for linting
 | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 41 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 16 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.          |
 | **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 29 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency.        |
-| **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 12 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                       |
+| **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 13 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                       |
 | **[Agent Skill Linting Spec](./AGENT_SKILL_LINT_SPEC.md)**     | 5 rules for auditing Claude Code skill (`SKILL.md`) and agent (`.md`) definitions under `~/.claude`. Covers frontmatter presence, broken refs, trigger-phrase collisions, orphaned skills, and dead tool restrictions. (v1, experimental) |
 
 All specs include machine-readable rule catalogs for programmatic consumption:

package/agent-session-lint-rules.json

@@ -144,6 +144,16 @@
       "message": "cited commit {sha} does not resolve in this repository",
       "fixable": false,
       "stability": "experimental"
+    },
+    {
+      "id": "session/large-read",
+      "category": "session",
+      "severity": "info",
+      "description": "Measures session context spent on whole-file Reads of large files. Each result is re-sent as prompt context (cache reads) on every later turn of its session; the finding is a baseline for judging read-routing changes, reported as one summary per project.",
+      "trigger": "One or more whole-file Read calls (no offset, limit or pages) in the current project's transcripts whose result is 4,000 tokens or more. Carry is each result's tokens times the later turns of its session that re-sent it, up to the session's end or its next /compact boundary; a turn is a distinct assistant message id.",
+      "message": "{count} whole-file Reads of 4,000+ tokens ({tokens} tokens); est. {carry} tokens of cache-read carry on later turns",
+      "fixable": false,
+      "stability": "experimental"
     }
   ],
   "dataSources": [

package/dist/index.js

@@ -27551,6 +27551,20 @@ import { readdir as readdir3 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
 import { join as join9 } from "node:path";
 import { createInterface as createInterface2 } from "node:readline";
+function emptyRead() {
+  return {
+    events: [],
+    filesRead: 0,
+    truncated: false,
+    sessionTurns: /* @__PURE__ */ new Map(),
+    sessionCompactions: /* @__PURE__ */ new Map()
+  };
+}
+function turnsCarried(read, ev) {
+  const total = read.sessionTurns.get(ev.sessionId) ?? ev.turn;
+  const boundary = read.sessionCompactions.get(ev.sessionId)?.find((b2) => b2 >= ev.turn);
+  return Math.max(0, (boundary ?? total) - ev.turn);
+}
 function asString(v2) {
   return typeof v2 === "string" ? v2 : "";
 }
@@ -27571,14 +27585,17 @@ function readProjectTranscript(project, home2 = resolveHome()) {
   }
   return hit;
 }
+function clearTranscriptCache() {
+  cache.clear();
+}
 function candidateDirs(project, home2) {
   const root = join9(home2, ".claude", "projects");
   return projectDirCandidates(project).map((n7) => join9(root, n7)).filter((d) => existsSync5(d));
 }
 async function readUncached(project, home2) {
-  if (!home2 || !project) return EMPTY;
+  if (!home2 || !project) return emptyRead();
   const dirs = candidateDirs(project, home2);
-  if (dirs.length === 0) return EMPTY;
+  if (dirs.length === 0) return emptyRead();
   const names = [];
   for (const dir of dirs) {
     for (const name of await readdir3(dir).catch(() => [])) {
@@ -27595,8 +27612,7 @@ async function readUncached(project, home2) {
   }).filter((f) => f !== null).sort((a, b2) => b2.mtime - a.mtime);
   let truncated = files.length > MAX_TRANSCRIPTS;
   const selected = files.slice(0, MAX_TRANSCRIPTS);
-  const events = [];
-  const pending = /* @__PURE__ */ new Map();
+  const st2 = { events: [], pending: /* @__PURE__ */ new Map(), sessions: /* @__PURE__ */ new Map(), anonymous: 0 };
   let lines = 0;
   for (const { p: p2 } of selected) {
     if (lines >= MAX_LINES2) {
@@ -27621,21 +27637,75 @@ async function readUncached(project, home2) {
         } catch {
           continue;
         }
-        collect(rec, events, pending);
+        collect(rec, st2);
       }
     } catch {
     } finally {
       rl.close();
     }
   }
-  return { events, filesRead: selected.length, truncated };
+  const sessionTurns = /* @__PURE__ */ new Map();
+  const sessionCompactions = /* @__PURE__ */ new Map();
+  for (const [id, s] of st2.sessions) {
+    sessionTurns.set(id, s.ordinals.size);
+    if (s.compactions.length > 0) {
+      sessionCompactions.set(
+        id,
+        [...s.compactions].sort((a, b2) => a - b2)
+      );
+    }
+  }
+  return {
+    events: st2.events,
+    filesRead: selected.length,
+    truncated,
+    sessionTurns,
+    sessionCompactions
+  };
+}
+function sessionState(st2, sessionId) {
+  let s = st2.sessions.get(sessionId);
+  if (!s) {
+    s = { ordinals: /* @__PURE__ */ new Map(), compactions: [] };
+    st2.sessions.set(sessionId, s);
+  }
+  return s;
 }
-function collect(rec, events, pending) {
+function turnOf(rec, message, st2, sessionId) {
+  const s = sessionState(st2, sessionId);
+  if (message?.model === "<synthetic>" || rec.isSidechain === true) return s.ordinals.size;
+  const key = asString(message?.id) || asString(rec.requestId) || `#anonymous:${++st2.anonymous}`;
+  let ordinal = s.ordinals.get(key);
+  if (ordinal === void 0) {
+    ordinal = s.ordinals.size + 1;
+    s.ordinals.set(key, ordinal);
+  }
+  return ordinal;
+}
+function isSet(v2) {
+  return v2 !== void 0 && v2 !== null && v2 !== "";
+}
+function readResultLines(rec, path21) {
+  const result = rec.toolUseResult;
+  if (!result || typeof result !== "object") return void 0;
+  const file2 = result.file;
+  if (!file2 || typeof file2 !== "object") return void 0;
+  const { filePath, numLines } = file2;
+  if (filePath !== path21) return void 0;
+  return typeof numLines === "number" ? numLines : void 0;
+}
+function collect(rec, st2) {
+  const sessionId = asString(rec.sessionId) || asString(rec.session_id);
+  if (rec.type === "system" && rec.subtype === "compact_boundary") {
+    const s = sessionState(st2, sessionId);
+    s.compactions.push(s.ordinals.size);
+    return;
+  }
   const message = rec.message;
+  const turn = rec.type === "assistant" ? turnOf(rec, message, st2, sessionId) : st2.sessions.get(sessionId)?.ordinals.size ?? 0;
   const content = message?.content;
   if (!Array.isArray(content)) return;
   const timestamp = Date.parse(asString(rec.timestamp)) || 0;
-  const sessionId = asString(rec.sessionId) || asString(rec.session_id);
   const gitBranch = asString(rec.gitBranch) || void 0;
   for (const raw of content) {
     if (!raw || typeof raw !== "object") continue;
@@ -27644,7 +27714,15 @@ function collect(rec, events, pending) {
     if (type === "text" && rec.type === "assistant") {
       const text = asString(block.text);
       if (text) {
-        events.push({ kind: "assistant-text", text, tool: "", gitBranch, timestamp, sessionId });
+        st2.events.push({
+          kind: "assistant-text",
+          text,
+          tool: "",
+          gitBranch,
+          turn,
+          timestamp,
+          sessionId
+        });
       }
       continue;
     }
@@ -27653,49 +27731,76 @@ function collect(rec, events, pending) {
       const input = block.input ?? {};
       const cmdField = COMMAND_TOOLS[tool];
       const writeField = WRITE_TOOLS[tool];
+      const readField = READ_TOOLS[tool];
       let ev = null;
       if (cmdField) {
         const text = asString(input[cmdField]);
-        if (text) ev = { kind: "command", text, tool, gitBranch, timestamp, sessionId };
+        if (text) ev = { kind: "command", text, tool, gitBranch, turn, timestamp, sessionId };
       } else if (writeField) {
         const text = asString(input[writeField]);
-        if (text) ev = { kind: "file-write", text, tool, gitBranch, timestamp, sessionId };
+        if (text) ev = { kind: "file-write", text, tool, gitBranch, turn, timestamp, sessionId };
+      } else if (readField) {
+        const text = asString(input[readField]);
+        if (text) {
+          ev = {
+            kind: "file-read",
+            text,
+            tool,
+            partial: PARTIAL_READ_FIELDS.some((f) => isSet(input[f])),
+            gitBranch,
+            turn,
+            timestamp,
+            sessionId
+          };
+        }
       }
       if (ev) {
-        events.push(ev);
         const id = asString(block.id);
-        if (id) pending.set(id, ev);
+        if (id) ev.toolUseId = id;
+        st2.events.push(ev);
+        if (id) st2.pending.set(id, ev);
       }
       continue;
     }
     if (type === "tool_result") {
       const id = asString(block.tool_use_id);
-      const ev = id ? pending.get(id) : void 0;
+      const ev = id ? st2.pending.get(id) : void 0;
       if (!ev) continue;
-      pending.delete(id);
+      st2.pending.delete(id);
+      const out = resultText(block.content);
       ev.isError = block.is_error === true;
-      ev.emptyOutput = resultText(block.content).trim().length === 0;
+      ev.emptyOutput = out.trim().length === 0;
+      ev.outputChars = out.length;
+      if (ev.kind === "file-read") {
+        ev.outputTokens = countTokens(out);
+        const lineCount = readResultLines(rec, ev.text);
+        if (lineCount !== void 0) ev.outputLines = lineCount;
+      }
     }
   }
 }
-var WRITE_TOOLS, COMMAND_TOOLS, MAX_TRANSCRIPTS, MAX_LINES2, EMPTY, cache;
+var WRITE_TOOLS, READ_TOOLS, PARTIAL_READ_FIELDS, COMMAND_TOOLS, MAX_TRANSCRIPTS, MAX_LINES2, cache;
 var init_transcript = __esm({
   "src/core/transcript.ts"() {
     "use strict";
     init_define_WEB_FIRST_SEGMENTS();
+    init_tokens();
     init_session_parser();
     WRITE_TOOLS = {
       Write: "file_path",
       Edit: "file_path",
       NotebookEdit: "notebook_path"
     };
+    READ_TOOLS = {
+      Read: "file_path"
+    };
+    PARTIAL_READ_FIELDS = ["offset", "limit", "pages"];
     COMMAND_TOOLS = {
       Bash: "command",
       PowerShell: "command"
     };
     MAX_TRANSCRIPTS = 5;
     MAX_LINES2 = 2e5;
-    EMPTY = { events: [], filesRead: 0, truncated: false };
     cache = /* @__PURE__ */ new Map();
   }
 });
@@ -27833,7 +27938,7 @@ function isUnverified(ev) {
 async function checkUnverifiedGateClaimedClean(ctx) {
   const { events } = await readProjectTranscript(ctx.currentProject);
   if (events.length === 0) return [];
-  const ordered = [...events].sort((a, b2) => a.timestamp - b2.timestamp);
+  const ordered = events.filter((e) => e.kind !== "file-read").sort((a, b2) => a.timestamp - b2.timestamp);
   const issues = [];
   const reported = /* @__PURE__ */ new Set();
   for (let i2 = 0; i2 < ordered.length; i2++) {
@@ -27914,7 +28019,7 @@ function isBranchAway(cmd) {
 async function checkDefaultBranchAccumulation(ctx) {
   const { events } = await readProjectTranscript(ctx.currentProject);
   if (events.length === 0) return [];
-  const ordered = [...events].sort((a, b2) => a.timestamp - b2.timestamp);
+  const ordered = events.filter((e) => e.kind !== "file-read").sort((a, b2) => a.timestamp - b2.timestamp);
   const pending = /* @__PURE__ */ new Set();
   let branch = "";
   let firstWrite = "";
@@ -28058,6 +28163,93 @@ var init_unresolvable_sha = __esm({
   }
 });
 
+// src/core/checks/session/large-read.ts
+import { isAbsolute as isAbsolute6, relative as relative6 } from "node:path";
+function qualifies(ev) {
+  if (ev.kind !== "file-read" || ev.partial || ev.isError) return false;
+  return (ev.outputTokens ?? 0) >= LARGE_READ_TOKENS;
+}
+function fmt(n7) {
+  return n7.toLocaleString("en-US");
+}
+function displayPath(path21, project) {
+  const rel = relative6(project, path21);
+  if (rel && !rel.startsWith("..") && !isAbsolute6(rel)) return rel.replace(/\\/g, "/");
+  return path21;
+}
+function fileKey(path21) {
+  const slashed = path21.replace(/\\/g, "/");
+  return process.platform === "win32" ? slashed.toLowerCase() : slashed;
+}
+async function checkLargeRead(ctx) {
+  const read = await readProjectTranscript(ctx.currentProject);
+  const byCall = /* @__PURE__ */ new Map();
+  const unkeyed = [];
+  for (const ev of read.events) {
+    if (!qualifies(ev)) continue;
+    const hit = { ev, tokens: ev.outputTokens ?? 0, carried: turnsCarried(read, ev) };
+    if (!ev.toolUseId) {
+      unkeyed.push(hit);
+      continue;
+    }
+    const prev = byCall.get(ev.toolUseId);
+    if (!prev || hit.carried < prev.carried) byCall.set(ev.toolUseId, hit);
+  }
+  const hits = [...byCall.values(), ...unkeyed];
+  if (hits.length === 0) return [];
+  let totalTokens = 0;
+  let carry = 0;
+  const files = /* @__PURE__ */ new Map();
+  for (const { ev, tokens, carried } of hits) {
+    totalTokens += tokens;
+    carry += tokens * carried;
+    const key = fileKey(ev.text);
+    const file2 = files.get(key) ?? { path: ev.text, reads: 0, tokens: 0 };
+    file2.reads += 1;
+    file2.tokens += tokens;
+    if (ev.outputLines !== void 0) file2.lines = Math.max(file2.lines ?? 0, ev.outputLines);
+    files.set(key, file2);
+  }
+  const top = [...files.values()].sort((a, b2) => b2.tokens - a.tokens || a.path.localeCompare(b2.path)).slice(0, TOP_FILES);
+  const topLines = top.map((f) => {
+    const reads = `${f.reads} read${f.reads === 1 ? "" : "s"}`;
+    const lines = f.lines !== void 0 ? `, ${fmt(f.lines)} line${f.lines === 1 ? "" : "s"}` : "";
+    return `  ${displayPath(f.path, ctx.currentProject)} -- ${reads}, ${fmt(f.tokens)} tokens${lines}`;
+  });
+  const count = hits.length;
+  const detail = [
+    `Largest files by tokens read whole:`,
+    ...topLines,
+    `Carry = each Read's result tokens x the later turns of its session that re-sent it (to the session's end or its next /compact). An estimate: tokens are counted with a proxy tokenizer, and a result's first re-send is a cache write rather than a read.`
+  ];
+  if (read.truncated) {
+    detail.push(
+      `Transcript read was capped (${read.filesRead} most recent transcripts, bounded line count): these figures cover only what was read, so the real totals are higher.`
+    );
+  }
+  return [
+    {
+      severity: "info",
+      check: "session-large-read",
+      ruleId: "session-large-read/large-read",
+      line: 0,
+      message: `${count} whole-file Read${count === 1 ? "" : "s"} of ${fmt(LARGE_READ_TOKENS)}+ tokens (${fmt(totalTokens)} tokens); est. ${fmt(carry)} tokens of cache-read carry on later turns`,
+      detail: detail.join("\n"),
+      suggestion: "Before reading a large file whole, find the part you need with `grep -n` (or the Grep tool) and Read just that range with `offset`/`limit`. For a question that needs the whole file, delegate it to a subagent: its reads stay in its own context and only the answer comes back."
+    }
+  ];
+}
+var LARGE_READ_TOKENS, TOP_FILES;
+var init_large_read = __esm({
+  "src/core/checks/session/large-read.ts"() {
+    "use strict";
+    init_define_WEB_FIRST_SEGMENTS();
+    init_transcript();
+    LARGE_READ_TOKENS = 4e3;
+    TOP_FILES = 3;
+  }
+});
+
 // src/core/checks/ci-coverage.ts
 import { readdir as readdir4, readFile as readFile4 } from "node:fs/promises";
 import { join as join10 } from "node:path";
@@ -29108,7 +29300,7 @@ import { readFileSync as readFileSync8 } from "node:fs";
 import { resolve as resolve15, dirname as dirname7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function loadVersion() {
-  if (true) return "0.24.1";
+  if (true) return "0.25.0";
   try {
     const __dir = dirname7(fileURLToPath2(import.meta.url));
     const pkgPath = resolve15(__dir, "../package.json");
@@ -29357,6 +29549,8 @@ async function runAudit(projectRoot, activeChecks, options = {}) {
         sessionPromises.push(checkDefaultBranchAccumulation(sessionCtx));
       if (sessionChecksToRun.includes("session-unresolvable-sha"))
         sessionPromises.push(checkUnresolvableSha(sessionCtx));
+      if (sessionChecksToRun.includes("session-large-read"))
+        sessionPromises.push(checkLargeRead(sessionCtx));
       const sessionResults = await Promise.all(sessionPromises);
       const sessionIssues = sessionResults.flat();
       fileResults.push({
@@ -29562,6 +29756,7 @@ var init_audit = __esm({
     init_unverified_gate_claimed_clean();
     init_default_branch_accumulation();
     init_unresolvable_sha();
+    init_large_read();
     init_ci_coverage();
     init_ci_secrets();
     init_content_secrets();
@@ -29607,7 +29802,8 @@ var init_audit = __esm({
       "session-shared-temp-path",
       "session-unverified-gate-claimed-clean",
       "session-default-branch-accumulation",
-      "session-unresolvable-sha"
+      "session-unresolvable-sha",
+      "session-large-read"
     ];
     ALL_SKILL_CHECKS = [
       "skill-frontmatter",
@@ -56870,49 +57066,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative8, options, skipNormalization) {
+    function resolveComponent(base, relative9, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse5(serialize(base, options), options);
-        relative8 = parse5(serialize(relative8, options), options);
+        relative9 = parse5(serialize(relative9, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative8.scheme) {
-        target.scheme = relative8.scheme;
-        target.userinfo = relative8.userinfo;
-        target.host = relative8.host;
-        target.port = relative8.port;
-        target.path = removeDotSegments(relative8.path || "");
-        target.query = relative8.query;
+      if (!options.tolerant && relative9.scheme) {
+        target.scheme = relative9.scheme;
+        target.userinfo = relative9.userinfo;
+        target.host = relative9.host;
+        target.port = relative9.port;
+        target.path = removeDotSegments(relative9.path || "");
+        target.query = relative9.query;
       } else {
-        if (relative8.userinfo !== void 0 || relative8.host !== void 0 || relative8.port !== void 0) {
-          target.userinfo = relative8.userinfo;
-          target.host = relative8.host;
-          target.port = relative8.port;
-          target.path = removeDotSegments(relative8.path || "");
-          target.query = relative8.query;
+        if (relative9.userinfo !== void 0 || relative9.host !== void 0 || relative9.port !== void 0) {
+          target.userinfo = relative9.userinfo;
+          target.host = relative9.host;
+          target.port = relative9.port;
+          target.path = removeDotSegments(relative9.path || "");
+          target.query = relative9.query;
         } else {
-          if (!relative8.path) {
+          if (!relative9.path) {
             target.path = base.path;
-            if (relative8.query !== void 0) {
-              target.query = relative8.query;
+            if (relative9.query !== void 0) {
+              target.query = relative9.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative8.path[0] === "/") {
-              target.path = removeDotSegments(relative8.path);
+            if (relative9.path[0] === "/") {
+              target.path = removeDotSegments(relative9.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative8.path;
+                target.path = "/" + relative9.path;
               } else if (!base.path) {
-                target.path = relative8.path;
+                target.path = relative9.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative8.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative9.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative8.query;
+            target.query = relative9.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -56920,7 +57116,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative8.fragment;
+      target.fragment = relative9.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -59407,11 +59603,11 @@ var require_format = __commonJS({
           }
           function getFormat(fmtDef) {
             const code = fmtDef instanceof RegExp ? (0, codegen_1.regexpCode)(fmtDef) : opts.code.formats ? (0, codegen_1._)`${opts.code.formats}${(0, codegen_1.getProperty)(schema)}` : void 0;
-            const fmt = gen.scopeValue("formats", { key: schema, ref: fmtDef, code });
+            const fmt2 = gen.scopeValue("formats", { key: schema, ref: fmtDef, code });
             if (typeof fmtDef == "object" && !(fmtDef instanceof RegExp)) {
-              return [fmtDef.type || "string", fmtDef.validate, (0, codegen_1._)`${fmt}.validate`];
+              return [fmtDef.type || "string", fmtDef.validate, (0, codegen_1._)`${fmt2}.validate`];
             }
-            return ["string", fmtDef, fmt];
+            return ["string", fmtDef, fmt2];
           }
           function validCondition() {
             if (typeof formatDef == "object" && !(formatDef instanceof RegExp) && formatDef.async) {
@@ -60081,8 +60277,8 @@ var require_limit = __commonJS({
             ref: self2.formats,
             code: opts.code.formats
           });
-          const fmt = gen.const("fmt", (0, codegen_1._)`${fmts}[${fCxt.schemaCode}]`);
-          cxt.fail$data((0, codegen_1.or)((0, codegen_1._)`typeof ${fmt} != "object"`, (0, codegen_1._)`${fmt} instanceof RegExp`, (0, codegen_1._)`typeof ${fmt}.compare != "function"`, compareCode(fmt)));
+          const fmt2 = gen.const("fmt", (0, codegen_1._)`${fmts}[${fCxt.schemaCode}]`);
+          cxt.fail$data((0, codegen_1.or)((0, codegen_1._)`typeof ${fmt2} != "object"`, (0, codegen_1._)`${fmt2} instanceof RegExp`, (0, codegen_1._)`typeof ${fmt2}.compare != "function"`, compareCode(fmt2)));
         }
         function validateFormat() {
           const format3 = fCxt.schema;
@@ -60092,15 +60288,15 @@ var require_limit = __commonJS({
           if (typeof fmtDef != "object" || fmtDef instanceof RegExp || typeof fmtDef.compare != "function") {
             throw new Error(`"${keyword}": format "${format3}" does not define "compare" function`);
           }
-          const fmt = gen.scopeValue("formats", {
+          const fmt2 = gen.scopeValue("formats", {
             key: format3,
             ref: fmtDef,
             code: opts.code.formats ? (0, codegen_1._)`${opts.code.formats}${(0, codegen_1.getProperty)(format3)}` : void 0
           });
-          cxt.fail$data(compareCode(fmt));
+          cxt.fail$data(compareCode(fmt2));
         }
-        function compareCode(fmt) {
-          return (0, codegen_1._)`${fmt}.compare(${data}, ${schemaCode}) ${KWDs[keyword].fail} 0`;
+        function compareCode(fmt2) {
+          return (0, codegen_1._)`${fmt2}.compare(${data}, ${schemaCode}) ${KWDs[keyword].fail} 0`;
         }
       },
       dependencies: ["format"]
@@ -62825,6 +63021,7 @@ var init_server4 = __esm({
     init_tokens();
     init_git();
     init_paths();
+    init_transcript();
     init_version2();
     contextCheckEnum = external_exports.enum(ALL_CHECKS);
     mcpCheckEnum = external_exports.enum(ALL_MCP_CHECKS);
@@ -63077,7 +63274,7 @@ var init_server4 = __esm({
     );
     server.tool(
       "ctxlint_session_audit",
-      "Audit AI agent session data for cross-project consistency. Checks for missing GitHub secrets, diverged config files, missing workflows, stale memory entries, and duplicate memories across sibling repositories.",
+      "Audit AI agent session data for cross-project consistency and session hazards. Checks for missing GitHub secrets, diverged config files and missing workflows across sibling repositories; stale, duplicate or overflowing memory entries; command loops; and, from Claude Code transcripts, shared temp paths, gates claimed clean after failing, edits piling up on the default branch, unresolvable commit SHAs in memory, and large whole-file Reads re-sent as context on later turns.",
       {
         projectPath: external_exports.string().optional().describe("Path to the project root. Defaults to current working directory."),
         checks: external_exports.array(sessionCheckEnum).optional().describe("Specific session checks to run (default: all session-* checks).")
@@ -63110,6 +63307,7 @@ var init_server4 = __esm({
           resetGit();
           resetPathsCache();
           resetPackageJsonCache();
+          clearTranscriptCache();
         }
       }
     );
@@ -70128,6 +70326,13 @@ function buildRuleDescriptors() {
       },
       helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
     },
+    {
+      id: "ctxlint/session-large-read",
+      shortDescription: {
+        text: "Whole-file Reads of large files re-sent as context on every later turn"
+      },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
     {
       id: "ctxlint/skill-frontmatter",
       shortDescription: { text: "Skill/agent definition missing required frontmatter" },
@@ -70362,6 +70567,7 @@ Fixed ${applied.totalFixes} issue${applied.totalFixes !== 1 ? "s" : ""} in ${app
       resetGit();
       resetPathsCache();
       resetPackageJsonCache();
+      clearTranscriptCache();
     }
     if (opts.watch) {
       const chalk2 = (await Promise.resolve().then(() => (init_source(), source_exports))).default;
@@ -70458,6 +70664,7 @@ Fixed ${applied.totalFixes} issue${applied.totalFixes !== 1 ? "s" : ""} in ${app
             resetPathsCache();
             resetPackageJsonCache();
             clearFileCache();
+            clearTranscriptCache();
           }
           console.log(chalk2.dim("\nWatching for changes... (Ctrl+C to stop)\n"));
         }, 300);
@@ -70651,6 +70858,7 @@ var init_cli = __esm({
     init_ora();
     init_paths();
     init_cache();
+    init_transcript();
     init_reporter();
     init_fixer();
     init_tokens();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "mcpName": "io.github.YawLabs/ctxlint",
   "description": "Lint your AI agent context files, MCP server configs, and session data against your actual codebase",
   "bin": {