Digital-Threads · Shahinyanm · Jul 26, 2026 · Jul 26, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -12,7 +12,7 @@ tools:
   - Write
   - Edit
   - Glob
-model: haiku
+model: sonnet
 ---
 
 Role: documentation author — decisions, ADRs, READMEs, API docs.
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,7 +12,7 @@ tools: @@
       - Write
       - Edit
       - Glob
-    model: haiku
+    model: sonnet
     ---
     Role: documentation author — decisions, ADRs, READMEs, API docs.
@@ Expand Down @@