diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9cfae6d..b23bfb1 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,14 +6,14 @@ }, "metadata": { "description": "Token Pilot — save 60-90% tokens when AI reads code", - "version": "0.50.2" + "version": "0.51.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. 25 MCP tools + 25 subagents + budget watchdog hooks.", - "version": "0.50.2", + "version": "0.51.0", "author": { "name": "Digital-Threads" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2842b17..845b1a0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "token-pilot", - "version": "0.50.2", + "version": "0.51.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", diff --git a/CHANGELOG.md b/CHANGELOG.md index 061c39f..e590a0c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,40 @@ 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.51.0] - 2026-07-26 + +### Changed — model assignment now follows a measured rule + +Five agents move from haiku to sonnet: `tp-run`, `tp-api-surface-tracker`, +`tp-dep-health`, `tp-doc-writer`, and `tp-incident-timeline` (which was +`inherit`, so it silently took whatever the session ran and could land on +haiku for a production incident). + +The old split had no stated basis. Two measurements on identical prompts +through `tp-run` gave one: + +| Task | Haiku | Sonnet | +|------|------:|-------:| +| List exported symbols, strict output format | **19,020 tok · 9.4s**, format exact | 25,798 tok · 12.6s, added a verdict line the prompt forbade | +| Find a defect in a decision function | 27,916 tok · 89s, narrow type issue | **30,307 tok · 50s**, the functional defect plus the follow-up | + +Haiku wins shape-bound work outright — cheaper, quicker, more literal. +Sonnet wins the moment the answer requires deciding what matters, which +is where haiku's answer came back narrower. + +The rule now written down: haiku for output with a predetermined shape +(commit message, orientation map, session briefing, coverage list, a +chain of commits quoted without interpretation); sonnet for anything that +weighs, ranks or explains. `tp-run` belongs in the second group because +it exists to take work no specialist claimed — its difficulty is unknown +when it is dispatched. + +Worth keeping in proportion: the gap between models is 8–26%, while +dispatching to `general-purpose` instead of a specialist costs 3x. The +model is a small optimisation; the agent is a large one. And because the +gap is small, a borderline task should go to sonnet — a wrong answer +costs more than the model does. + ## [0.50.2] - 2026-07-26 ### Fixed — hooks were dead on a freshly installed plugin diff --git a/agents/tp-api-surface-tracker.md b/agents/tp-api-surface-tracker.md index ef9c7f9..14b9afc 100644 --- a/agents/tp-api-surface-tracker.md +++ b/agents/tp-api-surface-tracker.md @@ -8,8 +8,8 @@ tools: - mcp__token-pilot__smart_diff - mcp__token-pilot__read_symbol - Bash -model: haiku -token_pilot_version: "0.50.2" +model: sonnet +token_pilot_version: "0.51.0" token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-audit-scanner.md b/agents/tp-audit-scanner.md index bad4730..afe890f 100644 --- a/agents/tp-audit-scanner.md +++ b/agents/tp-audit-scanner.md @@ -11,7 +11,7 @@ tools: - Grep - Read model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b requiredMcpServers: - "token-pilot" diff --git a/agents/tp-commit-writer.md b/agents/tp-commit-writer.md index db796f4..75fe544 100644 --- a/agents/tp-commit-writer.md +++ b/agents/tp-commit-writer.md @@ -8,7 +8,7 @@ tools: - mcp__token-pilot__test_summary - mcp__token-pilot__outline - Bash -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-context-engineer.md b/agents/tp-context-engineer.md index a78e9fb..128219f 100644 --- a/agents/tp-context-engineer.md +++ b/agents/tp-context-engineer.md @@ -13,7 +13,7 @@ tools: - Edit - Glob model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-dead-code-finder.md b/agents/tp-dead-code-finder.md index c332201..98f24c5 100644 --- a/agents/tp-dead-code-finder.md +++ b/agents/tp-dead-code-finder.md @@ -11,7 +11,7 @@ tools: - Grep - Read model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-debugger.md b/agents/tp-debugger.md index 6f37373..693b666 100644 --- a/agents/tp-debugger.md +++ b/agents/tp-debugger.md @@ -12,7 +12,7 @@ tools: - Read - Bash model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-dep-health.md b/agents/tp-dep-health.md index 0d3b4d0..354db39 100644 --- a/agents/tp-dep-health.md +++ b/agents/tp-dep-health.md @@ -8,8 +8,8 @@ tools: - mcp__token-pilot__find_unused - Bash - Read -model: haiku -token_pilot_version: "0.50.2" +model: sonnet +token_pilot_version: "0.51.0" token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-doc-writer.md b/agents/tp-doc-writer.md index b337629..ffdb422 100644 --- a/agents/tp-doc-writer.md +++ b/agents/tp-doc-writer.md @@ -12,8 +12,8 @@ tools: - Write - Edit - Glob -model: haiku -token_pilot_version: "0.50.2" +model: sonnet +token_pilot_version: "0.51.0" token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf requiredMcpServers: - "token-pilot" diff --git a/agents/tp-history-explorer.md b/agents/tp-history-explorer.md index ee7e95b..769cb71 100644 --- a/agents/tp-history-explorer.md +++ b/agents/tp-history-explorer.md @@ -10,7 +10,7 @@ tools: - Bash - Read model: haiku -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-impact-analyzer.md b/agents/tp-impact-analyzer.md index 188b7f0..2ca480f 100644 --- a/agents/tp-impact-analyzer.md +++ b/agents/tp-impact-analyzer.md @@ -12,7 +12,7 @@ tools: - mcp__token-pilot__read_symbols - Read model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f requiredMcpServers: - "token-pilot" diff --git a/agents/tp-incident-timeline.md b/agents/tp-incident-timeline.md index d3d2492..412f259 100644 --- a/agents/tp-incident-timeline.md +++ b/agents/tp-incident-timeline.md @@ -7,8 +7,8 @@ tools: - mcp__token-pilot__find_usages - mcp__token-pilot__read_symbol - Bash -model: inherit -token_pilot_version: "0.50.2" +model: sonnet +token_pilot_version: "0.51.0" token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb requiredMcpServers: - "token-pilot" diff --git a/agents/tp-incremental-builder.md b/agents/tp-incremental-builder.md index 4c0a677..2408adf 100644 --- a/agents/tp-incremental-builder.md +++ b/agents/tp-incremental-builder.md @@ -13,7 +13,7 @@ tools: - Edit - Bash model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-migration-scout.md b/agents/tp-migration-scout.md index 402d86b..7491e1f 100644 --- a/agents/tp-migration-scout.md +++ b/agents/tp-migration-scout.md @@ -11,7 +11,7 @@ tools: - Grep - Glob model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-onboard.md b/agents/tp-onboard.md index 99b2f15..9143d48 100644 --- a/agents/tp-onboard.md +++ b/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.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-performance-profiler.md b/agents/tp-performance-profiler.md index 8c60966..79a97bd 100644 --- a/agents/tp-performance-profiler.md +++ b/agents/tp-performance-profiler.md @@ -11,7 +11,7 @@ tools: - Bash - Read model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-pr-reviewer.md b/agents/tp-pr-reviewer.md index b7789f1..88bce87 100644 --- a/agents/tp-pr-reviewer.md +++ b/agents/tp-pr-reviewer.md @@ -11,7 +11,7 @@ tools: - mcp__token-pilot__read_for_edit - Read model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-refactor-planner.md b/agents/tp-refactor-planner.md index 1228b82..7182cf2 100644 --- a/agents/tp-refactor-planner.md +++ b/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.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-review-impact.md b/agents/tp-review-impact.md index 009354e..04c447f 100644 --- a/agents/tp-review-impact.md +++ b/agents/tp-review-impact.md @@ -9,7 +9,7 @@ tools: - mcp__token-pilot__module_info - Bash model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c requiredMcpServers: - "token-pilot" diff --git a/agents/tp-run.md b/agents/tp-run.md index 5973223..a1c5fb5 100644 --- a/agents/tp-run.md +++ b/agents/tp-run.md @@ -15,8 +15,8 @@ tools: - Grep - Glob - Bash -model: haiku -token_pilot_version: "0.50.2" +model: sonnet +token_pilot_version: "0.51.0" token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-session-restorer.md b/agents/tp-session-restorer.md index 4b0991c..a3cd788 100644 --- a/agents/tp-session-restorer.md +++ b/agents/tp-session-restorer.md @@ -9,7 +9,7 @@ tools: - mcp__token-pilot__session_budget - Bash - Read -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-ship-coordinator.md b/agents/tp-ship-coordinator.md index 40a9e47..9dc6fde 100644 --- a/agents/tp-ship-coordinator.md +++ b/agents/tp-ship-coordinator.md @@ -11,7 +11,7 @@ tools: - Read - Grep model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b requiredMcpServers: - "token-pilot" diff --git a/agents/tp-spec-writer.md b/agents/tp-spec-writer.md index 5334249..e926baf 100644 --- a/agents/tp-spec-writer.md +++ b/agents/tp-spec-writer.md @@ -9,7 +9,7 @@ tools: - Read - Write model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-test-coverage-gapper.md b/agents/tp-test-coverage-gapper.md index dcc54b3..5fa4530 100644 --- a/agents/tp-test-coverage-gapper.md +++ b/agents/tp-test-coverage-gapper.md @@ -10,7 +10,7 @@ tools: - mcp__token-pilot__test_summary - Glob - Grep -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-test-triage.md b/agents/tp-test-triage.md index f1431c4..29d7d7c 100644 --- a/agents/tp-test-triage.md +++ b/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.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90 requiredMcpServers: - "token-pilot" diff --git a/agents/tp-test-writer.md b/agents/tp-test-writer.md index 8963227..fd35a46 100644 --- a/agents/tp-test-writer.md +++ b/agents/tp-test-writer.md @@ -13,7 +13,7 @@ tools: - Edit - Bash model: sonnet -token_pilot_version: "0.50.2" +token_pilot_version: "0.51.0" token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9 requiredMcpServers: - "token-pilot" diff --git a/docs/agents.md b/docs/agents.md index 125dd8c..7f59ae8 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -64,11 +64,23 @@ Every agent carries an explicit `model:` field: | Model | Count | Used for | |-------|------:|---------| -| `haiku` | 9 | Structured / format-bound output (commit messages, onboarding maps, ADRs, session briefings) | -| `sonnet` | 15 | Reasoning tasks (review, debug, test, plan, audit, spec, profile, ship) | -| `inherit` | 1 | Deep correlation needing the main thread's model (`tp-incident-timeline`) | +| `haiku` | 5 | Mechanical work — extract, list, reformat against a fixed shape | +| `sonnet` | 20 | Judgement — decide what matters, what breaks, why it is so | -Under Opus 4.7's +35% tokenizer tax, keeping the majority of agent spawns on haiku/sonnet saves 5–10× model cost vs an all-Opus baseline. +### How the line is drawn + +Measured on identical prompts through `tp-run`: + +| Task | Haiku | Sonnet | +|------|------:|-------:| +| List exported symbols in a file (strict output format) | **19,020 tok · 9.4s**, format followed exactly | 25,798 tok · 12.6s, added a verdict line the prompt forbade | +| Find a defect in a decision function | 27,916 tok · 89s, found a narrow type issue | **30,307 tok · 50s**, found the functional defect and answered the follow-up | + +So haiku is the better tool for shape-bound work — cheaper, quicker, and more literal about the format. Sonnet is the better tool the moment the answer requires deciding what is important, because that is exactly where haiku's answer was narrower. + +Two things follow. First, most of the cost is subagent startup, not generation: the gap between models is 8–26%, while dispatching to `general-purpose` instead of a specialist costs 3x. Picking the model is a small optimisation; picking the agent is a large one. Second, because the gap is small, **when a task is borderline, choose sonnet** — a wrong answer costs more than the model does. + +The five on haiku all produce output with a predetermined shape: a commit message, an orientation map, a session briefing, a coverage list, a chain of commits quoted without interpretation. Anything that weighs, ranks, or explains is on sonnet — including `tp-run`, whose whole purpose is to take work no specialist claimed, so its difficulty is unknown in advance. ## Third-party Agent Integration (bless-agents) diff --git a/package-lock.json b/package-lock.json index dcf35ae..87bcacc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "token-pilot", - "version": "0.50.2", + "version": "0.51.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "token-pilot", - "version": "0.50.2", + "version": "0.51.0", "hasInstallScript": true, "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index c6adf1b..71e9e1f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "token-pilot", - "version": "0.50.2", + "version": "0.51.0", "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", diff --git a/server.json b/server.json index 13ecd30..2ae1323 100644 --- a/server.json +++ b/server.json @@ -6,12 +6,12 @@ "url": "https://github.com/Digital-Threads/token-pilot", "source": "github" }, - "version": "0.50.2", + "version": "0.51.0", "packages": [ { "registryType": "npm", "identifier": "token-pilot", - "version": "0.50.2", + "version": "0.51.0", "transport": { "type": "stdio" }, diff --git a/templates/agents/tp-api-surface-tracker.md b/templates/agents/tp-api-surface-tracker.md index 671a8b4..312f6ab 100644 --- a/templates/agents/tp-api-surface-tracker.md +++ b/templates/agents/tp-api-surface-tracker.md @@ -8,7 +8,7 @@ tools: - mcp__token-pilot__smart_diff - mcp__token-pilot__read_symbol - Bash -model: haiku +model: sonnet --- Role: public-API diff with semver classification. diff --git a/templates/agents/tp-dep-health.md b/templates/agents/tp-dep-health.md index 1eedc8b..77f5744 100644 --- a/templates/agents/tp-dep-health.md +++ b/templates/agents/tp-dep-health.md @@ -8,7 +8,7 @@ tools: - mcp__token-pilot__find_unused - Bash - Read -model: haiku +model: sonnet --- Role: dependency health audit. diff --git a/templates/agents/tp-doc-writer.md b/templates/agents/tp-doc-writer.md index c7b5995..a86cb91 100644 --- a/templates/agents/tp-doc-writer.md +++ b/templates/agents/tp-doc-writer.md @@ -12,7 +12,7 @@ tools: - Write - Edit - Glob -model: haiku +model: sonnet --- Role: documentation author — decisions, ADRs, READMEs, API docs. diff --git a/templates/agents/tp-incident-timeline.md b/templates/agents/tp-incident-timeline.md index 7b67e97..061d0f7 100644 --- a/templates/agents/tp-incident-timeline.md +++ b/templates/agents/tp-incident-timeline.md @@ -7,7 +7,7 @@ tools: - mcp__token-pilot__find_usages - mcp__token-pilot__read_symbol - Bash -model: inherit +model: sonnet --- Role: incident post-mortem timeline builder. diff --git a/templates/agents/tp-run.md b/templates/agents/tp-run.md index 2d9a0b6..63ab441 100644 --- a/templates/agents/tp-run.md +++ b/templates/agents/tp-run.md @@ -15,7 +15,7 @@ tools: - Grep - Glob - Bash -model: haiku +model: sonnet --- Role: general-purpose token-pilot workhorse.