token-pilot 0.28.2 → 0.29.0

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.2"
+    "version": "0.29.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. 22 MCP tools + 19 subagents + budget watchdog hooks.",
-      "version": "0.28.2",
+      "version": "0.29.0",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "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,73 @@ 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.29.0] - 2026-04-19
+
+Consolidation release based on Sonnet 4.6 + Opus 4.7 verification findings. Closes the short-tail issues that came out of the two live runs before the weekly-quota window reopens.
+
+### Added — context-mode partnership in shared preamble
+
+Both verification runs showed the same asymmetry: `token-pilot` saves on delegated (subagent) code reads; `context-mode` saves on main-thread Bash/command execution. Opus 4.7 literally wrote: "Во всей остальной работе использовал `ctx_batch_execute` вместо raw Bash — это adoption context-mode, не token-pilot". That's the right behaviour — we shouldn't fight it, we should formalise it.
+
+All 25 tp-* agents now carry an instruction in the shared preamble: *for heavy Bash (tests, builds, recursive searches, network calls), prefer `mcp__context-mode__execute` / `ctx_batch_execute` when available — runs in sandbox, only result enters context (95% reduction vs raw stdout)*. This is complementary, not redundant: token-pilot owns code reading, context-mode owns command execution.
+
+### Fixed — composite Bash escape patterns (from Opus 4.7 v0.28.2 report)
+
+Opus's verification noted that quoted / wrapped heavy commands slipped past our `PreToolUse:Bash` hook:
+
+- `bash -c "cat src/foo.ts"` → slipped
+- `sh -c "grep -r foo ."` → slipped
+- `eval "cat src/foo.ts"` → slipped
+- `for f in *.ts; do cat $f; done` → slipped
+- `while read f; do git log; done` → slipped
+
+Added `extractWrappedCommands()` in `src/hooks/pre-bash.ts` — unwraps `bash/sh/zsh -c "..."`, `eval "..."`, `for/while/until ... do BODY done` — and re-runs the heavy-pattern check on each inner body. First deny wins. Adds 7 regression tests covering both deny (heavy inside wrapper) and allow (benign inside wrapper — `bash -c "ls"`, `eval "echo hello"`).
+
+### Changed — honest tool descriptions for weak performers
+
+- `smart_log` description now carries a heads-up: "two verification runs measured this tool at ~39% token reduction (borderline). Cumulative data being gathered — tool may be dropped or redesigned in v0.30.0 if numbers don't improve". The description already advised scoping with `path` or `count`; kept.
+- `session_budget` re-framed as **META / info-only** — doesn't save tokens itself, purely diagnostic. This matches the META_TOOLS grouping in profiles (shipped in v0.28.1) and stops users thinking it's an optimisation tool.
+
+### Changed — composed-agent line budget 60 → 65
+
+Shared preamble now carries the context-mode paragraph — 3 extra lines flow into every composed agent file. Three agents (tp-context-engineer, tp-dead-code-finder, tp-doc-writer) ticked over the 60-line cap by 1-3 lines. Raised the hard limit to 65 to accommodate the new content without trimming per-agent instructions. 25 agents currently in the 38-63 range.
+
+### Deferred to v0.30.0
+
+- **Stop-hook output watchdog** — cap main-thread response size. Needs an experiment against Claude Code API first; too much new surface for a same-day patch.
+- **Automatic MCP response buffer** — intercept 3rd-party MCP (GitHub / Jira / Slack) responses via `updatedMCPToolOutput`. Biggest potential lever in the ecosystem, but a full feature, not a patch.
+- **`smart_log` final decision** — keep, redesign, or drop based on cumulative `tool-audit` data after a week of use.
+- **`explore_area` self-sizing** — v0.28.3 tightened the caps (20/500 → 10/200); next step is compare predicted output to `estimateExploreAreaWorkflowTokens` baseline and trim when exceeded.
+
+1026 tests passing (+7 new on composite Bash escape).
+
+## [0.28.3] - 2026-04-19
+
+### Fixed — `explore_area` output size (was −31% savings)
+
+Two independent live verification runs — Sonnet 4.6 on v0.28.1 and Opus 4.7 on v0.28.2, both on `docker-local-env` — measured `explore_area` at exactly **−31% savings**: 5,722 tokens returned against a 4,360-token baseline of reading the scanned files raw. That's the opposite of the tool's stated purpose. Root cause: imports analysis + tests listing + git-log tail accumulated on top of the directory outline, pushing the response above what the individual file-reads would have cost.
+
+Tightened two caps in `src/handlers/explore-area.ts`:
+
+| Constant | Before | After | Effect |
+|---|---:|---:|---|
+| `MAX_IMPORT_FILES` | 20 | **10** | imports panel scans half as many files |
+| `MAX_OUTPUT_LINES` | 500 | **200** | global response cap drops 60 % |
+
+The structural overview survives; the tail (detailed per-file imports past the top 10, git-log beyond the first screen) drops. Per-call smoke-test in the dev harness lands around +40–60 % savings, matching what the tool was supposed to deliver.
+
+Self-sizing (compare the predicted output against `estimateExploreAreaWorkflowTokens` baseline and trim if exceeded) deferred to v0.29.0 — needs handler + server coordination.
+
+### Noted for v0.29.0 (not this release)
+
+Composite Bash escape in `PreToolUse:Bash` hook:
+- `;` `&&` `||` `|` + newline separators → detected correctly (verified)
+- `bash -c "cat src/foo.ts"`, `eval "..."`, `for f in *.ts; do cat $f; done` → slip through (quoted / wrapped commands not lexed)
+
+Not shipping today because all three escape patterns require advanced shell knowledge and are rare in agent-generated commands. Opus 4.7's v0.28.2 verification confirmed 5/6 TP-blocked on realistic patterns. Fixing `bash -c` properly needs a small shell-tokenizer; worth a focused design pass, not a same-day patch.
+
+1019 tests still passing.
+
 ## [0.28.2] - 2026-04-19
 
 ### Fixed — plugin hooks were never actually reaching Claude Code

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

@@ -9,8 +9,8 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: f30fb3378463d6518041650487f1074b5411c6c3d6d7df315d21267f25f812d6
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: c9d33476fdf70c8a7a493ec8720f54792eda2f81585996246e94c130ff3ec356
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -19,6 +19,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: public-API diff with semver classification.

package/agents/tp-audit-scanner.md

@@ -11,8 +11,8 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 7095ffab66aca2e424f00875933e3f63bc10651eef2fde6a59f08bbbdbf86f7c
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -21,6 +21,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: audit scanner — surfaces risks, never fixes.

package/agents/tp-commit-writer.md

@@ -8,8 +8,8 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 559a0b61d20974bf33e35bc4c80dcf1b41d10d4df46cf9d05d3d5620713cd46f
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: b6831f11c61a9b255c2b6ffa04837130242fd02843463a7d30f109c1a06b3e3f
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -18,6 +18,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: commit-message authoring.

package/agents/tp-context-engineer.md

@@ -13,8 +13,8 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 8977f452021085a9ba63338bf94e8903e56b30e199dc32e41acc4ec3173a931d
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 43f9364ce722ff76daf0f8720ddaf9f77e18d4c4ed8bee3e15f12d207798e778
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -23,6 +23,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: curate what AI agents see so output quality stays high.

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

@@ -11,8 +11,8 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 33798b70002a206c4547d08ff46caefe6dbe5a9300f94ab5dad4a57ab5fb4478
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 386760aed26df6c3595d3267954605565fad08afa8761e016079ae60c19887a8
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -21,6 +21,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: safe dead-code detection.

package/agents/tp-debugger.md

@@ -12,8 +12,8 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: ada78a5a3f029721fa51e7cd203395ff0e87f0ab614cc7cf0d5bcc1bf9a80435
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 71738830d025e86c70988e046a2f7f30b4590f3d284291a18609ed5fdd732321
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -22,6 +22,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: bug diagnosis via systematic triage.

package/agents/tp-dep-health.md

@@ -9,8 +9,8 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 6224d989835ea284985b474005b8b46052b7007c4610e661b10658286b5c6624
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 12634cd28889d0a0ef1b4a6b994ba978353e14f3cb349011c393076e7e2b5c96
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -19,6 +19,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: dependency health audit.

package/agents/tp-doc-writer.md

@@ -13,8 +13,8 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 72347b06aaea75ed960972e96e2523c221b2ea7c892a3931aa0e7c32e4c86555
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 8e29d07dd8f58adeb9530ec477a59a6e42de6c624f322d2c6cfa8da66456b46a
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -23,6 +23,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: documentation author — decisions, ADRs, READMEs, API docs.

package/agents/tp-history-explorer.md

@@ -10,8 +10,8 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: b2daca007e959eaf26bf9a4d92ba36c3aa277a51de4ca4db674833d36acbe11b
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 260197bc31531352f5eda3b70cf114c7c57bb7e9373f68ca76161dd68a804b0d
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -20,6 +20,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: git-history archaeology — why, when, by whom.

package/agents/tp-impact-analyzer.md

@@ -12,8 +12,8 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 0be2620ce0303f912f6b3334f261d169f064970c0d16602fa1e76db4cb2ea441
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 1da6936cc117a7627640fae3cc85bf13a17f0b0b0d0d533423dfb4b7c0b4b1c2
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -22,6 +22,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: impact analysis.

package/agents/tp-incident-timeline.md

@@ -8,8 +8,8 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 420ffc423c7479a8d4e1b226cf73eb98d6d41388317c74a950d7f3b6240b6786
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 213746bab7acb6730a6edb16e1ff7b2c56572c3adf4f94990799f1c168cfa2ad
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -18,6 +18,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: incident post-mortem timeline builder.

package/agents/tp-incremental-builder.md

@@ -13,8 +13,8 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 9cb0bdf6e209d8ac613487385c01ef269d827dc3eddaf81b8eba581a3150b1e3
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 14c9adcabfb772c77a467a5fbfa682abbd5adc87e22d7fbe5d1329ffd790dde5
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -23,6 +23,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: incremental feature implementation with slice-by-slice discipline.

package/agents/tp-migration-scout.md

@@ -11,8 +11,8 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: cf32cdee777430ecc6732db32b3f883a685c8a02b6dc93379d71b15555e79b3e
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 62893e448e943d0e1b928a670823ec3e152de395e487564862f145bd82161fcb
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -21,6 +21,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: migration impact mapping.

package/agents/tp-onboard.md

@@ -10,8 +10,8 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 4e82f7b3c6446663e958fb6bf5eb5348bbdf33389269c888ce0dab766e50561f
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -20,6 +20,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: repository onboarding.

package/agents/tp-performance-profiler.md

@@ -11,8 +11,8 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 14b6fb4423a839c119120c2ea12c9dd6ab6ad1aeb13df1e7c22807b290cf1f9c
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 8b9f454a47e57e3761668de788850ef97d5d6f127b059cf8e0cef03deaca3f98
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -21,6 +21,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: performance diagnosis and targeted optimization.

package/agents/tp-pr-reviewer.md

@@ -11,8 +11,8 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 73ba5844c8354088dcb10c671622daecc0e8589568de15a6001e1cf951eea586
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 91003b244472c4e65d840b55474a86ce04fba379859d588cc0fa54850b0e1e4f
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -21,6 +21,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: PR / diff review across five axes.

package/agents/tp-refactor-planner.md

@@ -8,8 +8,8 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: dcc2c2aaeb443cc9688639b4337c6069b9d5bf21e3ed757fc8b3ac8a9d61bc03
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 45f972c6b36929491a529322bac3c34fd44872f7be4a974d25c7e27cb12e9dc3
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -18,6 +18,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: refactor planning with behaviour-preservation discipline.

package/agents/tp-review-impact.md

@@ -9,8 +9,8 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 72b635f511492188587d6cb6fd70f936ae34cf5df1f9cd9eff7849cf1231e185
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 3c1c66f952ac63a5936bec86fefda8c842fb9713bca81e48ca5bb568ccb5f367
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -19,6 +19,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: pre-merge blast-radius review.

package/agents/tp-run.md

@@ -16,8 +16,8 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: de342efe1e3ee265df1773ebde1241555750ab17de249190a5c1c200f1f8f51a
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -26,6 +26,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: general-purpose token-pilot workhorse.

package/agents/tp-session-restorer.md

@@ -9,8 +9,8 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: d031f30e9cc4ea454aa256427659ed27249d820b75dc8b9b99c81ba7635230a7
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -19,6 +19,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: session-state rehydration.

package/agents/tp-ship-coordinator.md

@@ -11,8 +11,8 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: e8f9c28da23e318328f5afd85b09e8e7b96e0dab21a4c6779ba798cd709ced64
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 6b1c27b3dc4fad622cebff7c49e079fc764ca0ae57ef5bc4e61b563d8321092d
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -21,6 +21,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: pre-production readiness coordinator.

package/agents/tp-spec-writer.md

@@ -9,8 +9,8 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: ed0b9f938c152c0d7be5a6a5eaf3c97c19b27ae4a9540aec342f0edb0927cb27
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 4ae44482db80a8a3a43794c6ecb665ec0b5385a274e1e5b2e3a404956075be88
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -19,6 +19,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: pre-code specification author.

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

@@ -10,8 +10,8 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: cc3d1f46fdb95ac3caf9344f69f1ddcd5ce5a175ee70aa150b7f9fda93edb152
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 6d862d1bcaeda3fb13099f51e40faaaf45d16d7d41d1b938609500192aa606f2
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -20,6 +20,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: test coverage gap finder.

package/agents/tp-test-triage.md

@@ -8,8 +8,8 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: f4e0dcbd2b4e8648efcafc9d53101a66bf394d7c90e97df7581ac47fcfbff5cb
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -18,6 +18,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: test-failure triage.

package/agents/tp-test-writer.md

@@ -13,8 +13,8 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.28.2"
-token_pilot_body_hash: 96211a3e7f6b52dd47fef286eec3584b1c269fb3464c1102f8b7edbe470700e6
+token_pilot_version: "0.29.0"
+token_pilot_body_hash: 960fe9e907e9c7d13b14dcc22af99e8cc7e7335f99791fa808df76ac21e1f5e9
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -23,6 +23,8 @@ For every file in a programming language, you MUST use the token-pilot MCP tools
 
 If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
 
+For heavy Bash operations (test runs, builds, recursive searches, network calls, any command with potentially large stdout): when `mcp__context-mode__execute` or `ctx_batch_execute` is available, use it instead of raw Bash. Context-mode runs commands in a sandbox and only the result enters your context — typically 95% token reduction vs raw stdout dump. This is complementary to token-pilot: we own code reading, context-mode owns command execution.
+
 Your specific role is defined below.
 
 Role: targeted test authoring with TDD discipline.

package/dist/handlers/explore-area.d.ts

@@ -1,5 +1,5 @@
-import type { AstIndexClient } from '../ast-index/client.js';
-import type { ExploreAreaArgs } from '../core/validation.js';
+import type { AstIndexClient } from "../ast-index/client.js";
+import type { ExploreAreaArgs } from "../core/validation.js";
 export interface ExploreAreaMeta {
     dir: string;
     codeFiles: string[];
@@ -11,7 +11,7 @@ export interface ExploreAreaMeta {
 }
 export declare function handleExploreArea(args: ExploreAreaArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
-        type: 'text';
+        type: "text";
         text: string;
     }>;
     meta: ExploreAreaMeta;

package/dist/handlers/explore-area.js

@@ -1,15 +1,22 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { readdir, stat } from 'node:fs/promises';
-import { resolve, relative, basename, dirname } from 'node:path';
-import { resolveSafePath } from '../core/validation.js';
-import { outlineDir, CODE_EXTENSIONS } from './outline.js';
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readdir, stat } from "node:fs/promises";
+import { resolve, relative, basename, dirname } from "node:path";
+import { resolveSafePath } from "../core/validation.js";
+import { outlineDir, CODE_EXTENSIONS } from "./outline.js";
 const execFileAsync = promisify(execFile);
 // ──────────────────────────────────────────────
 // Constants
 // ──────────────────────────────────────────────
-const MAX_IMPORT_FILES = 20;
-const MAX_OUTPUT_LINES = 500;
+// v0.28.3 — tightened from 20/500. Two independent verification runs
+// (Sonnet 4.6 + Opus 4.7 on docker-local-env) measured explore_area at
+// -31% savings — output was larger than reading scanned files raw.
+// Root cause: imports + tests + git log accumulated on top of the
+// directory outline. Halving both caps keeps the structural overview
+// while dropping the tail nobody actually reads. Self-sizing (compare
+// against baseline and trim if exceeded) deferred to v0.29.0.
+const MAX_IMPORT_FILES = 10;
+const MAX_OUTPUT_LINES = 200;
 // ──────────────────────────────────────────────
 // Handler
 // ──────────────────────────────────────────────
@@ -19,7 +26,7 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
     const pathStat = await stat(absPath).catch(() => null);
     if (!pathStat) {
         return {
-            content: [{ type: 'text', text: `Path "${args.path}" not found.` }],
+            content: [{ type: "text", text: `Path "${args.path}" not found.` }],
             meta: {
                 dir: args.path,
                 codeFiles: [],
@@ -34,28 +41,36 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
     if (!pathStat.isDirectory()) {
         absPath = dirname(absPath);
     }
-    const relDir = relative(projectRoot, absPath) || '.';
-    const include = args.include ?? ['outline', 'imports', 'tests', 'changes'];
+    const relDir = relative(projectRoot, absPath) || ".";
+    const include = args.include ?? ["outline", "imports", "tests", "changes"];
     // Collect code files for import/test analysis
     const codeFiles = await listCodeFiles(absPath);
     // Run all sections in parallel
     const [outlineSection, importsSection, testsSection, changesSection] = await Promise.allSettled([
-        include.includes('outline') ? buildOutlineSection(absPath, projectRoot, astIndex) : Promise.resolve(null),
-        include.includes('imports') ? buildImportsSection(codeFiles, absPath, projectRoot, astIndex) : Promise.resolve(null),
-        include.includes('tests') ? buildTestsSection(codeFiles, absPath, projectRoot) : Promise.resolve(null),
-        include.includes('changes') ? buildChangesSection(relDir, projectRoot) : Promise.resolve(null),
+        include.includes("outline")
+            ? buildOutlineSection(absPath, projectRoot, astIndex)
+            : Promise.resolve(null),
+        include.includes("imports")
+            ? buildImportsSection(codeFiles, absPath, projectRoot, astIndex)
+            : Promise.resolve(null),
+        include.includes("tests")
+            ? buildTestsSection(codeFiles, absPath, projectRoot)
+            : Promise.resolve(null),
+        include.includes("changes")
+            ? buildChangesSection(relDir, projectRoot)
+            : Promise.resolve(null),
     ]);
     // Assemble output
     const lines = [];
     const subdirCount = await countSubdirs(absPath);
-    lines.push(`AREA: ${relDir}/ (${codeFiles.length} code files${subdirCount > 0 ? `, ${subdirCount} subdirs` : ''})`);
-    lines.push('');
+    lines.push(`AREA: ${relDir}/ (${codeFiles.length} code files${subdirCount > 0 ? `, ${subdirCount} subdirs` : ""})`);
+    lines.push("");
     // Outline
     const outlineLines = extractResult(outlineSection);
     if (outlineLines) {
-        lines.push('STRUCTURE:');
+        lines.push("STRUCTURE:");
         lines.push(...outlineLines);
-        lines.push('');
+        lines.push("");
     }
     // Imports
     const importLines = extractResult(importsSection)?.lines ?? null;
@@ -75,11 +90,11 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
     // Truncate if needed
     if (lines.length > MAX_OUTPUT_LINES) {
         lines.length = MAX_OUTPUT_LINES;
-        lines.push('... truncated. Use outline() on specific subdirectories for details.');
+        lines.push("... truncated. Use outline() on specific subdirectories for details.");
     }
-    lines.push('HINT: Use smart_read(file) for details, read_symbol(path, symbol) for source code, find_usages(symbol) for references.');
+    lines.push("HINT: Use smart_read(file) for details, read_symbol(path, symbol) for source code, find_usages(symbol) for references.");
     return {
-        content: [{ type: 'text', text: lines.join('\n') }],
+        content: [{ type: "text", text: lines.join("\n") }],
         meta: {
             dir: relDir,
             codeFiles: codeFiles.map((file) => relative(projectRoot, file)).sort(),
@@ -103,43 +118,47 @@ async function buildOutlineSection(absPath, projectRoot, astIndex) {
 // Imports section — aggregate external deps + who imports this area
 // ──────────────────────────────────────────────
 async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
-    if (!astIndex.isAvailable() || astIndex.isDisabled() || astIndex.isOversized()) {
+    if (!astIndex.isAvailable() ||
+        astIndex.isDisabled() ||
+        astIndex.isOversized()) {
         return { lines: [], internalDeps: [], importedBy: [], externalDeps: [] };
     }
     const filesToAnalyze = codeFiles.slice(0, MAX_IMPORT_FILES);
     const externalDeps = new Set();
     const internalDeps = new Set();
-    const relDir = relative(projectRoot, absPath) || '.';
+    const relDir = relative(projectRoot, absPath) || ".";
     // Get imports for each file
-    const importResults = await Promise.allSettled(filesToAnalyze.map(f => astIndex.fileImports(f)));
+    const importResults = await Promise.allSettled(filesToAnalyze.map((f) => astIndex.fileImports(f)));
     for (const result of importResults) {
-        if (result.status !== 'fulfilled' || !result.value)
+        if (result.status !== "fulfilled" || !result.value)
             continue;
         for (const imp of result.value) {
             const source = imp.source;
             if (!source)
                 continue;
-            if (source.startsWith('.') || source.startsWith('/')) {
+            if (source.startsWith(".") || source.startsWith("/")) {
                 // Internal import — track if it's outside this area
                 const resolved = resolve(absPath, source);
-                if (!resolved.startsWith(absPath + '/') && resolved !== absPath) {
-                    const relImport = relative(projectRoot, resolved).replace(/\.[^.]+$/, '');
+                if (!resolved.startsWith(absPath + "/") && resolved !== absPath) {
+                    const relImport = relative(projectRoot, resolved).replace(/\.[^.]+$/, "");
                     internalDeps.add(relImport);
                 }
             }
             else {
                 // External package
-                const pkg = source.startsWith('@') ? source.split('/').slice(0, 2).join('/') : source.split('/')[0];
+                const pkg = source.startsWith("@")
+                    ? source.split("/").slice(0, 2).join("/")
+                    : source.split("/")[0];
                 externalDeps.add(pkg);
             }
         }
     }
     // Find who imports files from this area (reverse dependencies)
     const importedBy = new Set();
-    const fileBasenames = filesToAnalyze.map(f => basename(f).replace(/\.[^.]+$/, ''));
-    const refResults = await Promise.allSettled(fileBasenames.slice(0, 10).map(name => astIndex.refs(name, 10)));
+    const fileBasenames = filesToAnalyze.map((f) => basename(f).replace(/\.[^.]+$/, ""));
+    const refResults = await Promise.allSettled(fileBasenames.slice(0, 10).map((name) => astIndex.refs(name, 10)));
     for (const result of refResults) {
-        if (result.status !== 'fulfilled' || !result.value)
+        if (result.status !== "fulfilled" || !result.value)
             continue;
         const refs = result.value;
         if (refs.imports) {
@@ -149,8 +168,8 @@ async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
                     continue;
                 const relFile = relative(projectRoot, impFile);
                 // Only include files outside this area
-                if (!relFile.startsWith(relDir + '/') && relFile !== relDir) {
-                    importedBy.add(relFile.replace(/\.[^.]+$/, ''));
+                if (!relFile.startsWith(relDir + "/") && relFile !== relDir) {
+                    importedBy.add(relFile.replace(/\.[^.]+$/, ""));
                 }
             }
         }
@@ -158,18 +177,18 @@ async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
     const lines = [];
     if (externalDeps.size > 0) {
         const deps = Array.from(externalDeps).sort().slice(0, 20);
-        lines.push(`IMPORTS: ${deps.join(', ')}${externalDeps.size > 20 ? ` ... (${externalDeps.size} total)` : ''}`);
+        lines.push(`IMPORTS: ${deps.join(", ")}${externalDeps.size > 20 ? ` ... (${externalDeps.size} total)` : ""}`);
     }
     if (internalDeps.size > 0) {
         const deps = Array.from(internalDeps).sort().slice(0, 10);
-        lines.push(`INTERNAL DEPS: ${deps.join(', ')}${internalDeps.size > 10 ? ` ... (${internalDeps.size} total)` : ''}`);
+        lines.push(`INTERNAL DEPS: ${deps.join(", ")}${internalDeps.size > 10 ? ` ... (${internalDeps.size} total)` : ""}`);
     }
     if (importedBy.size > 0) {
         const importers = Array.from(importedBy).sort().slice(0, 10);
-        lines.push(`IMPORTED BY: ${importers.join(', ')}${importedBy.size > 10 ? ` ... (${importedBy.size} total)` : ''}`);
+        lines.push(`IMPORTED BY: ${importers.join(", ")}${importedBy.size > 10 ? ` ... (${importedBy.size} total)` : ""}`);
     }
     if (lines.length > 0)
-        lines.push('');
+        lines.push("");
     return {
         lines,
         internalDeps: Array.from(internalDeps).sort(),
@@ -182,18 +201,18 @@ async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
 // ──────────────────────────────────────────────
 async function buildTestsSection(codeFiles, absPath, projectRoot) {
     const testFiles = [];
-    const areaFileNames = new Set(codeFiles.map(f => basename(f).replace(/\.[^.]+$/, '')));
+    const areaFileNames = new Set(codeFiles.map((f) => basename(f).replace(/\.[^.]+$/, "")));
     // Scan for test files: check area dir + common test dirs
     const dirsToScan = [absPath];
     // Check for sibling __tests__ or tests directory
     const parent = dirname(absPath);
     const areaName = basename(absPath);
     const testDirCandidates = [
-        resolve(absPath, '__tests__'),
-        resolve(absPath, 'tests'),
-        resolve(absPath, 'test'),
-        resolve(parent, '__tests__', areaName),
-        resolve(parent, 'tests', areaName),
+        resolve(absPath, "__tests__"),
+        resolve(absPath, "tests"),
+        resolve(absPath, "test"),
+        resolve(parent, "__tests__", areaName),
+        resolve(parent, "tests", areaName),
     ];
     for (const testDir of testDirCandidates) {
         const testDirStat = await stat(testDir).catch(() => null);
@@ -203,9 +222,9 @@ async function buildTestsSection(codeFiles, absPath, projectRoot) {
     }
     // Also check project-level test directories
     const projectTestDirs = [
-        resolve(projectRoot, 'tests'),
-        resolve(projectRoot, 'test'),
-        resolve(projectRoot, '__tests__'),
+        resolve(projectRoot, "tests"),
+        resolve(projectRoot, "test"),
+        resolve(projectRoot, "__tests__"),
     ];
     for (const testDir of projectTestDirs) {
         if (dirsToScan.includes(testDir))
@@ -222,12 +241,15 @@ async function buildTestsSection(codeFiles, absPath, projectRoot) {
                 if (!entry.isFile())
                     continue;
                 const name = entry.name;
-                if (name.includes('.test.') || name.includes('.spec.') || name.includes('_test.') || name.includes('_spec.')) {
+                if (name.includes(".test.") ||
+                    name.includes(".spec.") ||
+                    name.includes("_test.") ||
+                    name.includes("_spec.")) {
                     // Check if this test corresponds to an area file
                     const testBase = name
-                        .replace(/\.(test|spec)\./, '.')
-                        .replace(/_(test|spec)\./, '.')
-                        .replace(/\.[^.]+$/, '');
+                        .replace(/\.(test|spec)\./, ".")
+                        .replace(/_(test|spec)\./, ".")
+                        .replace(/\.[^.]+$/, "");
                     if (areaFileNames.has(testBase) || dir !== absPath) {
                         const relPath = relative(projectRoot, resolve(dir, name));
                         if (!testFiles.includes(relPath)) {
@@ -237,13 +259,15 @@ async function buildTestsSection(codeFiles, absPath, projectRoot) {
                 }
             }
         }
-        catch { /* skip unreadable dirs */ }
+        catch {
+            /* skip unreadable dirs */
+        }
     }
     if (testFiles.length === 0)
         return { lines: [], testFiles: [] };
     const lines = [];
-    lines.push(`TESTS: ${testFiles.join(', ')}`);
-    lines.push('');
+    lines.push(`TESTS: ${testFiles.join(", ")}`);
+    lines.push("");
     return { lines, testFiles: [...testFiles].sort() };
 }
 // ──────────────────────────────────────────────
@@ -251,16 +275,16 @@ async function buildTestsSection(codeFiles, absPath, projectRoot) {
 // ──────────────────────────────────────────────
 async function buildChangesSection(relDir, projectRoot) {
     try {
-        const { stdout } = await execFileAsync('git', ['log', '--oneline', '-5', '--', relDir], { cwd: projectRoot, timeout: 5000 });
+        const { stdout } = await execFileAsync("git", ["log", "--oneline", "-5", "--", relDir], { cwd: projectRoot, timeout: 5000 });
         if (!stdout.trim())
             return { lines: [], count: 0 };
         const lines = [];
-        const commits = stdout.trim().split('\n');
-        lines.push('RECENT CHANGES:');
+        const commits = stdout.trim().split("\n");
+        lines.push("RECENT CHANGES:");
         for (const line of commits) {
             lines.push(`  ${line}`);
         }
-        lines.push('');
+        lines.push("");
         return { lines, count: commits.length };
     }
     catch {
@@ -271,7 +295,7 @@ async function buildChangesSection(relDir, projectRoot) {
 // Helpers
 // ──────────────────────────────────────────────
 function extractResult(settled) {
-    if (settled.status === 'fulfilled' && settled.value) {
+    if (settled.status === "fulfilled" && settled.value) {
         return settled.value;
     }
     return null;
@@ -282,7 +306,7 @@ async function listCodeFiles(dirPath) {
         const files = [];
         for (const entry of entries) {
             if (entry.isFile()) {
-                const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+                const ext = entry.name.split(".").pop()?.toLowerCase() ?? "";
                 if (CODE_EXTENSIONS.has(ext)) {
                     files.push(resolve(dirPath, entry.name));
                 }
@@ -297,7 +321,7 @@ async function listCodeFiles(dirPath) {
 async function countSubdirs(dirPath) {
     try {
         const entries = await readdir(dirPath, { withFileTypes: true });
-        return entries.filter(e => e.isDirectory()).length;
+        return entries.filter((e) => e.isDirectory()).length;
     }
     catch {
         return 0;

package/dist/hooks/pre-bash.d.ts

@@ -37,6 +37,17 @@ export type PreBashDecision = {
     kind: "deny";
     reason: string;
 };
+/**
+ * v0.29.0 — expose wrapped commands. Opus 4.7's v0.28.2 verification
+ * report showed escape patterns: `bash -c "cat src/foo.ts"`,
+ * `eval "..."`, `for f in *.ts; do cat $f; done` all slipped through
+ * our heuristics because the dangerous call sat inside quotes / a loop
+ * body. Unwrap those before matching.
+ *
+ * Returns the original command PLUS the extracted inner body for each
+ * wrapper found. Duplication is fine — detectHeavyPattern is pure.
+ */
+export declare function extractWrappedCommands(command: string): string[];
 export declare function detectHeavyPattern(command: string): PreBashDecision;
 export declare function decidePreBash(input: PreBashInput): PreBashDecision;
 export declare function renderPreBashOutput(decision: PreBashDecision): string | null;

package/dist/hooks/pre-bash.js

@@ -32,7 +32,60 @@ function invokes(command, utility) {
     const re = new RegExp(`(^|[;&|\\n]\\s*)${utility}(\\s|$)`, "m");
     return re.test(command);
 }
+/**
+ * v0.29.0 — expose wrapped commands. Opus 4.7's v0.28.2 verification
+ * report showed escape patterns: `bash -c "cat src/foo.ts"`,
+ * `eval "..."`, `for f in *.ts; do cat $f; done` all slipped through
+ * our heuristics because the dangerous call sat inside quotes / a loop
+ * body. Unwrap those before matching.
+ *
+ * Returns the original command PLUS the extracted inner body for each
+ * wrapper found. Duplication is fine — detectHeavyPattern is pure.
+ */
+export function extractWrappedCommands(command) {
+    const out = [command];
+    // bash -c "..." / sh -c "..." / zsh -c "..."
+    for (const shell of ["bash", "sh", "zsh"]) {
+        const re = new RegExp(`\\b${shell}\\s+-c\\s+(?:"([^"]+)"|'([^']+)')`, "g");
+        for (const m of command.matchAll(re)) {
+            const inner = m[1] ?? m[2];
+            if (inner)
+                out.push(inner);
+        }
+    }
+    // eval "..." / eval '...'
+    for (const m of command.matchAll(/\beval\s+(?:"([^"]+)"|'([^']+)')/g)) {
+        const inner = m[1] ?? m[2];
+        if (inner)
+            out.push(inner);
+    }
+    // for LOOP with body: `for X in Y; do BODY; done` — extract BODY
+    // Also covers `while COND; do BODY; done` and `until COND; do BODY; done`
+    for (const m of command.matchAll(/\b(?:for|while|until)\b[^;]*;\s*do\s+(.+?)\s*;?\s*done\b/gs)) {
+        const body = m[1];
+        if (body)
+            out.push(body);
+    }
+    return out;
+}
 export function detectHeavyPattern(command) {
+    const cmd = command.trim();
+    if (!cmd)
+        return { kind: "allow" };
+    // v0.29.0: check each of the original + any unwrapped inner commands.
+    // First deny wins.
+    const candidates = extractWrappedCommands(cmd);
+    if (candidates.length > 1) {
+        // Check only the unwrapped inners; the original is handled below.
+        for (let i = 1; i < candidates.length; i++) {
+            const inner = detectHeavyPatternSingle(candidates[i]);
+            if (inner.kind === "deny")
+                return inner;
+        }
+    }
+    return detectHeavyPatternSingle(cmd);
+}
+function detectHeavyPatternSingle(command) {
     const cmd = command.trim();
     if (!cmd)
         return { kind: "allow" };

package/dist/server/tool-definitions.js

@@ -499,7 +499,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "smart_log",
-        description: "Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref.",
+        description: "Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref. HEADS UP: two verification runs measured this tool at ~39% token reduction (borderline — vs 95-99% for outline/smart_diff). Cumulative data being gathered — tool may be dropped or redesigned in v0.30.0 if numbers don't improve. Prefer scoping with `path` or `count` to tighten savings.",
         inputSchema: {
             type: "object",
             properties: {
@@ -581,7 +581,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "session_budget",
-        description: "Report Read-hook pressure for this session: suppressed tokens so far, reference budget, burn fraction (0..1), and the effective denyThreshold the adaptive curve would apply right now. NOTE: burnFraction measures hook activity, not actual context-window occupancy. Useful to decide when to tighten further before a big read.",
+        description: "META / info-only: reports Read-hook pressure for this session (suppressed tokens, reference budget, burn fraction, effective denyThreshold). Does NOT save tokens itself — this is diagnostic, use to decide when to tighten before a big read. NOTE: burnFraction measures hook activity, not actual context-window occupancy.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.28.2",
+  "version": "0.29.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",