token-pilot 0.28.3 → 0.30.0

package/dist/server/tool-profiles.js

@@ -25,6 +25,7 @@ export const PROFILE_NAMES = [
     "full",
     "nav",
     "edit",
+    "minimal",
 ];
 /**
  * Meta-tools — diagnostic / self-observation tools that must be visible
@@ -37,6 +38,18 @@ export const META_TOOLS = new Set([
     "session_budget",
     "session_snapshot",
 ]);
+/**
+ * Minimal profile — 5 core tools for emergency / context-constrained sessions.
+ * Token overhead: tools/list is tiny; instructions are ~80 tokens vs ~350 for full.
+ * Use TOKEN_PILOT_PROFILE=minimal when the agent's context budget is nearly full.
+ */
+export const MINIMAL_TOOLS = new Set([
+    "smart_read",
+    "read_symbol",
+    "find_usages",
+    "smart_diff",
+    "smart_log",
+]);
 /** Minimum nav profile — exploration only, no editing support. */
 export const NAV_TOOLS = new Set([
     "smart_read",
@@ -49,6 +62,7 @@ export const NAV_TOOLS = new Set([
     "explore_area",
     "smart_log",
     "smart_diff",
+    "read_section", // v0.30.0: section reading is nav-class (read-only, no edit prep)
 ]);
 /** Edit profile adds batch reads + edit-preparation tools. */
 export const EDIT_EXTRAS = new Set([
@@ -73,6 +87,11 @@ export function filterToolsByProfile(tools, profile) {
     // session_snapshot are the instruments for verifying the profile is
     // doing its job. Hiding them would turn "did this save tokens?" into
     // a guess.
+    if (profile === "minimal") {
+        // Minimal: 5 core tools only. META excluded — keep the footprint tiny.
+        // The agent can still call session_analytics by name if it knows it.
+        return tools.filter((t) => MINIMAL_TOOLS.has(t.name));
+    }
     if (profile === "nav") {
         return tools.filter((t) => NAV_TOOLS.has(t.name) || META_TOOLS.has(t.name));
     }
@@ -85,14 +104,29 @@ export function filterToolsByProfile(tools, profile) {
  * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning
  * and fall back to full — we never silently apply a guess.
  */
+/**
+ * Parse the TOKEN_PILOT_PROFILE env value.
+ *
+ * Default changed in v0.30.0: full → edit.
+ * Rationale: 'full' was exposing 22 tools + full instruction set on every
+ * session, burning ~3 k tokens before any work. 'edit' covers 99% of
+ * development workflows (reading + writing code). Switch to 'full' only
+ * when you need audit tools (code_audit, find_unused, test_summary).
+ *
+ * Unknown values fall back to 'edit' with a stderr warning — we never
+ * silently apply a guess.
+ */
 export function parseProfileEnv(envValue, warn = () => { }) {
     if (!envValue)
-        return "full";
+        return "edit";
     const lower = envValue.trim().toLowerCase();
-    if (lower === "full" || lower === "nav" || lower === "edit") {
+    if (lower === "full" ||
+        lower === "nav" ||
+        lower === "edit" ||
+        lower === "minimal") {
         return lower;
     }
-    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit. Falling back to full.`);
-    return "full";
+    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit|minimal. Falling back to edit.`);
+    return "edit";
 }
 //# sourceMappingURL=tool-profiles.js.map

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type EnforcementMode } from "./server/enforcement-mode.js";
 export declare function createServer(projectRoot: string, options?: {
     skipAstIndex?: boolean;
+    enforcementMode?: EnforcementMode;
 }): Promise<Server<{
     method: string;
     params?: {

package/dist/server.js

@@ -45,11 +45,13 @@ import { detectContextMode } from "./integration/context-mode-detector.js";
 import { estimateTokens } from "./core/token-estimator.js";
 import { checkPolicy, isFullReadTool } from "./core/policy-engine.js";
 import { appendToolCall } from "./core/tool-call-log.js";
-import { MCP_INSTRUCTIONS, TOOL_DEFINITIONS, } from "./server/tool-definitions.js";
+import { getMcpInstructions, TOOL_DEFINITIONS, } from "./server/tool-definitions.js";
 import { filterToolsByProfile, parseProfileEnv, } from "./server/tool-profiles.js";
+import { STRICT_SMART_READ_MAX_TOKENS, STRICT_EXPLORE_AREA_INCLUDE, } from "./server/enforcement-mode.js";
 import { createTokenEstimates } from "./server/token-estimates.js";
 import { validateSmartReadArgs, validateReadSymbolArgs, validateReadSymbolsArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, validateReadSectionArgs, } from "./core/validation.js";
 export async function createServer(projectRoot, options) {
+    const mode = options?.enforcementMode ?? "deny";
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
         binaryPath: config.astIndex.binaryPath,
@@ -193,7 +195,6 @@ export async function createServer(projectRoot, options) {
     let fullFileReadsCount = 0;
     let totalCallCount = 0;
     let totalTokensReturned = 0;
-    const readForEditCalled = new Set();
     // Detect context-mode companion
     const cmEnabled = config.contextMode.enabled;
     const contextModeStatus = await detectContextMode(projectRoot, cmEnabled === "auto" ? undefined : cmEnabled);
@@ -238,18 +239,20 @@ export async function createServer(projectRoot, options) {
     catch {
         /* fallback to hardcoded */
     }
+    // v0.26.3 — tool profiles. TOKEN_PILOT_PROFILE=nav|edit|full|minimal
+    // (default: edit since v0.30.0) trims the advertised tools/list payload.
+    // Handlers stay live, so a subagent that explicitly names a filtered-out
+    // tool still gets a response — we just don't brag about every tool upfront.
+    // v0.30.0 — profile also selects matching MCP instructions so the agent
+    // doesn't see rules for tools that aren't in its tools/list.
+    const activeProfile = parseProfileEnv(process.env.TOKEN_PILOT_PROFILE, (m) => process.stderr.write(m + "\n"));
     const server = new Server({ name: "token-pilot", version: pkgVersion }, {
         capabilities: { tools: {} },
-        instructions: MCP_INSTRUCTIONS,
+        instructions: getMcpInstructions(activeProfile),
     });
-    // v0.26.3 — tool profiles. TOKEN_PILOT_PROFILE=nav|edit|full (default
-    // full) trims the advertised tools/list payload. Handlers stay live,
-    // so a subagent that explicitly names a filtered-out tool still gets
-    // a response — we just don't brag about every tool upfront.
-    const activeProfile = parseProfileEnv(process.env.TOKEN_PILOT_PROFILE, (m) => process.stderr.write(m + "\n"));
     const advertisedTools = filterToolsByProfile(TOOL_DEFINITIONS, activeProfile);
-    if (activeProfile !== "full") {
-        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools. Unset TOKEN_PILOT_PROFILE for the full set.\n`);
+    if (activeProfile !== "edit") {
+        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools. Set TOKEN_PILOT_PROFILE=edit for the default set.\n`);
     }
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: advertisedTools,
@@ -289,14 +292,10 @@ export async function createServer(projectRoot, options) {
         if (isFullReadTool(rest.tool)) {
             fullFileReadsCount++;
         }
-        if (rest.tool === "read_for_edit" && call.path) {
-            readForEditCalled.add(call.path);
-        }
         // Policy check
         const advisory = checkPolicy(config.policies, rest.tool, {
             fullFileReadsCount,
             tokensReturned: rest.tokensReturned,
-            readForEditCalled,
             totalCallCount,
             totalTokensReturned,
         });
@@ -331,6 +330,14 @@ export async function createServer(projectRoot, options) {
             switch (name) {
                 case "smart_read": {
                     const validArgs = validateSmartReadArgs(args);
+                    // v0.30.0 strict mode: cap max_tokens when caller didn't set it.
+                    let strictReadCapNote;
+                    if (mode === "strict" && validArgs.max_tokens === undefined) {
+                        validArgs.max_tokens = STRICT_SMART_READ_MAX_TOKENS;
+                        strictReadCapNote =
+                            `\n\n[token-pilot strict] Output capped at ${STRICT_SMART_READ_MAX_TOKENS} tokens ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass max_tokens explicitly to override.`;
+                    }
                     const picked = pickRegistry(args);
                     // Try non-code handler for JSON/YAML/MD etc.
                     if (isNonCodeStructured(validArgs.path)) {
@@ -373,8 +380,9 @@ export async function createServer(projectRoot, options) {
                         absPath: resolve(projectRoot, validArgs.path),
                         args: validArgs,
                     });
-                    if (policyAdv)
-                        result.content[0] = { type: "text", text: text + policyAdv };
+                    const srSuffix = (policyAdv ?? "") + (strictReadCapNote ?? "");
+                    if (srSuffix)
+                        result.content[0] = { type: "text", text: text + srSuffix };
                     return result;
                 }
                 case "read_symbol": {
@@ -527,6 +535,15 @@ export async function createServer(projectRoot, options) {
                 }
                 case "find_usages": {
                     const usagesArgs = validateFindUsagesArgs(args);
+                    // v0.30.0 strict mode: default mode to "list" when caller didn't set it.
+                    // Injected before cache lookup so the key matches strict-mode cached results.
+                    let strictFuNote;
+                    if (mode === "strict" && usagesArgs.mode === undefined) {
+                        usagesArgs.mode = "list";
+                        strictFuNote =
+                            `\n\n[token-pilot strict] find_usages mode defaulted to "list" ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass mode explicitly to override.`;
+                    }
                     const cachedUsages = sessionCache?.get("find_usages", usagesArgs);
                     if (cachedUsages) {
                         recordWithTrace({
@@ -558,6 +575,12 @@ export async function createServer(projectRoot, options) {
                         savingsCategory: "compression",
                         args: usagesArgs,
                     });
+                    if (strictFuNote && usagesResult.content[0]) {
+                        usagesResult.content[0] = {
+                            type: "text",
+                            text: usagesText + strictFuNote,
+                        };
+                    }
                     return usagesResult;
                 }
                 case "project_overview": {
@@ -801,6 +824,15 @@ export async function createServer(projectRoot, options) {
                 }
                 case "explore_area": {
                     const eaArgs = validateExploreAreaArgs(args);
+                    // v0.30.0 strict mode: default include to outline-only when caller didn't set it.
+                    // Injected before cache lookup so the key matches strict-mode cached results.
+                    let strictEaCapNote;
+                    if (mode === "strict" && eaArgs.include === undefined) {
+                        eaArgs.include = STRICT_EXPLORE_AREA_INCLUDE;
+                        strictEaCapNote =
+                            `\n\n[token-pilot strict] include defaulted to ["outline"] ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass include explicitly to override.`;
+                    }
                     const cachedEa = sessionCache?.get("explore_area", eaArgs);
                     if (cachedEa) {
                         recordWithTrace({
@@ -833,10 +865,24 @@ export async function createServer(projectRoot, options) {
                         savingsCategory: "compression",
                         args: eaArgs,
                     });
+                    if (strictEaCapNote && eaResult.content[0]) {
+                        eaResult.content[0] = {
+                            type: "text",
+                            text: eaText + strictEaCapNote,
+                        };
+                    }
                     return eaResult;
                 }
                 case "smart_log": {
                     const slArgs = validateSmartLogArgs(args);
+                    // v0.30.0 strict mode: bound count to 20 when caller didn't set it.
+                    let strictSlNote;
+                    if (mode === "strict" && slArgs.count === undefined) {
+                        slArgs.count = 20;
+                        strictSlNote =
+                            `\n\n[token-pilot strict] smart_log count defaulted to 20 ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass count explicitly to override.`;
+                    }
                     const slResult = await handleSmartLog(slArgs, projectRoot);
                     const slText = slResult.content[0]?.text ?? "";
                     const slTokens = estimateTokens(slText);
@@ -849,6 +895,12 @@ export async function createServer(projectRoot, options) {
                         savingsCategory: "compression",
                         args: slArgs,
                     });
+                    if (strictSlNote && slResult.content[0]) {
+                        slResult.content[0] = {
+                            type: "text",
+                            text: slText + strictSlNote,
+                        };
+                    }
                     return { content: slResult.content };
                 }
                 case "test_summary": {

package/docs/agents.md

@@ -0,0 +1,82 @@
+# tp-* Subagents (Claude Code only)
+
+`tp-*` subagents are a Claude Code feature. Other clients get the MCP tools + hooks but cannot invoke subagents. Each agent carries an explicit `model:` field in its frontmatter; the budget is enforced post-response — overshoots beyond 10% land in `.token-pilot/over-budget.log`.
+
+## Installation
+
+```bash
+npx token-pilot install-agents --scope=user            # all projects
+npx token-pilot install-agents --scope=project         # this repo only
+npx token-pilot install-agents --scope=user --force    # re-apply after an update
+npx token-pilot uninstall-agents --scope=user|project
+```
+
+`init` offers to install these; to add them to another project run `npx token-pilot install-agents`.
+
+## Tier 1 — Workhorses (invoke proactively)
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-run` | General MCP-first workhorse; use when no specialised agent fits | 800 |
+| `tp-onboard` | Orient to an unfamiliar repo (layout, entry points, modules) | 600 |
+| `tp-pr-reviewer` | Review a diff / PR / changeset; verdict-first, Critical/Important tiers | 600 |
+| `tp-impact-analyzer` | Trace blast-radius of a change (callers, transitive deps) | 400 |
+| `tp-refactor-planner` | Plan a refactor with exact edit context per step | 500 |
+| `tp-test-triage` | Investigate test failures → root cause → minimal fix | 500 |
+
+## Tier 2 — Specialists
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-debugger` | Stack trace / error → root-cause line via call-tree traversal | 700 |
+| `tp-migration-scout` | Pre-migration impact map grouped by effort class | 800 |
+| `tp-test-writer` | Write tests for ONE symbol, mirrors project style, runs tests | 900 |
+| `tp-dead-code-finder` | Cross-checked dead-code detection, output-only (never deletes) | 600 |
+| `tp-commit-writer` | Draft Conventional-Commit from staged diff; refuses failing tests | 400 |
+| `tp-history-explorer` | "Why is this like this?" — minimum commit chain explaining current state | 600 |
+| `tp-audit-scanner` | Read-only security / quality audit; Critical / Important / Minor findings | 800 |
+| `tp-session-restorer` | Rehydrate state after /clear or compaction from latest snapshot | 400 |
+
+## Tier 3 — Combo / Workflow
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-review-impact` | Pre-merge blast-radius review (diff × dependents × API surface) | 700 |
+| `tp-test-coverage-gapper` | Find symbols with zero test references, prioritised | 500 |
+| `tp-api-surface-tracker` | Public API diff vs last release → MAJOR / MINOR / PATCH verdict | 600 |
+| `tp-dep-health` | Dep audit: stale × heavily-used × removable | 600 |
+| `tp-incident-timeline` | Correlate an incident window with commits, rank likely culprits | 700 |
+
+## Tier 4 — Methodology
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-context-engineer` | Audit / write CLAUDE.md / AGENTS.md rules files per project | 800 |
+| `tp-spec-writer` | Pre-code spec with gated workflow; surfaces assumptions before code | 900 |
+| `tp-performance-profiler` | Measure → identify → fix → verify → guard; refuses to optimise without data | 800 |
+| `tp-incremental-builder` | Multi-file feature work in thin vertical slices, test between each | 900 |
+| `tp-doc-writer` | ADRs + READMEs + API docs; documents *why* not *what* | 700 |
+| `tp-ship-coordinator` | 5-pillar pre-launch checklist (quality / security / observability / rollback / rollout) | 800 |
+
+## Model Tiers
+
+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`) |
+
+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.
+
+## Third-party Agent Integration (bless-agents)
+
+For third-party agents (e.g. `acc-*` plugins) whose tool allowlist excludes token-pilot MCP:
+
+```bash
+npx token-pilot bless-agents       # add token-pilot MCP to project-level overrides
+npx token-pilot unbless-agents <name>... | --all
+```
+
+`doctor` warns when the original agent has changed since blessing.

package/docs/configuration.md

@@ -0,0 +1,117 @@
+# Configuration & Tool Profiles
+
+## .token-pilot.json
+
+Drop `.token-pilot.json` in your project root. All fields are optional.
+
+```json
+{
+  "hooks": { "mode": "deny-enhanced", "denyThreshold": 300 },
+  "sessionStart": { "enabled": true, "showStats": false, "maxReminderTokens": 250 },
+  "agents": { "scope": null, "reminder": true },
+  "smartRead": { "smallFileThreshold": 200 },
+  "cache": { "maxSizeMB": 100, "watchFiles": true },
+  "policies": { "maxFullFileReads": 10, "largeReadThreshold": 2000 },
+  "astIndex": { "binaryPath": null },
+  "updates": { "checkOnStartup": true, "autoUpdate": false },
+  "ignore": ["node_modules/**", "dist/**", ".git/**"]
+}
+```
+
+| Option | Default | What it does |
+|--------|---------|--------------|
+| `hooks.mode` | `"deny-enhanced"` | Read hook mode: `off` / `advisory` / `deny-enhanced` |
+| `hooks.denyThreshold` | `300` | Line count above which the hook intervenes on unbounded `Read` |
+| `sessionStart.enabled` | `true` | Re-inject MCP-rules reminder at every new session / `/clear` / `/compact` |
+| `agents.scope` | `null` | Persisted scope of last `install-agents` run; reused silently |
+| `agents.reminder` | `true` | Show the "agents not installed" startup nudge |
+| `smartRead.smallFileThreshold` | `200` | Files with fewer lines bypass AST overhead and are returned in full |
+| `cache.maxSizeMB` | `100` | File cache ceiling (LRU eviction) |
+| `policies.maxFullFileReads` | `10` | Warn after N full-file reads in session |
+| `policies.largeReadThreshold` | `2000` | Token threshold above which a read is flagged as "large" in analytics |
+
+## Tool Profiles
+
+Trim the advertised `tools/list` to save ~2 k tokens per session. Set via `TOKEN_PILOT_PROFILE` in your MCP server env block.
+
+| Profile | Tools | ~Tokens | Use when |
+|---------|------:|--------:|----------|
+| `full` *(default)* | 22 | ~4 150 | All capabilities |
+| `edit` | 16 | ~3 120 | Code-change workflows (nav + batch reads + `read_for_edit`) |
+| `nav` | 10 | ~1 910 | Read-only exploration / subagents that only navigate |
+
+Handlers remain active regardless of profile — a subagent that explicitly names a filtered-out tool still gets served. The profile only controls what appears in `tools/list` at session start.
+
+### Setting a profile
+
+**In `.mcp.json`:**
+```json
+{
+  "mcpServers": {
+    "token-pilot": {
+      "command": "npx",
+      "args": ["-y", "token-pilot"],
+      "env": { "TOKEN_PILOT_PROFILE": "nav" }
+    }
+  }
+}
+```
+
+**Via shell:**
+```bash
+TOKEN_PILOT_PROFILE=edit npx token-pilot
+```
+
+## CLI Reference
+
+```bash
+token-pilot                              # start MCP server
+token-pilot init                         # create/merge .mcp.json; prompt about subagents
+token-pilot install-agents [--scope=user|project] [--force]
+token-pilot uninstall-agents --scope=user|project
+token-pilot bless-agents                 # extend third-party agents with token-pilot MCP
+token-pilot unbless-agents <name>... | --all
+token-pilot install-hook                 # install PreToolUse hooks
+token-pilot uninstall-hook
+token-pilot stats                        # totals + top files from hook-events.jsonl
+token-pilot stats --session[=<id>] | --by-agent
+token-pilot tool-audit                   # per-tool savings distribution
+token-pilot tool-audit --json
+token-pilot doctor                       # diagnostics (ast-index, config, upstream drift)
+token-pilot doctor --check=env           # env var check only
+token-pilot install-ast-index            # download ast-index binary (auto on first run)
+```
+
+## Architecture
+
+```
+src/
+  index.ts              — CLI entry + MCP server bootstrap
+  server.ts             — MCP server: 22 tool definitions + enforcement mode
+  server/
+    enforcement-mode.ts — TOKEN_PILOT_MODE parsing (advisory / deny / strict)
+  ast-index/            — ast-index binary client + auto-install
+  core/
+    event-log.ts        — hook-events.jsonl + rotation + retention
+    session-analytics.ts, policy-engine.ts, intent-classifier.ts
+  hooks/
+    installer.ts        — hook install/uninstall for Claude Code
+    pre-bash.ts         — PreToolUse:Bash advisor (Bash/sh/eval/loop patterns)
+    pre-grep.ts         — PreToolUse:Grep advisor (symbol-like pattern detection)
+    session-start.ts    — SessionStart reminder handler
+    summary-pipeline.ts — ast-index → regex → head+tail → pass-through
+  cli/
+    install-agents.ts, uninstall-agents.ts
+    bless-agents.ts, unbless-agents.ts, doctor-drift.ts
+    stats.ts, tool-audit.ts
+  templates/agent-builder.ts
+  config/loader.ts, defaults.ts
+  handlers/             — 22 MCP tool handlers
+  git/                  — HEAD + file watchers (cache invalidation)
+
+scripts/
+  build-agents.mjs      — render templates/ → dist/agents/
+  bench-hook.mjs        — hook latency benchmark
+
+templates/agents/       — source for tp-* family + shared preamble + contract
+```

package/docs/hooks.md

@@ -0,0 +1,99 @@
+# Hooks & Enforcement Modes
+
+Token Pilot installs two categories of PreToolUse hooks in Claude Code:
+
+1. **Read hook** — intercepts large `Read` calls (configurable threshold, default 300 lines) and returns a structural summary in the denial reason.
+2. **Grep / Bash hooks** — block heavy recursive patterns (`grep -r`, `find /`, `cat <file.ts>`, unbounded `git log`, bare `git diff`) and redirect to token-pilot MCP equivalents.
+
+## TOKEN_PILOT_MODE — Enforcement Mode
+
+Controls how aggressively both hook categories behave:
+
+| Value | Grep/Bash hooks | MCP output |
+|-------|----------------|------------|
+| `advisory` | Pass all through (no blocking) | No caps |
+| `deny` *(default)* | Block heavy patterns, allow bounded variants | No caps |
+| `strict` | Same as deny, plus auto-cap MCP output (see below) | Capped |
+
+```bash
+# Set in your MCP server env block or shell profile:
+TOKEN_PILOT_MODE=strict npx token-pilot
+```
+
+### Strict-mode MCP output caps
+
+When `TOKEN_PILOT_MODE=strict` and the caller has not set the parameter explicitly:
+
+| Tool | Auto-injected default | Note appended |
+|------|-----------------------|---------------|
+| `smart_read` | `max_tokens: 2000` | Yes |
+| `explore_area` | `include: ["outline"]` | Yes |
+| `find_usages` | `mode: "list"` | Yes |
+| `smart_log` | `count: 20` | Yes |
+
+Pass the parameter explicitly to override the cap.
+
+## Read Hook Modes
+
+The PreToolUse:Read hook has its own mode (separate from enforcement mode). Set in `.token-pilot.json`:
+
+| Mode | Behaviour |
+|------|-----------|
+| `off` | Hook is inert — all `Read` calls pass through |
+| `advisory` | Denies unbounded Read with a short tip pointing at `smart_read` / `read_for_edit` |
+| `deny-enhanced` *(default)* | Denies the Read and returns a full structural summary (imports, exports, declarations) **inside** the denial reason. Works for subagents that lack MCP access. |
+
+```json
+{ "hooks": { "mode": "deny-enhanced", "denyThreshold": 300 } }
+```
+
+## Grep / Bash Hook Rules
+
+The Grep hook redirects symbol-like patterns to `find_usages`. The Bash hook blocks:
+
+| Pattern | Blocked when | Allowed when |
+|---------|-------------|--------------|
+| `grep -r`/`-R` | Always (unbounded) | Has `-m N` bound |
+| `find /`, `find ~` | No `-maxdepth` | Has `-maxdepth N` |
+| `cat <file.ts>` | Code file, no pipeline | In pipeline (`cat … \| head`) or non-code file |
+| `git log` | No count limit | Has `-n N`, `--max-count`, or `\| head` |
+| `git diff` | Bare (no path/flag) | Has path arg or `--stat` |
+| `bash -c "…"`, `eval "…"` | Inner command is heavy | Inner command is benign |
+
+## Installing / Removing Hooks
+
+```bash
+npx token-pilot install-hook      # register PreToolUse hooks in Claude Code
+npx token-pilot uninstall-hook    # remove hooks
+```
+
+Hooks are auto-installed on first server start inside Claude Code. The Claude Code plugin path installs hooks automatically:
+
+```bash
+claude plugin marketplace add https://github.com/Digital-Threads/token-pilot
+claude plugin install token-pilot@token-pilot
+```
+
+## Environment Variables
+
+| Var | Effect |
+|-----|--------|
+| `TOKEN_PILOT_MODE` | `advisory` / `deny` (default) / `strict` — enforcement level for Grep/Bash hooks and MCP output caps |
+| `TOKEN_PILOT_BYPASS=1` | Pass every Read through (Read hook only) |
+| `TOKEN_PILOT_DENY_THRESHOLD=<n>` | Override `hooks.denyThreshold` (default 300) |
+| `TOKEN_PILOT_ADAPTIVE_THRESHOLD=true` | Enable adaptive curve as session burns |
+| `TOKEN_PILOT_DEBUG=1` | Verbose hook logging to stderr |
+| `TOKEN_PILOT_NO_AGENT_REMINDER=1` | Suppress the "tp-* not installed" stderr nudge |
+| `TOKEN_PILOT_SUBAGENT=1` | Mark the MCP server as running inside a subagent |
+
+## Analytics & Audit
+
+```bash
+token-pilot stats                          # totals + top files from hook-events.jsonl
+token-pilot stats --session[=<id>]         # filter by session
+token-pilot stats --by-agent              # grouped by agent
+token-pilot tool-audit                    # per-tool savings distribution (cumulative)
+token-pilot tool-audit --json             # machine-readable output
+```
+
+Hook events accumulate in `.token-pilot/hook-events.jsonl`. The `session_analytics` MCP tool provides per-tool breakdown within the current session.