token-pilot 0.30.5 → 0.32.0

package/dist/cli/stats.js

@@ -67,7 +67,50 @@ export function formatStats(events, opts) {
     const total = sumSaved(scope);
     const sessionSuffix = sessionLabel ? ` (session ${sessionLabel})` : "";
     lines.push(`token-pilot stats${sessionSuffix} — ${scope.length} event${scope.length === 1 ? "" : "s"}, ~${total} tokens saved`);
-    if (opts.byAgent) {
+    if (opts.tasks) {
+        // v0.31.0 — Task-routing view. Scope to event:"task" records only.
+        const taskEvents = scope.filter((e) => e.event === "task");
+        if (taskEvents.length === 0) {
+            return lines[0] + "\n\nNo Task events yet.";
+        }
+        const totalTasks = taskEvents.length;
+        const misses = taskEvents.filter((e) => typeof e.matched_tp_agent === "string" &&
+            e.matched_tp_agent.length > 0 &&
+            e.subagent_type !== e.matched_tp_agent);
+        const missRate = totalTasks > 0 ? Math.round((misses.length / totalTasks) * 100) : 0;
+        // Group by subagent_type (what Claude actually picked).
+        const pickGroups = groupBy(taskEvents, (e) => (e.subagent_type && e.subagent_type.length > 0
+            ? e.subagent_type
+            : "(unknown)"));
+        const picks = [...pickGroups.entries()]
+            .map(([agent, evs]) => ({ agent, count: evs.length }))
+            .sort((a, b) => b.count - a.count);
+        // Top missed routings: (picked → suggested) pairs with counts.
+        const missCounts = new Map();
+        for (const e of misses) {
+            const key = `${e.subagent_type} → ${e.matched_tp_agent}`;
+            missCounts.set(key, (missCounts.get(key) ?? 0) + 1);
+        }
+        const topMisses = [...missCounts.entries()]
+            .map(([pair, count]) => ({ pair, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 10);
+        // Rewrite header for the task view (replace savings number with miss-rate).
+        lines[0] = `token-pilot stats — ${totalTasks} Task call${totalTasks === 1 ? "" : "s"}, miss-rate ${missRate}% (${misses.length}/${totalTasks})${sessionSuffix}`;
+        lines.push("");
+        lines.push("Picked subagents:");
+        for (const p of picks) {
+            lines.push(`  ${pad(p.agent, 24)}  ${p.count.toString().padStart(4)}× events`);
+        }
+        if (topMisses.length > 0) {
+            lines.push("");
+            lines.push("Top routing misses (picked → suggested tp-*):");
+            for (const m of topMisses) {
+                lines.push(`  ${pad(m.pair, 48)}  ${m.count.toString().padStart(4)}×`);
+            }
+        }
+    }
+    else if (opts.byAgent) {
         // Group by agent_type (null → "main").
         const groups = groupBy(scope, (e) => (e.agent_type ?? "main"));
         const rows = [...groups.entries()]
@@ -121,9 +164,11 @@ export async function handleStats(argv, opts) {
     const events = await loadEvents(projectRoot);
     const session = parseFlag(argv, "session");
     const byAgent = parseFlag(argv, "by-agent");
+    const tasks = parseFlag(argv, "tasks");
     const rendered = formatStats(events, {
         session: session === undefined ? undefined : session,
         byAgent: byAgent === true,
+        tasks: tasks === true,
     });
     process.stdout.write(rendered + "\n");
     return 0;

package/dist/core/agent-matcher.d.ts

@@ -0,0 +1,115 @@
+/**
+ * v0.31.0 — tp-* subagent heuristic matcher.
+ *
+ * Goal: given a Claude Code `Task` tool invocation (subagent_type +
+ * description), decide which `tp-*` agent from `agents/` would be a
+ * better fit. Used by:
+ *
+ *   1. PostToolUse:Task telemetry — enrich each event with
+ *      `matched_tp_agent` so `stats --tasks` can show miss-rate.
+ *   2. PreToolUse:Task enforcement (Pack 2, later) — advise/deny when
+ *      the agent picked `general-purpose` but a tp-* clearly fits.
+ *
+ * Matcher philosophy — keep it BORING and EXPLAINABLE.
+ *
+ * Agent frontmatter description layout (empirically stable across all
+ * 24 shipped agents):
+ *
+ *     description: PROACTIVELY use this when the user asks to review a
+ *       diff, PR, commit range, or changeset ("review these changes",
+ *       "look at my PR", "is this safe to merge"). Verdict-first output
+ *       with Critical / Important findings. Do NOT use for writing code
+ *       or planning.
+ *
+ * Two signal sources:
+ *
+ *   - Quoted triggers: every `"…"` substring inside the description.
+ *     These are literally the phrases the agent author expected users
+ *     to type. Highest signal. Substring match (case-insensitive) on
+ *     the user's description → score += 2.
+ *
+ *   - Content keywords: stemmed word set from the 1st description
+ *     sentence, minus stopwords and boilerplate ("PROACTIVELY",
+ *     "use this", "when the user asks"). Each match on the user's
+ *     description → score += 1.
+ *
+ * Negative filter: everything after `Do NOT use for` is excluded from
+ * keyword extraction AND actively penalises a match (score -= 1 per
+ * term present in user's description). Prevents `tp-test-writer` from
+ * being suggested on "diagnose failing test" (which is tp-test-triage).
+ *
+ * Confidence tiers:
+ *   - score ≥ 3 or ≥ 1 quoted trigger → "high"
+ *   - score in [1, 2]                 → "low"
+ *   - score < 1                       → no match
+ *
+ * The function is pure (deps → in-memory index + string) so it's fully
+ * unit-testable. File I/O (reading the agents dir) lives in
+ * `buildAgentIndex` which is a one-shot loader called at startup.
+ */
+/** One parsed `tp-*` agent. Only fields the matcher needs. */
+export interface ParsedAgent {
+    /** agent name without .md extension, e.g. "tp-pr-reviewer" */
+    name: string;
+    /** phrases found in `"…"` inside the description — highest signal */
+    quotedTriggers: string[];
+    /** stemmed content keywords from the positive side of the description */
+    keywords: string[];
+    /** negative-filter terms from `Do NOT use for …` */
+    negative: string[];
+}
+export interface AgentIndex {
+    agents: ParsedAgent[];
+}
+export interface MatchResult {
+    agent: string;
+    confidence: "high" | "low";
+    score: number;
+}
+/** Extract the `description:` value from YAML frontmatter.
+ *  Supports multi-line values (continuation lines indented).
+ *  Returns null when the file has no frontmatter or no description. */
+export declare function extractDescription(body: string): string | null;
+/** Pull every `"…"` substring out of a string. Ignores empty pairs. */
+export declare function extractQuotedTriggers(s: string): string[];
+/**
+ * Split `description` around `Do NOT use for …` — everything on the
+ * positive side is keyword material; everything after contributes to
+ * the negative filter.
+ */
+export declare function splitAroundNegative(desc: string): {
+    positive: string;
+    negative: string;
+};
+/**
+ * Tokenise → lowercase → drop stopwords + ≤2 chars + quoted-trigger
+ * leftovers. Keywords stay in surface form; we do not stem. Stemming
+ * helps recall on English verb/noun pairs ("refactor"/"refactoring"),
+ * but libraries add cost for modest gain — use substring match on the
+ * user's description instead (covers most morphology).
+ */
+export declare function extractKeywords(text: string): string[];
+/**
+ * Parse one agent markdown body into its ParsedAgent representation.
+ * Returns null if frontmatter is missing / description is empty.
+ */
+export declare function parseAgent(name: string, body: string): ParsedAgent | null;
+/**
+ * Load every `tp-*.md` under a directory and build an in-memory index.
+ * Non-tp-* files are silently skipped. Unreadable files are skipped
+ * with no throw — an agent directory isn't a runtime dep.
+ */
+export declare function buildAgentIndex(agentsDir: string): Promise<AgentIndex>;
+/**
+ * Score a single agent against the user description. Surface the score
+ * so callers can inspect / threshold differently if needed.
+ */
+export declare function scoreAgent(agent: ParsedAgent, userDescriptionLower: string): number;
+/**
+ * Find the best `tp-*` match for a user description. Returns null when
+ * no agent clears the low-confidence threshold.
+ *
+ * "Best" = highest score, tiebreak alphabetical (deterministic).
+ */
+export declare function matchTpAgent(description: string, index: AgentIndex): MatchResult | null;
+//# sourceMappingURL=agent-matcher.d.ts.map

package/dist/core/agent-matcher.js

@@ -0,0 +1,326 @@
+/**
+ * v0.31.0 — tp-* subagent heuristic matcher.
+ *
+ * Goal: given a Claude Code `Task` tool invocation (subagent_type +
+ * description), decide which `tp-*` agent from `agents/` would be a
+ * better fit. Used by:
+ *
+ *   1. PostToolUse:Task telemetry — enrich each event with
+ *      `matched_tp_agent` so `stats --tasks` can show miss-rate.
+ *   2. PreToolUse:Task enforcement (Pack 2, later) — advise/deny when
+ *      the agent picked `general-purpose` but a tp-* clearly fits.
+ *
+ * Matcher philosophy — keep it BORING and EXPLAINABLE.
+ *
+ * Agent frontmatter description layout (empirically stable across all
+ * 24 shipped agents):
+ *
+ *     description: PROACTIVELY use this when the user asks to review a
+ *       diff, PR, commit range, or changeset ("review these changes",
+ *       "look at my PR", "is this safe to merge"). Verdict-first output
+ *       with Critical / Important findings. Do NOT use for writing code
+ *       or planning.
+ *
+ * Two signal sources:
+ *
+ *   - Quoted triggers: every `"…"` substring inside the description.
+ *     These are literally the phrases the agent author expected users
+ *     to type. Highest signal. Substring match (case-insensitive) on
+ *     the user's description → score += 2.
+ *
+ *   - Content keywords: stemmed word set from the 1st description
+ *     sentence, minus stopwords and boilerplate ("PROACTIVELY",
+ *     "use this", "when the user asks"). Each match on the user's
+ *     description → score += 1.
+ *
+ * Negative filter: everything after `Do NOT use for` is excluded from
+ * keyword extraction AND actively penalises a match (score -= 1 per
+ * term present in user's description). Prevents `tp-test-writer` from
+ * being suggested on "diagnose failing test" (which is tp-test-triage).
+ *
+ * Confidence tiers:
+ *   - score ≥ 3 or ≥ 1 quoted trigger → "high"
+ *   - score in [1, 2]                 → "low"
+ *   - score < 1                       → no match
+ *
+ * The function is pure (deps → in-memory index + string) so it's fully
+ * unit-testable. File I/O (reading the agents dir) lives in
+ * `buildAgentIndex` which is a one-shot loader called at startup.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+/**
+ * Stopwords stripped from keyword extraction. Keep tiny — aggressive
+ * stopword lists kill recall. Only boilerplate from agent frontmatter
+ * templates goes here.
+ */
+const STOPWORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "and",
+    "or",
+    "of",
+    "to",
+    "in",
+    "for",
+    "on",
+    "at",
+    "by",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "this",
+    "that",
+    "these",
+    "those",
+    "it",
+    "its",
+    "as",
+    "with",
+    "when",
+    "where",
+    "user",
+    "users",
+    "ask",
+    "asks",
+    "asked",
+    "asking",
+    "use",
+    "uses",
+    "used",
+    "using",
+    "proactively",
+    "please",
+    "any",
+    "all",
+    "some",
+    "get",
+    "gets",
+    "got",
+    "also",
+    "like",
+    "from",
+    "into",
+    "not",
+    "no",
+    "do",
+    "does",
+    "did",
+    "have",
+    "has",
+    "had",
+    "will",
+    "can",
+    "could",
+    "should",
+    "may",
+    "might",
+    "must",
+    "you",
+    "your",
+    "their",
+    "they",
+    "them",
+    "we",
+    "our",
+    "us",
+]);
+/** Extract the `description:` value from YAML frontmatter.
+ *  Supports multi-line values (continuation lines indented).
+ *  Returns null when the file has no frontmatter or no description. */
+export function extractDescription(body) {
+    const fmEnd = body.indexOf("\n---", 3);
+    if (!body.startsWith("---\n") || fmEnd === -1)
+        return null;
+    const fm = body.slice(4, fmEnd);
+    const lines = fm.split("\n");
+    let desc = "";
+    let inDesc = false;
+    for (const line of lines) {
+        // Top-level key detection: `key: value` at column 0
+        const topKey = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+        if (topKey && !/^\s/.test(line)) {
+            if (inDesc)
+                break;
+            if (topKey[1] === "description") {
+                desc = topKey[2] ?? "";
+                inDesc = true;
+            }
+        }
+        else if (inDesc) {
+            // Continuation line (indented or blank) — append with a space.
+            desc += " " + line.trim();
+        }
+    }
+    const trimmed = desc.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/** Pull every `"…"` substring out of a string. Ignores empty pairs. */
+export function extractQuotedTriggers(s) {
+    const out = [];
+    const re = /"([^"]+)"/g;
+    for (const m of s.matchAll(re)) {
+        const inner = m[1].trim().toLowerCase();
+        if (inner.length > 0)
+            out.push(inner);
+    }
+    return out;
+}
+/**
+ * Split `description` around `Do NOT use for …` — everything on the
+ * positive side is keyword material; everything after contributes to
+ * the negative filter.
+ */
+export function splitAroundNegative(desc) {
+    // Case-insensitive split on common "Do NOT use …" lead-ins. `to` catches
+    // "Do NOT use to write" (tp-test-triage); `for` / `on` / `during` / `when`
+    // cover every other shipped agent. Add terms here as new forms appear.
+    const re = /\bdo\s+not\s+use\s+(?:for|on|during|when|to)\b/i;
+    const idx = desc.search(re);
+    if (idx === -1)
+        return { positive: desc, negative: "" };
+    return {
+        positive: desc.slice(0, idx),
+        negative: desc.slice(idx),
+    };
+}
+/**
+ * Tokenise → lowercase → drop stopwords + ≤2 chars + quoted-trigger
+ * leftovers. Keywords stay in surface form; we do not stem. Stemming
+ * helps recall on English verb/noun pairs ("refactor"/"refactoring"),
+ * but libraries add cost for modest gain — use substring match on the
+ * user's description instead (covers most morphology).
+ */
+export function extractKeywords(text) {
+    const out = new Set();
+    // Remove quoted phrases first (they're handled separately).
+    const cleaned = text.replace(/"[^"]+"/g, " ");
+    for (const raw of cleaned.toLowerCase().split(/[^a-z0-9_-]+/)) {
+        const tok = raw.trim();
+        // Keep short technical terms ("ci", "pr", "db", "io"). STOPWORDS already
+        // filters most 1-2 char english junk ("is", "to", "on", "a"). Drop
+        // single chars only — they carry ~no signal.
+        if (tok.length < 2)
+            continue;
+        if (STOPWORDS.has(tok))
+            continue;
+        out.add(tok);
+    }
+    return [...out];
+}
+/**
+ * Parse one agent markdown body into its ParsedAgent representation.
+ * Returns null if frontmatter is missing / description is empty.
+ */
+export function parseAgent(name, body) {
+    const desc = extractDescription(body);
+    if (!desc)
+        return null;
+    const { positive, negative } = splitAroundNegative(desc);
+    const quotedTriggers = extractQuotedTriggers(desc);
+    const keywords = extractKeywords(positive);
+    // Negative terms: only the core ones (tp-* names, salient nouns).
+    const negKeywords = extractKeywords(negative);
+    return {
+        name,
+        quotedTriggers,
+        keywords,
+        negative: negKeywords,
+    };
+}
+/**
+ * Load every `tp-*.md` under a directory and build an in-memory index.
+ * Non-tp-* files are silently skipped. Unreadable files are skipped
+ * with no throw — an agent directory isn't a runtime dep.
+ */
+export async function buildAgentIndex(agentsDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(agentsDir);
+    }
+    catch {
+        return { agents: [] };
+    }
+    const agents = [];
+    for (const entry of entries) {
+        if (!entry.startsWith("tp-") || !entry.endsWith(".md"))
+            continue;
+        const name = entry.slice(0, -".md".length);
+        let body;
+        try {
+            body = await fs.readFile(join(agentsDir, entry), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseAgent(name, body);
+        if (parsed)
+            agents.push(parsed);
+    }
+    return { agents };
+}
+/**
+ * Score a single agent against the user description. Surface the score
+ * so callers can inspect / threshold differently if needed.
+ */
+export function scoreAgent(agent, userDescriptionLower) {
+    let score = 0;
+    for (const trigger of agent.quotedTriggers) {
+        if (userDescriptionLower.includes(trigger))
+            score += 2;
+    }
+    for (const kw of agent.keywords) {
+        if (userDescriptionLower.includes(kw))
+            score += 1;
+    }
+    for (const neg of agent.negative) {
+        if (userDescriptionLower.includes(neg))
+            score -= 1;
+    }
+    return score;
+}
+/**
+ * Find the best `tp-*` match for a user description. Returns null when
+ * no agent clears the low-confidence threshold.
+ *
+ * "Best" = highest score, tiebreak alphabetical (deterministic).
+ */
+export function matchTpAgent(description, index) {
+    if (!description || index.agents.length === 0)
+        return null;
+    const needle = description.toLowerCase();
+    let best = null;
+    for (const agent of index.agents) {
+        const score = scoreAgent(agent, needle);
+        if (!best) {
+            best = { agent, score };
+            continue;
+        }
+        if (score > best.score) {
+            best = { agent, score };
+            continue;
+        }
+        // Deterministic tiebreak: alphabetical by agent.name. Without this,
+        // match depends on readdir order, which is filesystem-specific.
+        if (score === best.score && agent.name < best.agent.name) {
+            best = { agent, score };
+        }
+    }
+    if (!best || best.score < 1)
+        return null;
+    // High confidence when score is strong OR at least one quoted trigger
+    // matched (quoted = explicit author-blessed phrase).
+    const hitQuoted = best.agent.quotedTriggers.some((t) => needle.includes(t));
+    const confidence = best.score >= 3 || hitQuoted ? "high" : "low";
+    return {
+        agent: best.agent.name,
+        confidence,
+        score: best.score,
+    };
+}
+//# sourceMappingURL=agent-matcher.js.map

package/dist/core/event-log.d.ts

@@ -28,7 +28,7 @@ export interface HookEvent {
     /** null for top-level session; agent_type string inside a subagent. */
     agent_type: string | null;
     agent_id: string | null;
-    event: "denied" | "allowed" | "bypass" | "pass-through" | string;
+    event: "denied" | "allowed" | "bypass" | "pass-through" | "task" | string;
     file: string;
     lines: number;
     estTokens: number;
@@ -36,6 +36,19 @@ export interface HookEvent {
     summaryTokens: number;
     /** estTokens - summaryTokens; 0 for allow/bypass. */
     savedTokens: number;
+    /** The subagent_type Claude Code dispatched (`tp-*` or `general-purpose`…). */
+    subagent_type?: string;
+    /**
+     * Heuristic match against `tp-*` agent frontmatter. Set only when
+     * `subagent_type` is NOT already a tp-*. null when no match fires.
+     */
+    matched_tp_agent?: string | null;
+    /** Confidence of the heuristic match (omitted when matched_tp_agent=null). */
+    match_confidence?: "high" | "low";
+    /** Response budget declared in the agent markdown body, or null. */
+    budget?: number | null;
+    /** actualTokens > budget × (1 + tolerance). */
+    overBudget?: boolean;
 }
 export declare function eventLogDir(projectRoot: string): string;
 export declare function currentLogPath(projectRoot: string): string;

package/dist/core/validation.d.ts

@@ -22,7 +22,7 @@ export declare function validateReadSymbolArgs(args: unknown): {
     symbol: string;
     context_before?: number;
     context_after?: number;
-    show?: 'full' | 'head' | 'tail' | 'outline';
+    show?: "full" | "head" | "tail" | "outline";
 };
 /**
  * Validate read_symbols arguments (batch multi-symbol read).
@@ -32,7 +32,7 @@ export declare function validateReadSymbolsArgs(args: unknown): {
     symbols: string[];
     context_before?: number;
     context_after?: number;
-    show?: 'full' | 'head' | 'tail' | 'outline';
+    show?: "full" | "head" | "tail" | "outline";
 };
 /**
  * Validate read_range arguments.
@@ -56,11 +56,11 @@ export declare function validateReadDiffArgs(args: unknown): {
 export interface FindUsagesArgs {
     symbol: string;
     scope?: string;
-    kind?: 'definitions' | 'imports' | 'usages' | 'all';
+    kind?: "definitions" | "imports" | "usages" | "all";
     limit?: number;
     lang?: string;
     context_lines?: number;
-    mode?: 'full' | 'list';
+    mode?: "full" | "list";
 }
 export declare function validateFindUsagesArgs(args: unknown): FindUsagesArgs;
 /**
@@ -105,8 +105,12 @@ export declare function validateFindUnusedArgs(args: unknown): {
     export_only?: boolean;
     limit?: number;
 };
+export declare function validateCallTreeArgs(args: unknown): {
+    symbol: string;
+    depth?: number;
+};
 export interface CodeAuditArgs {
-    check: 'pattern' | 'todo' | 'deprecated' | 'annotations' | 'all';
+    check: "pattern" | "todo" | "deprecated" | "annotations" | "all";
     pattern?: string;
     name?: string;
     lang?: string;
@@ -118,7 +122,7 @@ export declare function validateCodeAuditArgs(args: unknown): CodeAuditArgs;
  * v1.1: added include filter.
  */
 export interface ProjectOverviewArgs {
-    include?: Array<'stack' | 'ci' | 'quality' | 'architecture'>;
+    include?: Array<"stack" | "ci" | "quality" | "architecture">;
 }
 export declare function validateProjectOverviewArgs(args: unknown): ProjectOverviewArgs;
 /**
@@ -126,14 +130,14 @@ export declare function validateProjectOverviewArgs(args: unknown): ProjectOverv
  */
 export interface ModuleInfoArgs {
     module: string;
-    check?: 'deps' | 'dependents' | 'api' | 'unused-deps' | 'all';
+    check?: "deps" | "dependents" | "api" | "unused-deps" | "all";
 }
 export declare function validateModuleInfoArgs(args: unknown): ModuleInfoArgs;
 /**
  * Validate smart_diff arguments.
  */
 export interface SmartDiffArgs {
-    scope?: 'unstaged' | 'staged' | 'commit' | 'branch';
+    scope?: "unstaged" | "staged" | "commit" | "branch";
     path?: string;
     ref?: string;
 }
@@ -143,7 +147,7 @@ export declare function validateSmartDiffArgs(args: unknown): SmartDiffArgs;
  */
 export interface ExploreAreaArgs {
     path: string;
-    include?: Array<'outline' | 'imports' | 'tests' | 'changes'>;
+    include?: Array<"outline" | "imports" | "tests" | "changes">;
 }
 export declare function validateExploreAreaArgs(args: unknown): ExploreAreaArgs;
 export interface SmartLogArgs {