token-pilot 0.28.0 → 0.28.2

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot \u2014 save 60-90% tokens when AI reads code",
-    "version": "0.28.0"
+    "version": "0.28.2"
   },
   "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. 22 MCP tools + 19 subagents + budget watchdog hooks.",
-      "version": "0.28.0",
+      "version": "0.28.2",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "description": "Saves 60-90% tokens when AI reads code. AST-aware lazy reading, symbol navigation, cross-session tool-usage analytics, 22 subagents (haiku/sonnet/opus-tiered) with budget watchdog.",
   "author": {
     "name": "Digital-Threads",

package/CHANGELOG.md

@@ -5,6 +5,69 @@ 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.28.2] - 2026-04-19
+
+### Fixed — plugin hooks were never actually reaching Claude Code
+
+**Critical: all our PreToolUse hooks (Read, Edit, Bash, Grep) in the plugin-install path have been silently non-functional since v0.1.0.**
+
+Live verification by Sonnet 4.6 on Windows surfaced the symptom: `grep -r`, `cat <code-file>`, and `bare git log` — documented as blocked in v0.28.0 — were not being blocked. Pattern-based deny from our hook-pre-bash / hook-pre-grep never fired. The tests passed because the pure decision logic is correct; the issue was that **Claude Code never called our hook at all**.
+
+Root cause, confirmed against the [official Anthropic plugin-dev skill](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md):
+
+> **For plugin hooks** in `hooks/hooks.json`, use wrapper format
+
+Canonical plugin hook location is **`<plugin-root>/hooks/hooks.json`**, not `<plugin-root>/.claude-plugin/hooks/hooks.json`. We'd been putting it inside `.claude-plugin/` since v0.1.0 based on a misreading — Claude Code's plugin loader never looked there.
+
+The fact that Read-hook blocking "seemed to work" earlier was because `npx token-pilot install-hook` copied the same hooks into `~/.claude/settings.json` directly (a separate code path that works). When I cleaned up duplicates via `uninstall-hook` in v0.28.0, the plugin-side fallback I thought existed turned out never to have existed — and *no one's hooks were firing at all*.
+
+Reference comparison — `claude-context-mode@0.7.2` ships hooks.json in both locations. The `hooks/hooks.json` copy is what actually works; the `.claude-plugin/hooks/hooks.json` is dead weight.
+
+### Change
+
+`git mv .claude-plugin/hooks/hooks.json hooks/hooks.json`. Also:
+
+- `package.json` `files` now includes `hooks/hooks.json`.
+- Regression test updated to read from the new canonical path.
+- Code comments in `src/hooks/installer.ts` and `src/index.ts` that referenced the old path corrected.
+
+### After upgrade — required user action
+
+Plugin users on 0.27.x / 0.28.0 / 0.28.1 need to reinstall the plugin so the hook files land in the correct location:
+
+```bash
+claude plugin marketplace update token-pilot
+claude plugin uninstall token-pilot@token-pilot
+claude plugin install token-pilot@token-pilot
+```
+
+Then restart Claude Code. PreToolUse hooks for all four matchers (Read / Edit / Bash / Grep) will fire in the new session. Verify with Sonnet's test: a `Grep(pattern="getUserById")` in a new session must now return a deny with the find_usages suggestion.
+
+npm-install users on `install-hook` are unaffected (their hooks live in `~/.claude/settings.json` and always worked).
+
+1019 tests still passing.
+
+## [0.28.1] - 2026-04-19
+
+### Fixed — `session_analytics` hidden in `nav` profile defeated the whole point of profiles
+
+Field report from Opus 4.7 running our own verification prompt against v0.28.0 on Windows: user had `TOKEN_PILOT_PROFILE=nav` set, Opus tried `mcp__plugin_token-pilot_token-pilot__session_analytics` for the pre-flight baseline and got "No matching deferred tools found". The whole verification stalled — the tool that measures whether the profile saves tokens wasn't in the profile.
+
+Root cause: in v0.26.3 I bucketed `session_analytics` / `session_budget` / `session_snapshot` as "full-only" along with `test_summary`, `code_audit`, `find_unused`. That was a mistake — those three are **diagnostic meta-tools**, not workflow tools. Hiding them from `nav` and `edit` contradicts the profile feature's own purpose: if you can't verify the savings, why would you trust the profile?
+
+Fix: new `META_TOOLS` set in `src/server/tool-profiles.ts`. META is **always visible** regardless of profile. Contents:
+- `session_analytics` — self-measurement (verifies the profile is working)
+- `session_budget` — remaining budget view
+- `session_snapshot` — state capture for /clear recovery
+
+`filterToolsByProfile` now does `NAV_TOOLS ∪ META_TOOLS` for nav and `NAV_TOOLS ∪ EDIT_EXTRAS ∪ META_TOOLS` for edit. New regression test asserts META is present in every profile.
+
+### Impact
+
+Users on `nav` / `edit` profiles get **3 extra tools** in their `tools/list` (~400 additional tokens at session start) but retain the ability to verify savings. The math: if a profile saves 2200 tokens on the original 22-tool list but hides the observability tools, the user mentally pads the savings with uncertainty and eventually switches back to `full`. The 400-token tax for keeping visibility is cheaper than that.
+
+1019 tests passing (+1 new — META_TOOLS cross-profile visibility).
+
 ## [0.28.0] - 2026-04-19
 
 ### Added — passive pre-intercept hooks for Grep and Bash

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

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: f30fb3378463d6518041650487f1074b5411c6c3d6d7df315d21267f25f812d6
 ---
 

package/agents/tp-audit-scanner.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
 ---
 

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.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 559a0b61d20974bf33e35bc4c80dcf1b41d10d4df46cf9d05d3d5620713cd46f
 ---
 

package/agents/tp-context-engineer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 8977f452021085a9ba63338bf94e8903e56b30e199dc32e41acc4ec3173a931d
 ---
 

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

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 33798b70002a206c4547d08ff46caefe6dbe5a9300f94ab5dad4a57ab5fb4478
 ---
 

package/agents/tp-debugger.md

@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: ada78a5a3f029721fa51e7cd203395ff0e87f0ab614cc7cf0d5bcc1bf9a80435
 ---
 

package/agents/tp-dep-health.md

@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 6224d989835ea284985b474005b8b46052b7007c4610e661b10658286b5c6624
 ---
 

package/agents/tp-doc-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 72347b06aaea75ed960972e96e2523c221b2ea7c892a3931aa0e7c32e4c86555
 ---
 

package/agents/tp-history-explorer.md

@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: b2daca007e959eaf26bf9a4d92ba36c3aa277a51de4ca4db674833d36acbe11b
 ---
 

package/agents/tp-impact-analyzer.md

@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 0be2620ce0303f912f6b3334f261d169f064970c0d16602fa1e76db4cb2ea441
 ---
 

package/agents/tp-incident-timeline.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 420ffc423c7479a8d4e1b226cf73eb98d6d41388317c74a950d7f3b6240b6786
 ---
 

package/agents/tp-incremental-builder.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 9cb0bdf6e209d8ac613487385c01ef269d827dc3eddaf81b8eba581a3150b1e3
 ---
 

package/agents/tp-migration-scout.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: cf32cdee777430ecc6732db32b3f883a685c8a02b6dc93379d71b15555e79b3e
 ---
 

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.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
 ---
 

package/agents/tp-performance-profiler.md

@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 14b6fb4423a839c119120c2ea12c9dd6ab6ad1aeb13df1e7c22807b290cf1f9c
 ---
 

package/agents/tp-pr-reviewer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 73ba5844c8354088dcb10c671622daecc0e8589568de15a6001e1cf951eea586
 ---
 

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.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: dcc2c2aaeb443cc9688639b4337c6069b9d5bf21e3ed757fc8b3ac8a9d61bc03
 ---
 

package/agents/tp-review-impact.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 72b635f511492188587d6cb6fd70f936ae34cf5df1f9cd9eff7849cf1231e185
 ---
 

package/agents/tp-run.md

@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

package/agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
 ---
 

package/agents/tp-ship-coordinator.md

@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: e8f9c28da23e318328f5afd85b09e8e7b96e0dab21a4c6779ba798cd709ced64
 ---
 

package/agents/tp-spec-writer.md

@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: ed0b9f938c152c0d7be5a6a5eaf3c97c19b27ae4a9540aec342f0edb0927cb27
 ---
 

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

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: cc3d1f46fdb95ac3caf9344f69f1ddcd5ce5a175ee70aa150b7f9fda93edb152
 ---
 

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.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
 ---
 

package/agents/tp-test-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.28.0"
+token_pilot_version: "0.28.2"
 token_pilot_body_hash: 96211a3e7f6b52dd47fef286eec3584b1c269fb3464c1102f8b7edbe470700e6
 ---
 

package/dist/hooks/installer.js

@@ -92,7 +92,7 @@ function createHookConfig(options) {
  */
 export async function installHook(projectRoot, options) {
     // Skip auto-install when running as a Claude Code plugin —
-    // the plugin system already registers hooks via .claude-plugin/hooks/hooks.json
+    // the plugin system already registers hooks via hooks/hooks.json
     if (process.env.CLAUDE_PLUGIN_ROOT) {
         return {
             installed: false,

package/dist/index.js

@@ -589,13 +589,13 @@ export function handleHookEdit() {
 export async function handleInstallHook(projectRoot) {
     // v0.26.5 — plugin-aware early-return. If we're running as a Claude
     // Code plugin (CLAUDE_PLUGIN_ROOT set) the hooks are already declared
-    // in .claude-plugin/hooks/hooks.json and Claude Code wires them up
+    // in hooks/hooks.json and Claude Code wires them up
     // on install. Calling install-hook in that context would write a
     // duplicate entry to the user's settings.json and emit two hooks for
     // every event. Bail early.
     if (process.env.CLAUDE_PLUGIN_ROOT) {
         console.log("token-pilot is running as a Claude Code plugin — hooks are already\n" +
-            "declared in .claude-plugin/hooks/hooks.json and registered by the\n" +
+            "declared in hooks/hooks.json and registered by the\n" +
             "plugin installer. `install-hook` is only needed for npm/npx setups.\n" +
             "Skipping to avoid duplicate hook entries.");
         process.exit(0);
@@ -652,7 +652,7 @@ export async function handleDoctor() {
     // ── Installation mode ──
     // v0.26.5 — tell the user HOW token-pilot is installed. Matters
     // because plugin users don't need `install-hook` (hooks come from
-    // .claude-plugin/hooks/hooks.json); npm users do. dev/worktree users
+    // hooks/hooks.json); npm users do. dev/worktree users
     // are usually contributors running from a local checkout.
     let installMode;
     if (process.env.CLAUDE_PLUGIN_ROOT) {

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

@@ -1,5 +1,5 @@
 /**
- * v0.26.3 — tool profiles.
+ * v0.26.3 — tool profiles. v0.28.1 — META_TOOLS always-available fix.
  *
  * Idea lifted honestly from Token Savior's TOKEN_SAVIOR_PROFILE. When an
  * MCP server advertises 22 tools, every tools/list response costs the
@@ -10,20 +10,26 @@
  * user in the same server can still reach the full set if they know
  * the name).
  *
- * Three profiles:
- *   - full  (default): everything, same as pre-v0.26.3.
- *   - nav  : read-only exploration. smart_read, outline, find_usages,
- *            read_symbol, project_overview, module_info, related_files,
- *            explore_area, smart_log, smart_diff.
- *   - edit : nav + batch reads + everything Edit needs to hit a symbol
- *            precisely. Adds read_symbols, read_range, read_section,
- *            read_diff, read_for_edit, smart_read_many.
+ * Three profiles, plus one always-on set:
+ *   - META (implicit): always advertised, every profile — meta-tools
+ *     the user needs to verify token-pilot is actually saving anything.
+ *     Excluding them contradicts the whole point of profiles.
+ *   - full (default): everything, same as pre-v0.26.3.
+ *   - nav : META + read-only exploration (10 tools + META).
+ *   - edit: META + nav + batch reads + edit-prep (16 tools + META).
  *
  * Selection: TOKEN_PILOT_PROFILE=nav|edit|full env var. Unknown values
  * fall back to full with a stderr warning. Silent on missing env.
  */
 export type ToolProfile = "full" | "nav" | "edit";
 export declare const PROFILE_NAMES: readonly ToolProfile[];
+/**
+ * Meta-tools — diagnostic / self-observation tools that must be visible
+ * in EVERY profile. Excluding them defeats the profile feature's own
+ * purpose: if you can't check whether token-pilot is saving tokens, why
+ * would you trust the savings number?
+ */
+export declare const META_TOOLS: ReadonlySet<string>;
 /** Minimum nav profile — exploration only, no editing support. */
 export declare const NAV_TOOLS: ReadonlySet<string>;
 /** Edit profile adds batch reads + edit-preparation tools. */

package/dist/server/tool-profiles.js

@@ -1,5 +1,5 @@
 /**
- * v0.26.3 — tool profiles.
+ * v0.26.3 — tool profiles. v0.28.1 — META_TOOLS always-available fix.
  *
  * Idea lifted honestly from Token Savior's TOKEN_SAVIOR_PROFILE. When an
  * MCP server advertises 22 tools, every tools/list response costs the
@@ -10,14 +10,13 @@
  * user in the same server can still reach the full set if they know
  * the name).
  *
- * Three profiles:
- *   - full  (default): everything, same as pre-v0.26.3.
- *   - nav  : read-only exploration. smart_read, outline, find_usages,
- *            read_symbol, project_overview, module_info, related_files,
- *            explore_area, smart_log, smart_diff.
- *   - edit : nav + batch reads + everything Edit needs to hit a symbol
- *            precisely. Adds read_symbols, read_range, read_section,
- *            read_diff, read_for_edit, smart_read_many.
+ * Three profiles, plus one always-on set:
+ *   - META (implicit): always advertised, every profile — meta-tools
+ *     the user needs to verify token-pilot is actually saving anything.
+ *     Excluding them contradicts the whole point of profiles.
+ *   - full (default): everything, same as pre-v0.26.3.
+ *   - nav : META + read-only exploration (10 tools + META).
+ *   - edit: META + nav + batch reads + edit-prep (16 tools + META).
  *
  * Selection: TOKEN_PILOT_PROFILE=nav|edit|full env var. Unknown values
  * fall back to full with a stderr warning. Silent on missing env.
@@ -27,6 +26,17 @@ export const PROFILE_NAMES = [
     "nav",
     "edit",
 ];
+/**
+ * Meta-tools — diagnostic / self-observation tools that must be visible
+ * in EVERY profile. Excluding them defeats the profile feature's own
+ * purpose: if you can't check whether token-pilot is saving tokens, why
+ * would you trust the savings number?
+ */
+export const META_TOOLS = new Set([
+    "session_analytics",
+    "session_budget",
+    "session_snapshot",
+]);
 /** Minimum nav profile — exploration only, no editing support. */
 export const NAV_TOOLS = new Set([
     "smart_read",
@@ -59,10 +69,17 @@ export const EDIT_EXTRAS = new Set([
 export function filterToolsByProfile(tools, profile) {
     if (profile === "full")
         return [...tools];
-    if (profile === "nav")
-        return tools.filter((t) => NAV_TOOLS.has(t.name));
-    // edit = nav + extras
-    return tools.filter((t) => NAV_TOOLS.has(t.name) || EDIT_EXTRAS.has(t.name));
+    // META_TOOLS are ALWAYS visible — session_analytics, session_budget,
+    // session_snapshot are the instruments for verifying the profile is
+    // doing its job. Hiding them would turn "did this save tokens?" into
+    // a guess.
+    if (profile === "nav") {
+        return tools.filter((t) => NAV_TOOLS.has(t.name) || META_TOOLS.has(t.name));
+    }
+    // edit = nav + extras + meta
+    return tools.filter((t) => NAV_TOOLS.has(t.name) ||
+        EDIT_EXTRAS.has(t.name) ||
+        META_TOOLS.has(t.name));
 }
 /**
  * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "description": "Save up to 80% tokens when AI reads code \u2014 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",
@@ -15,6 +15,7 @@
     "scripts/postinstall.mjs",
     "start.sh",
     ".claude-plugin/",
+    "hooks/hooks.json",
     ".mcp.json",
     "skills/",
     "README.md",