token-pilot 0.31.0 → 0.32.0

package/dist/handlers/call-tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v0.32.0 — call_tree MCP tool.
+ *
+ * Thin wrapper over `AstIndexClient.callTree`. Produces a text tree of
+ * callers (depth-N) for one function. Complements `find_usages` which
+ * is flat (one level of refs): call_tree is recursive, so you see the
+ * full chain from leaves → entry points.
+ *
+ * Typical use cases:
+ *   - debugging: "who eventually calls this helper"
+ *   - refactor planning: "what breaks if I change this function's
+ *     signature"
+ *   - dead-code verification: "does anything actually reach this
+ *     branch"
+ *
+ * Output shape is indented tree text, not JSON — the MCP-consuming
+ * model needs to read it, not diff it.
+ */
+import type { AstIndexClient } from "../ast-index/client.js";
+export interface CallTreeArgs {
+    /** Function / method name (unqualified, e.g. `fetchUser`). */
+    symbol: string;
+    /** Walk-up depth. Default 3, max 6 (anything deeper is overwhelming). */
+    depth?: number;
+}
+export declare function handleCallTree(args: CallTreeArgs, astIndex: AstIndexClient): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    meta: {
+        files: string[];
+    };
+}>;
+//# sourceMappingURL=call-tree.d.ts.map

package/dist/handlers/call-tree.js

@@ -0,0 +1,70 @@
+const MAX_DEPTH = 6;
+function renderNode(node, indent, out) {
+    const loc = node.file && node.line != null
+        ? ` — ${node.file}:${node.line}`
+        : node.file
+            ? ` — ${node.file}`
+            : "";
+    out.push(`${indent}${node.name}${loc}`);
+    if (node.callers && node.callers.length > 0) {
+        for (const child of node.callers) {
+            renderNode(child, indent + "  ", out);
+        }
+    }
+}
+export async function handleCallTree(args, astIndex) {
+    if (astIndex.isDisabled() || astIndex.isOversized()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "call_tree is disabled: " +
+                        (astIndex.isDisabled()
+                            ? "project root not detected. Call smart_read() on any project file first."
+                            : "ast-index indexed >50k files (likely includes node_modules). Ensure node_modules is in .gitignore.") +
+                        "\nAlternative: use find_usages(symbol) iteratively.",
+                },
+            ],
+            meta: { files: [] },
+        };
+    }
+    const symbol = args.symbol?.trim();
+    if (!symbol) {
+        return {
+            content: [{ type: "text", text: "call_tree: `symbol` is required." }],
+            meta: { files: [] },
+        };
+    }
+    const depth = Math.min(Math.max(1, Math.floor(args.depth ?? 3)), MAX_DEPTH);
+    const tree = await astIndex.callTree(symbol, depth);
+    if (!tree) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No call-tree found for \`${symbol}\`. The symbol may be uncalled, unindexed, or ambiguous. Try find_usages("${symbol}") for a flat cross-reference list.`,
+                },
+            ],
+            meta: { files: [] },
+        };
+    }
+    const lines = [];
+    lines.push(`CALL TREE for \`${symbol}\` (depth ${depth}, callers of callers…):`);
+    lines.push("");
+    renderNode(tree, "  ", lines);
+    lines.push("");
+    lines.push("Read bottom-up: indented entries call the parent. Root is the symbol you asked for.");
+    // Collect files for meta so downstream consumers can open them.
+    const files = new Set();
+    const collect = (n) => {
+        if (n.file)
+            files.add(n.file);
+        n.callers?.forEach(collect);
+    };
+    collect(tree);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        meta: { files: [...files] },
+    };
+}
+//# sourceMappingURL=call-tree.js.map

package/dist/hooks/session-start.d.ts

@@ -7,6 +7,8 @@
  *
  * Output contract: one JSON line on stdout, or exit 0 silent.
  */
+import { type HookEvent } from "../core/event-log.js";
+export declare function buildSubagentAdoptionNudge(events: HookEvent[], now: number, windowDays?: number, minSample?: number, threshold?: number): string | null;
 export interface AgentEntry {
     name: string;
     description: string;

package/dist/hooks/session-start.js

@@ -10,7 +10,43 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { loadLatestSnapshot } from "./../handlers/session-snapshot-persist.js";
+import { loadEvents } from "../core/event-log.js";
 const SNAPSHOT_FRESH_MS = 2 * 3600 * 1000; // 2h — enough to cover compaction/restart, tight enough that a new day's unrelated work doesn't inherit yesterday's thread
+// ─── subagent adoption nudge (v0.32.0) ──────────────────────────────
+// Pure function: takes the event log + current time, returns either a
+// one-liner nudge string or null when there's nothing useful to say.
+// Thresholds are module-level constants so tests can reference them.
+const NUDGE_WINDOW_DAYS = 7;
+/** Minimum Task events in window before we consider the sample big enough. */
+const NUDGE_MIN_SAMPLE = 5;
+/** Miss-rate (routable general-purpose dispatches / total) above which we nudge. */
+const NUDGE_THRESHOLD = 0.5;
+export function buildSubagentAdoptionNudge(events, now, windowDays = NUDGE_WINDOW_DAYS, minSample = NUDGE_MIN_SAMPLE, threshold = NUDGE_THRESHOLD) {
+    const cutoff = now - windowDays * 86_400_000;
+    const tasks = events.filter((e) => e.event === "task" && e.ts >= cutoff);
+    if (tasks.length < minSample)
+        return null;
+    const misses = tasks.filter((e) => typeof e.matched_tp_agent === "string" &&
+        e.matched_tp_agent.length > 0 &&
+        e.subagent_type !== e.matched_tp_agent);
+    if (misses.length === 0)
+        return null;
+    const rate = misses.length / tasks.length;
+    if (rate < threshold)
+        return null;
+    const pct = Math.round(rate * 100);
+    // Surface the top routing miss pair so the nudge is concrete, not abstract.
+    const pairCounts = new Map();
+    for (const m of misses) {
+        const key = `${m.subagent_type} → ${m.matched_tp_agent}`;
+        pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+    }
+    const topPair = [...pairCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    const pairClause = topPair ? ` Top miss: ${topPair}.` : "";
+    return (`[token-pilot] subagent miss-rate ${pct}% over last ${windowDays}d ` +
+        `(${misses.length}/${tasks.length} Task calls could have used a tp-* specialist).${pairClause} ` +
+        `Run \`token-pilot stats --tasks\` for details, or set TOKEN_PILOT_FORCE_SUBAGENTS=1 to hard-block.`);
+}
 function extractSnapshotGoal(body) {
     const m = body.match(/\*\*Goal:\*\*\s*(.+?)(?:\n|$)/);
     return m ? m[1].trim().slice(0, 100) : null;
@@ -215,6 +251,19 @@ export async function handleSessionStart(opts) {
             const goalClause = goal ? ` (goal: "${goal}")` : "";
             message += `\n\n[token-pilot] session_snapshot from ${age}${goalClause}. Read .token-pilot/snapshots/latest.md to resume — or ignore if unrelated.`;
         }
+        // v0.32.0 — subagent adoption nudge. Reads recent Task telemetry
+        // from hook-events.jsonl; when the main thread is picking
+        // general-purpose on routable work, surface a one-liner so the
+        // user / agent sees the miss rate without needing `stats --tasks`.
+        try {
+            const events = await loadEvents(opts.projectRoot);
+            const nudge = buildSubagentAdoptionNudge(events, Date.now());
+            if (nudge)
+                message += `\n\n${nudge}`;
+        }
+        catch {
+            /* silent — telemetry nudge is strictly opt-in */
+        }
         const output = {
             hookSpecificOutput: {
                 hookEventName: "SessionStart",

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

@@ -977,6 +977,71 @@ export declare const TOOL_DEFINITIONS: ({
         };
         required?: undefined;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            symbol: {
+                type: string;
+                description: string;
+            };
+            depth: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            show_imports?: undefined;
+            show_docs?: undefined;
+            scope?: undefined;
+            max_tokens?: undefined;
+            session_id?: undefined;
+            force?: undefined;
+            context_before?: undefined;
+            context_after?: undefined;
+            show?: undefined;
+            include_edit_context?: undefined;
+            symbols?: undefined;
+            start_line?: undefined;
+            end_line?: undefined;
+            heading?: undefined;
+            context_lines?: undefined;
+            line?: undefined;
+            context?: undefined;
+            include_callers?: undefined;
+            include_tests?: undefined;
+            include_changes?: undefined;
+            section?: undefined;
+            paths?: undefined;
+            kind?: undefined;
+            limit?: undefined;
+            lang?: undefined;
+            mode?: undefined;
+            include?: undefined;
+            recursive?: undefined;
+            max_depth?: undefined;
+            verbose?: undefined;
+            module?: undefined;
+            export_only?: undefined;
+            check?: undefined;
+            pattern?: undefined;
+            name?: undefined;
+            ref?: undefined;
+            count?: undefined;
+            command?: undefined;
+            runner?: undefined;
+            timeout?: undefined;
+            goal?: undefined;
+            decisions?: undefined;
+            confirmed?: undefined;
+            files?: undefined;
+            blocked?: undefined;
+            next?: undefined;
+            sessionId?: undefined;
+        };
+        required: string[];
+    };
 } | {
     name: string;
     description: string;

package/dist/server/tool-definitions.js

@@ -502,6 +502,24 @@ export const TOOL_DEFINITIONS = [
         },
     },
     // --- Analysis ---
+    {
+        name: "call_tree",
+        description: "Recursive depth-N call hierarchy for a function. Shows who calls who transitively — complements find_usages (flat one-level refs) by revealing full chains from leaf helpers to entry points. Use for debugging, refactor impact, and verifying reachability.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                symbol: {
+                    type: "string",
+                    description: "Function / method name, unqualified (e.g. `fetchUser`).",
+                },
+                depth: {
+                    type: "number",
+                    description: "Walk-up depth. Default 3, max 6.",
+                },
+            },
+            required: ["symbol"],
+        },
+    },
     {
         name: "find_unused",
         description: "Find dead code — functions, classes, and variables with no references across the project. Use for cleanup and refactoring.",

package/dist/server.js

@@ -28,6 +28,7 @@ import { handleSmartReadMany } from "./handlers/smart-read-many.js";
 import { handleProjectOverview } from "./handlers/project-overview.js";
 import { handleNonCodeRead, isNonCodeStructured } from "./handlers/non-code.js";
 import { handleFindUnused } from "./handlers/find-unused.js";
+import { handleCallTree } from "./handlers/call-tree.js";
 import { handleReadForEdit } from "./handlers/read-for-edit.js";
 import { handleRelatedFiles } from "./handlers/related-files.js";
 import { handleOutline } from "./handlers/outline.js";
@@ -49,7 +50,7 @@ import { getMcpInstructions, TOOL_DEFINITIONS, } from "./server/tool-definitions
 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";
+import { validateSmartReadArgs, validateReadSymbolArgs, validateReadSymbolsArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCallTreeArgs, 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);
@@ -726,6 +727,40 @@ export async function createServer(projectRoot, options) {
                         ],
                     };
                 }
+                case "call_tree": {
+                    const callTreeArgs = validateCallTreeArgs(args);
+                    const cachedTree = sessionCache?.get("call_tree", callTreeArgs);
+                    if (cachedTree) {
+                        recordWithTrace({
+                            tool: "call_tree",
+                            path: callTreeArgs.symbol,
+                            tokensReturned: cachedTree.tokenEstimate,
+                            tokensWouldBe: cachedTree.tokensWouldBe ?? cachedTree.tokenEstimate,
+                            timestamp: Date.now(),
+                            sessionCacheHit: true,
+                            savingsCategory: "cache",
+                            args: callTreeArgs,
+                        });
+                        return cachedTree.result;
+                    }
+                    const treeResult = await handleCallTree(callTreeArgs, astIndex);
+                    const treeText = treeResult.content[0]?.text ?? "";
+                    const treeTokens = estimateTokens(treeText);
+                    // No good "wouldBe" baseline for call_tree (you'd otherwise
+                    // run find_usages in a loop). Use a conservative N× multiplier.
+                    const treeWouldBe = treeTokens * 3;
+                    sessionCache?.set("call_tree", callTreeArgs, treeResult, { dependsOnAst: true }, treeTokens, treeWouldBe);
+                    recordWithTrace({
+                        tool: "call_tree",
+                        path: callTreeArgs.symbol,
+                        tokensReturned: treeTokens,
+                        tokensWouldBe: treeWouldBe,
+                        timestamp: Date.now(),
+                        savingsCategory: "compression",
+                        args: callTreeArgs,
+                    });
+                    return treeResult;
+                }
                 case "find_unused": {
                     const unusedArgs = validateFindUnusedArgs(args);
                     const cachedUnused = sessionCache?.get("find_unused", unusedArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Save up to 80% tokens when AI reads code — 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",