token-pilot 0.44.0 → 0.45.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot — save 60-90% tokens when AI reads code",
-    "version": "0.44.0"
+    "version": "0.45.0"
   },
   "plugins": [
     {
       "name": "token-pilot",
       "source": "./",
       "description": "Reduces token consumption by 60-90% via AST-aware lazy file reading, structural symbol navigation, and cross-session tool-usage analytics. 23 MCP tools + 25 subagents + budget watchdog hooks.",
-      "version": "0.44.0",
+      "version": "0.45.0",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Saves 60-90% tokens on AI code reading. AST-aware lazy reads, symbol navigation, find_usages, structural git diff/log, edit-safety guard, Task-routing matcher, cross-session telemetry (errors + diagnostics), 25 tp-* subagents tiered to haiku/sonnet/opus with budget watchdog.",
   "author": {
     "name": "Digital-Threads",

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to Token Pilot will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.45.0] - unreleased
+
+Accumulating; not yet published. `0.44.0` is the published/consumed version —
+the items below live only on `master` until `0.45.0` ships.
+
+### Changed — default tool profile is now `full` (adoption fix)
+
+The advice surface (rules, SessionStart/PostToolUse banners, the pre-edit hook)
+references `read_for_edit`, batch reads, `test_summary` etc. unconditionally,
+but the old default (`edit`) and any trimmed profile hide some of those — so the
+model calls a hidden tool, hits `No such tool available`, and falls back to raw
+`Read`/`Bash`. Those dead round-trips cost far more than the ~2k tokens the trim
+saved. Default is now `full` (advertise everything); trimmed profiles stay
+opt-in via `TOKEN_PILOT_PROFILE=nav|edit|minimal`. When a trimmed profile is
+active the SessionStart banner now prepends a caveat naming what's hidden.
+
+The profile **recommender** no longer pushes a trim: it used to suggest
+`TOKEN_PILOT_PROFILE=nav` for read-heavy usage and print an "apply to
+`.mcp.json`" snippet — users applied it, then the next edit session hit the
+trimmed-away `read_for_edit` / `read_range` / batch reads. It now always
+recommends `full`. And `token-pilot doctor` loudly flags an explicit trimmed
+profile, names the hidden tools, and tells you to remove it.
+
+### Added — tool failures are logged (no more silent breakage)
+
+`createServer`'s tool dispatch now writes handler exceptions / validation errors
+(and unknown-tool names that reach the server) to `~/.token-pilot/hook-errors.jsonl`,
+visible via `token-pilot errors`. Previously tp breakage vanished while telemetry
+reported "all ok". (`No such tool available` is rejected at the Claude Code layer
+before reaching us and stays invisible by design — the full default removes its
+main source.)
+
+### Fixed — `read_section` is docs-only
+
+Clarified that `read_section` reads Markdown/YAML/JSON/CSV by heading/key/row —
+**not** code by line/symbol (use `read_range` / `read_symbol`). Removed its
+misleading placement under "Batch variants" in the SessionStart banner.
+
+### Added — bounded-read leak closed (gate on read span, not bound presence)
+
+`PreToolUse:Read` passed *any* `offset`/`limit` Read straight through, so
+`Read(file, limit=2000)` (Claude Code's default page) pulled a whole big file
+hook-free **and** un-counted in the adaptive burn signal — the #1 invisible
+leak. The hook now measures the span a Read actually pulls
+(`effectiveReadSpanLines`) and applies the same deny threshold: a default-page
+or offset-no-limit read of a big file denies with a structural summary, while a
+genuinely narrow slice (`limit < threshold`) still passes. Cost estimates are
+scaled by the span so bounded denies don't over-report savings.
+
+### Added — `parent_session_id` capture in SubagentStop (groundwork)
+
+A subagent's MCP server runs with `CLAUDE_CODE_SESSION_ID` = the *agent*
+session, so subagent savings get tagged with that id and the statusline's
+main-session badge drops them (savings look flat when subagents do the reading).
+SubagentStop now captures `parent_session_id` (which CC ships in the payload),
+enabling a future child→parent rollup in the badge. Additive/no-op when absent.
+
+### Security — `vitest` 3.2.4 → 3.2.6
+
+Patches GHSA-5xrq-8626-4rwp (Vitest UI arbitrary file read/exec, critical).
+Dev-only dependency; shipped runtime deps unchanged. The other 32 Dependabot
+alerts were already resolved (installed transitive versions at/above the
+patched version) and auto-close on re-scan.
+
+### Docs
+
+Fable-5 economic positioning in the README — savings are in tokens, value is in
+tokens × price; keep the premium thread lean.
+
 ## [0.44.0] - 2026-06-10
 
 ### Changed — adaptive deny threshold ON by default

package/README.md

@@ -2,6 +2,8 @@
 
 **Token-efficient AI coding, enforced.** Cuts context consumption in AI coding assistants by up to **90%** without changing the way you work.
 
+> **Why it matters more now:** as frontier models move up in price — Claude's Fable 5 is the most capable (and most expensive-per-token) tier yet — the tokens you *don't* spend reading code are worth more, not less. The savings are in tokens; the value is in tokens × price. Token Pilot keeps the expensive main thread lean so the premium model spends its budget on reasoning, not on re-reading files.
+
 Three layers, each useful on its own, stronger together:
 
 1. **MCP tools** — structural reads (`smart_read`, `read_symbol`, `read_for_edit`, …). Ask for an outline or load one function by name instead of the whole file.

package/agents/tp-api-surface-tracker.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-audit-scanner.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-commit-writer.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-context-engineer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-dead-code-finder.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-debugger.md

@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-dep-health.md

@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-doc-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-history-explorer.md

@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-impact-analyzer.md

@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-incident-timeline.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-incremental-builder.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-migration-scout.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-onboard.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-performance-profiler.md

@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-pr-reviewer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-refactor-planner.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-review-impact.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-run.md

@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-ship-coordinator.md

@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-spec-writer.md

@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-test-coverage-gapper.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-test-triage.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-test-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.44.0"
+token_pilot_version: "0.45.0"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
 requiredMcpServers:
   - "token-pilot"

package/dist/core/event-log.d.ts

@@ -38,6 +38,17 @@ export interface HookEvent {
      * never populate it; events stay shape-compatible.
      */
     parent_agent_id?: string | null;
+    /**
+     * v0.45.0 — root/parent SESSION id (distinct from agent_id). Claude Code
+     * exposes `parent_session_id` in subagent hook payloads (binary:
+     * `if(D.parentSessionId) X.parent_session_id = D.parentSessionId`). A
+     * subagent's MCP server is spawned with CLAUDE_CODE_SESSION_ID = the AGENT
+     * session, so its tool-call and denial savings get tagged with that id and
+     * the statusline's main-session filter drops them. Capturing the parent lets
+     * the badge roll subagent savings up to the conversation that spawned them.
+     * Optional — absent on the main thread and on older Claude Code.
+     */
+    parent_session_id?: string | null;
     /**
      * v0.38.0 — id of the token-pilot workflow this event belongs to,
      * when one is active (TOKEN_PILOT_WORKFLOW_ID set). Lets fleet-level

package/dist/hooks/session-start.d.ts

@@ -8,6 +8,7 @@
  * Output contract: one JSON line on stdout, or exit 0 silent.
  */
 import { type HookEvent } from "../core/event-log.js";
+import { type ToolProfile } from "../server/tool-profiles.js";
 export declare function buildSubagentAdoptionNudge(events: HookEvent[], now: number, windowDays?: number, minSample?: number, threshold?: number): string | null;
 export interface AgentEntry {
     name: string;
@@ -43,5 +44,13 @@ export declare function buildReminderMessage(agents: AgentEntry[], maxReminderTo
  * Returns the JSON string to write to stdout, or null for silent exit.
  * Never throws — any error → null (fail-safe pass-through).
  */
+/**
+ * v0.45.0 (token-pilot-2fd part 2) — when a trimmed TOOL profile is active,
+ * the banner still names tools that profile hides. The full default advertises
+ * everything, but an explicit nav/edit/minimal does not, so warn the agent
+ * before it calls a hidden tool, hits "No such tool available", and falls back
+ * to raw Read/Bash. Empty string for the default `full` profile.
+ */
+export declare function profileBannerNote(profile: ToolProfile): string;
 export declare function handleSessionStart(opts: HandleSessionStartOptions): Promise<string | null>;
 //# sourceMappingURL=session-start.d.ts.map

package/dist/hooks/session-start.js

@@ -11,6 +11,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { loadLatestSnapshot } from "./../handlers/session-snapshot-persist.js";
 import { loadEvents } from "../core/event-log.js";
+import { parseProfileEnv } from "../server/tool-profiles.js";
 const SNAPSHOT_FRESH_MS = 2 * 3600 * 1000; // 2h — enough to cover compaction/restart, tight enough that a new day's unrelated work doesn't inherit yesterday's thread
 // ─── subagent adoption nudge (v0.32.0) ──────────────────────────────
 // Pure function: takes the event log + current time, returns either a
@@ -138,7 +139,8 @@ MANDATORY — use these BEFORE raw Read / Grep / git:
   smart_log(path?)             — git log with symbol context (INSTEAD of raw git log)
   test_summary(command)        — test runs without dumping full output
   project_overview             — unfamiliar repo top-level map (first step)
-Batch variants (prefer over loops): read_symbols, smart_read_many, read_section.
+Batch variants (prefer over loops): read_symbols, smart_read_many.
+read_section — Markdown/YAML/JSON/CSV ONLY (by heading/key/row); for CODE use read_range / read_symbol.
 Also available: read_range, read_diff, module_info, related_files, explore_area,
 code_audit, find_unused, session_snapshot, session_budget, session_analytics.
 Raw Read/Grep allowed only with offset/limit / narrow regex / non-code files,
@@ -235,6 +237,20 @@ export function buildReminderMessage(agents, maxReminderTokens) {
  * Returns the JSON string to write to stdout, or null for silent exit.
  * Never throws — any error → null (fail-safe pass-through).
  */
+/**
+ * v0.45.0 (token-pilot-2fd part 2) — when a trimmed TOOL profile is active,
+ * the banner still names tools that profile hides. The full default advertises
+ * everything, but an explicit nav/edit/minimal does not, so warn the agent
+ * before it calls a hidden tool, hits "No such tool available", and falls back
+ * to raw Read/Bash. Empty string for the default `full` profile.
+ */
+export function profileBannerNote(profile) {
+    if (profile === "full")
+        return "";
+    return (`⚠ TOKEN_PILOT_PROFILE=${profile} — trimmed tool surface active. Some tools named below are NOT advertised this session ` +
+        `(test_summary / code_audit / find_unused always; read_for_edit / read_range / read_diff / batch reads on nav & minimal). ` +
+        `Calling them returns "No such tool available" — use the listed alternatives or unset TOKEN_PILOT_PROFILE to advertise all.\n\n`);
+}
 export async function handleSessionStart(opts) {
     try {
         if (!opts.sessionStartConfig.enabled) {
@@ -242,6 +258,10 @@ export async function handleSessionStart(opts) {
         }
         const agents = await scanAgents(opts.projectRoot, opts.homeDir);
         let message = buildReminderMessage(agents, opts.sessionStartConfig.maxReminderTokens);
+        // Prepend a profile caveat when a trimmed surface hides referenced tools.
+        message =
+            profileBannerNote(parseProfileEnv(process.env.TOKEN_PILOT_PROFILE)) +
+                message;
         // TP-340: surface a fresh snapshot so the new session can resume.
         const snap = await loadLatestSnapshot(opts.projectRoot);
         if (snap && snap.ageMs < SNAPSHOT_FRESH_MS) {

package/dist/hooks/subagent-stop.d.ts

@@ -38,6 +38,13 @@ export interface SubagentStopInput {
     last_assistant_message?: string;
     session_id?: string;
     parent_agent_id?: string;
+    /**
+     * v0.45.0 — root/parent session id. CC ships this in the SubagentStop
+     * payload (`X.parent_session_id`). Lets the statusline roll a subagent's
+     * savings (tagged with the agent's own session id) up to the parent
+     * conversation. Absent on older CC → field simply not written.
+     */
+    parent_session_id?: string;
 }
 /**
  * Best-effort token total from a subagent transcript (JSONL of CC

package/dist/hooks/subagent-stop.js

@@ -90,6 +90,9 @@ export function buildSubagentTaskEvent(input, now, tokensOverride) {
         agent_type: input.agent_type ?? null,
         agent_id: input.agent_id ?? null,
         ...(input.parent_agent_id ? { parent_agent_id: input.parent_agent_id } : {}),
+        ...(input.parent_session_id
+            ? { parent_session_id: input.parent_session_id }
+            : {}),
         event: "task",
         file: "",
         lines: 0,

package/dist/index.d.ts

@@ -39,6 +39,21 @@ export declare function handleHookRead(filePathArg?: string, mode?: HookMode, de
  * wrapping.
  */
 export declare function runHookReadDispatch(filePathArg: string | undefined, mode: HookMode, denyThresholdArg?: number, projectRootArg?: string, adaptive?: HookReadAdaptiveOptions): Promise<string | null>;
+/**
+ * v0.45.0 (token-pilot-xg9) — how many lines a Read actually pulls.
+ *
+ * An unbounded Read (no offset/limit) pulls the whole file. A bounded Read
+ * pulls `limit` lines starting at `offset` — but Claude Code's Read defaults
+ * to a 2000-line page, so `Read(file, limit=2000)` or an offset with no limit
+ * drags a whole big file through. The old hook passed ANY bounded Read
+ * straight through (`hasOffset || hasLimit → return null`), which is the leak:
+ * the model bounds with a large/default limit and reads everything hook-free
+ * AND un-counted in the adaptive burn signal. Comparing the *span* against the
+ * deny threshold closes that while still letting a genuinely narrow slice pass.
+ *
+ * `offset` / `limit` are null when the field is absent on the tool call.
+ */
+export declare function effectiveReadSpanLines(totalLines: number, offset: number | null, limit: number | null): number;
 /**
  * PreToolUse:Edit / MultiEdit / Write enforcement.
  *

package/dist/index.js

@@ -767,14 +767,36 @@ export async function runHookReadDispatch(filePathArg, mode, denyThresholdArg, p
     const projectRoot = projectRootArg ?? process.cwd();
     return runHookReadDispatchImpl(filePathArg, mode, denyThreshold, projectRoot, adaptive);
 }
+/**
+ * v0.45.0 (token-pilot-xg9) — how many lines a Read actually pulls.
+ *
+ * An unbounded Read (no offset/limit) pulls the whole file. A bounded Read
+ * pulls `limit` lines starting at `offset` — but Claude Code's Read defaults
+ * to a 2000-line page, so `Read(file, limit=2000)` or an offset with no limit
+ * drags a whole big file through. The old hook passed ANY bounded Read
+ * straight through (`hasOffset || hasLimit → return null`), which is the leak:
+ * the model bounds with a large/default limit and reads everything hook-free
+ * AND un-counted in the adaptive burn signal. Comparing the *span* against the
+ * deny threshold closes that while still letting a genuinely narrow slice pass.
+ *
+ * `offset` / `limit` are null when the field is absent on the tool call.
+ */
+export function effectiveReadSpanLines(totalLines, offset, limit) {
+    if (offset == null && limit == null)
+        return totalLines;
+    const DEFAULT_READ_PAGE = 2000;
+    const start = offset != null && offset > 0 ? offset : 0;
+    const page = limit != null && limit >= 0 ? limit : DEFAULT_READ_PAGE;
+    return Math.max(0, Math.min(page, totalLines - start));
+}
 async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, projectRoot, adaptive = {}) {
     if (mode === "off")
         return null;
     // Parse stdin to get tool_input + session/agent metadata, unless a
     // filePath was supplied directly (tests, --filePath invocation).
     let filePath = filePathArg;
-    let hasOffset = false;
-    let hasLimit = false;
+    let offsetVal = null;
+    let limitVal = null;
     let sessionId = "";
     let agentType = null;
     let agentId = null;
@@ -783,8 +805,14 @@ async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, project
             const stdin = readFileSync(0, "utf-8");
             const input = JSON.parse(stdin);
             filePath = input?.tool_input?.file_path;
-            hasOffset = input?.tool_input?.offset != null;
-            hasLimit = input?.tool_input?.limit != null;
+            offsetVal =
+                typeof input?.tool_input?.offset === "number"
+                    ? input.tool_input.offset
+                    : null;
+            limitVal =
+                typeof input?.tool_input?.limit === "number"
+                    ? input.tool_input.limit
+                    : null;
             sessionId = typeof input?.session_id === "string" ? input.session_id : "";
             agentType =
                 typeof input?.agent_type === "string" ? input.agent_type : null;
@@ -799,9 +827,6 @@ async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, project
     const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
     if (!CODE_EXTENSIONS.has(ext))
         return null;
-    // Bounded Reads are always passed through — the agent already narrowed scope.
-    if (hasOffset || hasLimit)
-        return null;
     // Path safety: refuse to summarise any file outside the project root
     // (traversal, symlinks pointing outside). Pass-through on failure so the
     // agent is never blocked by a safety reject.
@@ -829,13 +854,20 @@ async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, project
     try {
         fileContent = readFileSync(filePath, "utf-8");
         lineCount = fileContent.split("\n").length;
-        if (lineCount <= effectiveThreshold)
-            return null;
     }
     catch {
         return null;
     }
-    const charEst = Math.ceil(fileContent.length / 4);
+    // v0.45.0 (token-pilot-xg9) — measure the span the Read actually pulls, not
+    // just the file size. A narrow bounded slice (< threshold) still passes; a
+    // `limit=2000` / offset-no-limit read of a big file no longer slips through.
+    const spanLines = effectiveReadSpanLines(lineCount, offsetVal, limitVal);
+    if (spanLines <= effectiveThreshold)
+        return null;
+    // Cost estimate reflects what the read would pull (the span), so a bounded
+    // deny doesn't over-report savings vs the whole-file figure.
+    const spanRatio = lineCount > 0 ? Math.min(1, spanLines / lineCount) : 1;
+    const charEst = Math.ceil((fileContent.length * spanRatio) / 4);
     const wsRatio = (fileContent.match(/\s/g)?.length ?? 0) / fileContent.length;
     const estTokens = Math.ceil(charEst * (1 - wsRatio * 0.3));
     // Legacy telemetry (hook-denied.jsonl) — retained for backward compatibility
@@ -873,7 +905,7 @@ async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, project
     if (mode === "advisory") {
         const reason = `File "${filePath}" has ${lineCount} lines. Use mcp__token-pilot__smart_read("${filePath}") ` +
             `for a structural overview, or mcp__token-pilot__read_for_edit("${filePath}", symbol="<name>") ` +
-            `for edit context. Bounded Read with offset/limit is still allowed.`;
+            `for edit context. A narrow bounded Read (small limit) is still allowed.`;
         await writeEvent("denied", Math.ceil(reason.length / 4));
         return JSON.stringify({
             hookSpecificOutput: {
@@ -1282,6 +1314,29 @@ export async function handleDoctor() {
     catch {
         /* ignore */
     }
+    // ── explicit trimmed-profile warning (v0.45.0, token-pilot-26b) ──
+    // An explicit TOKEN_PILOT_PROFILE=nav|edit|minimal hides tools the rules and
+    // the pre-edit hook still reference (read_for_edit / read_range / batch),
+    // trapping edit sessions on "No such tool available". This recurred for two
+    // users. Surface it loudly so they can remove it.
+    try {
+        const raw = process.env.TOKEN_PILOT_PROFILE;
+        if (raw && raw.trim()) {
+            const { parseProfileEnv } = await import("./server/tool-profiles.js");
+            if (parseProfileEnv(raw) !== "full") {
+                console.log(`⚠ TOKEN_PILOT_PROFILE=${raw.trim()} is set — a TRIMMED tool surface.\n` +
+                    `  It hides read_for_edit / read_range / batch reads (and code_audit /\n` +
+                    `  find_unused / test_summary) that the rules + pre-edit hook still name →\n` +
+                    `  calls to them fail with "No such tool available" and the agent falls\n` +
+                    `  back to raw Read/Bash.\n` +
+                    `  Fix: remove "TOKEN_PILOT_PROFILE" from your .mcp.json env block (or set\n` +
+                    `  it to "full"), then restart. Full is the default since v0.45.0.\n`);
+            }
+        }
+    }
+    catch {
+        /* doctor must never crash over an optional check */
+    }
     // ── profile recommendation ──
     // v0.26.4 — data-driven. Reads cumulative tool-calls.jsonl and suggests
     // the narrowest TOKEN_PILOT_PROFILE that wouldn't hide any tool the

package/dist/server/profile-recommender.js

@@ -41,25 +41,29 @@ export function recommendProfile(events) {
             lowConfidence: true,
         };
     }
+    // v0.45.0 (token-pilot-26b) — we NO LONGER recommend trimming to nav/edit.
+    // Past tool usage doesn't predict future edits, and a trimmed profile hides
+    // read_for_edit / read_range / batch reads that the rules and the pre-edit
+    // hook still reference — so the agent calls them, hits "No such tool
+    // available", and falls back to raw Read/Bash. That recurring trap cost two
+    // users whole sessions. Full is the recommendation; minimal stays a
+    // self-serve, clearly-warned opt-in for context-critical work only.
     const allInNav = [...used].every((t) => NAV_TOOLS.has(t));
     if (allInNav) {
         return {
-            recommended: "nav",
-            reason: `Every tool you've used (${uniqueToolsSeen} distinct) is part of the nav subset. You're a read-only explorer.`,
+            recommended: "full",
+            reason: `You've used only nav-subset tools so far (${uniqueToolsSeen} distinct), but read_for_edit / read_range / batch reads — named by the rules and the pre-edit hook — live in edit/full. Stay on full so an edit doesn't hit "No such tool available". Set TOKEN_PILOT_PROFILE=minimal yourself ONLY if context is critically tight (it hides edit tools).`,
             uniqueToolsSeen,
             totalCalls,
-            wouldHide: [
-                ...[...EDIT_EXTRAS].filter((t) => !used.has(t)),
-                /* full-only — we don't enumerate here, keep the list short */
-            ],
+            wouldHide: [],
             lowConfidence: false,
         };
     }
     const allInEditOrBelow = [...used].every((t) => NAV_TOOLS.has(t) || EDIT_EXTRAS.has(t));
     if (allInEditOrBelow) {
         return {
-            recommended: "edit",
-            reason: `You use edit-preparation tools (read_for_edit, batch reads) but never reach for full-only tools like code_audit/test_summary/find_unused.`,
+            recommended: "full",
+            reason: `You use edit-prep tools but haven't reached for full-only ones (code_audit/test_summary/find_unused) yet. Stay on full — they cost ~1k tokens to advertise but trimming hides them the moment you need one, and dead calls cost more.`,
             uniqueToolsSeen,
             totalCalls,
             wouldHide: [],
@@ -87,15 +91,14 @@ export function formatRecommendation(rec) {
     lines.push(`  data:         ${rec.totalCalls} calls, ${rec.uniqueToolsSeen} distinct tools`);
     lines.push(`  recommend:    TOKEN_PILOT_PROFILE=${rec.recommended}`);
     lines.push(`  why:          ${rec.reason}`);
-    if (rec.recommended !== "full") {
-        lines.push(`  savings:      ~${rec.recommended === "nav" ? "2200 tokens (−54%)" : "1000 tokens (−25%)"} on every tools/list response`);
-        lines.push(`  apply:        add "env": { "TOKEN_PILOT_PROFILE": "${rec.recommended}" } to your token-pilot entry in .mcp.json`);
-    }
-    else if (rec.lowConfidence) {
-        lines.push(`  action:       keep default (full). Re-run \`token-pilot doctor\` after a few real sessions for a data-backed suggestion.`);
+    // v0.45.0 (26b) — we no longer print an "apply nav/edit to .mcp.json"
+    // snippet. recommendProfile always returns `full`; the old snippet trapped
+    // users into trimming, which hid edit tools the rules reference.
+    if (rec.lowConfidence) {
+        lines.push(`  action:       keep default (full). Re-run \`token-pilot doctor\` after a few real sessions for a data-backed view.`);
     }
     else {
-        lines.push(`  action:       keep default (full). You're using what you have.`);
+        lines.push(`  action:       keep default (full). Trim to minimal yourself only for context-critical, read-only work.`);
     }
     return lines.join("\n");
 }

package/dist/server/tool-definitions.d.ts

@@ -8,8 +8,8 @@
  *
  *   minimal — 5 core tools, minimal context overhead
  *   nav     — 10 exploration tools, no editing
- *   edit    — nav + 6 edit-prep tools (DEFAULT)
- *   full    — everything including audit tools
+ *   edit    — nav + 6 edit-prep tools
+ *   full    — everything including audit tools (DEFAULT since v0.45.0)
  */
 import type { ToolProfile } from "./tool-profiles.js";
 /**

package/dist/server/tool-definitions.js

@@ -42,7 +42,7 @@ const MCP_INSTRUCTIONS_NAV = [
     "• Explore: project_overview → explore_area → smart_read → read_symbol",
 ].join("\n");
 // ---------------------------------------------------------------------------
-// Edit profile — nav + batch reads + edit-prep (DEFAULT)
+// Edit profile — nav + batch reads + edit-prep
 // ---------------------------------------------------------------------------
 const MCP_INSTRUCTIONS_EDIT = [
     "Token Pilot — token-efficient code reading (saves 60-80% tokens). ALWAYS prefer these tools over Read/cat/grep.",
@@ -87,7 +87,7 @@ const MCP_INSTRUCTIONS_EDIT = [
     "• Long session: session_snapshot → compact context → continue with minimal state",
 ].join("\n");
 // ---------------------------------------------------------------------------
-// Full profile — all tools including audit (code_audit, find_unused, test_summary)
+// Full profile — all tools including audit (code_audit, find_unused, test_summary) — DEFAULT since v0.45.0
 // ---------------------------------------------------------------------------
 const MCP_INSTRUCTIONS_FULL = [
     "Token Pilot — token-efficient code reading (saves 60-80% tokens). ALWAYS prefer these tools over Read/cat/grep.",
@@ -297,7 +297,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "read_section",
-        description: "Read a specific section from Markdown, YAML, JSON, or CSV files. Markdown: by heading name. YAML/JSON: by top-level key. CSV: by row range (rows:1-50). Much cheaper than reading the whole file.",
+        description: "Read a specific section from Markdown, YAML, JSON, or CSV files. Markdown: by heading name. YAML/JSON: by top-level key. CSV: by row range (rows:1-50). Much cheaper than reading the whole file. DOCS/DATA ONLY — `heading` is required; this does NOT read code by line/symbol. For source files use read_range (line range) or read_symbol (one symbol).",
         inputSchema: {
             type: "object",
             properties: {

package/dist/server/tool-profiles.js

@@ -117,8 +117,16 @@ export function filterToolsByProfile(tools, profile) {
  * silently apply a guess.
  */
 export function parseProfileEnv(envValue, warn = () => { }) {
+    // v0.45.0 — default is now `full` (was `edit`). Trimming the advertised
+    // tools/list saved ~2k tokens but created a mismatch: the rules, the
+    // SessionStart/PostToolUse banners and the pre-edit hook all reference tools
+    // (read_for_edit, test_summary, batch reads) that a trimmed profile hides —
+    // so the model calls them, hits "No such tool available", and falls back to
+    // raw Read/Bash. Those dead round-trips cost far more than the 2k saved.
+    // Advertise everything by default; users who truly need the smaller surface
+    // opt in with TOKEN_PILOT_PROFILE=nav|edit|minimal.
     if (!envValue)
-        return "edit";
+        return "full";
     const lower = envValue.trim().toLowerCase();
     if (lower === "full" ||
         lower === "nav" ||
@@ -126,7 +134,7 @@ export function parseProfileEnv(envValue, warn = () => { }) {
         lower === "minimal") {
         return lower;
     }
-    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit|minimal. Falling back to edit.`);
-    return "edit";
+    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit|minimal. Falling back to full.`);
+    return "full";
 }
 //# sourceMappingURL=tool-profiles.js.map

package/dist/server.js

@@ -4,6 +4,7 @@ import { AstIndexClient } from "./ast-index/client.js";
 import { FileCache } from "./core/file-cache.js";
 import { ContextRegistry } from "./core/context-registry.js";
 import { SessionRegistryManager } from "./core/session-registry.js";
+import { appendError, classifyError } from "./core/error-log.js";
 import { SymbolResolver } from "./core/symbol-resolver.js";
 import { SessionAnalytics, } from "./core/session-analytics.js";
 import { classifyIntent } from "./core/intent-classifier.js";
@@ -277,8 +278,8 @@ export async function createServer(projectRoot, options) {
         instructions: getMcpInstructions(activeProfile),
     });
     const advertisedTools = filterToolsByProfile(TOOL_DEFINITIONS, activeProfile);
-    if (activeProfile !== "edit") {
-        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools. Set TOKEN_PILOT_PROFILE=edit for the default set.\n`);
+    if (activeProfile !== "full") {
+        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools (full is the default). A trimmed profile hides tools the rules/hooks still reference; unset TOKEN_PILOT_PROFILE to advertise all.\n`);
     }
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: advertisedTools,
@@ -1057,6 +1058,17 @@ export async function createServer(projectRoot, options) {
                     return { content: budgetResult.content };
                 }
                 default:
+                    // token-pilot-m68 — an unknown tool NAME that still reached the
+                    // server (a forwarded call CC didn't reject). Log it so the gap is
+                    // visible via `token-pilot errors`.
+                    void appendError({
+                        ts: Date.now(),
+                        hook: `mcp-tool:${name}`,
+                        level: "warn",
+                        code: "unknown_tool",
+                        msg: `Unknown tool: ${name}`,
+                        input: { tool: name },
+                    });
                     return {
                         content: [{ type: "text", text: `Unknown tool: ${name}` }],
                         isError: true,
@@ -1065,6 +1077,23 @@ export async function createServer(projectRoot, options) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            // v0.45.0 (token-pilot-m68) — surface tool failures that REACH the
+            // server (validation errors, handler exceptions) in the same
+            // ~/.token-pilot/hook-errors.jsonl the hooks use, so `token-pilot errors`
+            // shows them. Previously these vanished — telemetry reported "saving
+            // tokens, all ok" while broken tp calls were invisible. Best-effort;
+            // appendError never throws. NOTE: "No such tool available" rejections
+            // happen at the Claude Code layer BEFORE the call reaches us, so those
+            // remain invisible by CC design (mitigated by the full-tool default).
+            void appendError({
+                ts: Date.now(),
+                hook: `mcp-tool:${name}`,
+                level: "error",
+                code: classifyError(err),
+                msg: message,
+                stack: err instanceof Error ? err.stack : undefined,
+                input: { tool: name },
+            });
             return {
                 content: [{ type: "text", text: `Error: ${message}` }],
                 isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",