token-pilot 0.30.5 → 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/installer.js

@@ -61,6 +61,15 @@ function createHookConfig(options) {
                         },
                     ],
                 },
+                {
+                    matcher: "Task",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("hook-pre-task", options),
+                        },
+                    ],
+                },
             ],
             SessionStart: [
                 {

package/dist/hooks/post-task.d.ts

@@ -13,6 +13,7 @@
  * Silent on every failure — telemetry must never break the agent loop.
  * Non-tp-* subagents are ignored (we only enforce our own contracts).
  */
+import { type AgentIndex } from "../core/agent-matcher.js";
 export declare const OVER_BUDGET_LOG = "over-budget.log";
 /** Ratio above which we flag — 0.1 = 10 % grace. */
 export declare const OVER_BUDGET_TOLERANCE = 0.1;
@@ -55,9 +56,23 @@ export interface PostTaskHookInput {
     tool_name?: string;
     tool_input?: {
         subagent_type?: string;
+        description?: string;
     };
     tool_response?: unknown;
+    session_id?: string;
+    agent_type?: string;
+    agent_id?: string;
 }
+/**
+ * Resolve the plugin's own `agents/` directory. The hook binary lives
+ * at `<plugin>/dist/index.js`, so agents/ is `../agents` from here.
+ * Allow an override for tests that want an isolated fixture dir.
+ */
+export declare function defaultAgentsDir(): string;
+/** Resolve (and cache) the tp-* agent index. Safe to call repeatedly. */
+export declare function getAgentIndex(dir?: string): Promise<AgentIndex>;
+/** Test-only: clear the module-level cache between fixtures. */
+export declare function _resetAgentIndexCache(): void;
 /**
  * Full post-Task processing: read frontmatter, count tokens, log over-budget.
  * Returns the advice message (or null) so the caller can optionally emit

package/dist/hooks/post-task.js

@@ -14,7 +14,10 @@
  * Non-tp-* subagents are ignored (we only enforce our own contracts).
  */
 import { promises as fs } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildAgentIndex, matchTpAgent, } from "../core/agent-matcher.js";
+import { appendEvent } from "../core/event-log.js";
 export const OVER_BUDGET_LOG = "over-budget.log";
 /** Ratio above which we flag — 0.1 = 10 % grace. */
 export const OVER_BUDGET_TOLERANCE = 0.1;
@@ -100,6 +103,43 @@ export async function loadAgentBody(projectRoot, homeDir, agentName) {
     }
     return null;
 }
+// ─── Cached tp-* agent index ─────────────────────────────────────────
+// The hook subprocess is cold-started per Task post-event, but within
+// that process we parse the agents directory once. Lookup cost is ~1 FS
+// listing + 24 file reads, ~5-15 ms — below the noise floor of the hook
+// round-trip. Kept as a process-level cache anyway for Pack 2 when the
+// pre-task hook re-uses the same index on hot paths.
+let _agentIndexCache = null;
+/**
+ * Resolve the plugin's own `agents/` directory. The hook binary lives
+ * at `<plugin>/dist/index.js`, so agents/ is `../agents` from here.
+ * Allow an override for tests that want an isolated fixture dir.
+ */
+export function defaultAgentsDir() {
+    // `import.meta.url` resolves to the bundled dist location, which is
+    // already one step below the repo root (`dist/hooks/post-task.js`).
+    // Walk up twice: `hooks` → `dist` → plugin root, then join `agents`.
+    try {
+        const here = fileURLToPath(import.meta.url);
+        return resolve(dirname(here), "..", "..", "agents");
+    }
+    catch {
+        // Not running as a bundled module (eg. vitest in-source) — fall
+        // back to CWD/agents. Production path uses the URL resolver above.
+        return resolve(process.cwd(), "agents");
+    }
+}
+/** Resolve (and cache) the tp-* agent index. Safe to call repeatedly. */
+export async function getAgentIndex(dir = defaultAgentsDir()) {
+    if (_agentIndexCache)
+        return _agentIndexCache;
+    _agentIndexCache = await buildAgentIndex(dir);
+    return _agentIndexCache;
+}
+/** Test-only: clear the module-level cache between fixtures. */
+export function _resetAgentIndexCache() {
+    _agentIndexCache = null;
+}
 /**
  * Full post-Task processing: read frontmatter, count tokens, log over-budget.
  * Returns the advice message (or null) so the caller can optionally emit
@@ -108,29 +148,72 @@ export async function loadAgentBody(projectRoot, homeDir, agentName) {
 export async function processPostTask(projectRoot, homeDir, input) {
     if (input.tool_name !== "Task")
         return null;
-    const agentName = input.tool_input?.subagent_type;
-    if (typeof agentName !== "string" || !agentName.startsWith("tp-")) {
-        return null;
+    const subagentType = input.tool_input?.subagent_type;
+    const description = input.tool_input?.description ?? "";
+    const actualTokens = extractSubagentTokens(input) ?? 0;
+    const isTpAgent = typeof subagentType === "string" && subagentType.startsWith("tp-");
+    // ─── existing tp-* budget logic (unchanged) ─────────────────────
+    let budget = null;
+    let decision = {
+        overBudget: false,
+        overByRatio: 0,
+        message: null,
+    };
+    if (isTpAgent && actualTokens > 0) {
+        const body = await loadAgentBody(projectRoot, homeDir, subagentType);
+        budget = body ? parseAgentBudget(body) : null;
+        decision = decideBudgetAdvice({
+            agentName: subagentType,
+            budget,
+            actualTokens,
+        });
+        if (decision.overBudget && budget != null) {
+            await appendOverBudgetLog(projectRoot, {
+                ts: Date.now(),
+                agent: subagentType,
+                budget,
+                actualTokens,
+                overByRatio: decision.overByRatio,
+            });
+        }
     }
-    const actualTokens = extractSubagentTokens(input);
-    if (actualTokens == null)
-        return null;
-    const body = await loadAgentBody(projectRoot, homeDir, agentName);
-    const budget = body ? parseAgentBudget(body) : null;
-    const decision = decideBudgetAdvice({
-        agentName,
-        budget,
-        actualTokens,
-    });
-    if (decision.overBudget && budget != null) {
-        await appendOverBudgetLog(projectRoot, {
+    // ─── v0.31.0 Task telemetry ────────────────────────────────────
+    // One event per Task call, regardless of tp-*. For non-tp agents we
+    // run the heuristic matcher so `stats --tasks` can surface routing
+    // misses (general-purpose picked when a tp-* would have fit).
+    // Silent on any error — telemetry must never break hook dispatch.
+    try {
+        let matched = null;
+        let matchConfidence;
+        if (!isTpAgent && description.length > 0) {
+            const index = await getAgentIndex();
+            const hit = matchTpAgent(description, index);
+            if (hit) {
+                matched = hit.agent;
+                matchConfidence = hit.confidence;
+            }
+        }
+        await appendEvent(projectRoot, {
             ts: Date.now(),
-            agent: agentName,
+            session_id: input.session_id ?? "",
+            agent_type: input.agent_type ?? null,
+            agent_id: input.agent_id ?? null,
+            event: "task",
+            file: "",
+            lines: 0,
+            estTokens: actualTokens,
+            summaryTokens: 0,
+            savedTokens: 0,
+            subagent_type: typeof subagentType === "string" ? subagentType : "",
+            matched_tp_agent: matched,
+            ...(matchConfidence ? { match_confidence: matchConfidence } : {}),
             budget,
-            actualTokens,
-            overByRatio: decision.overByRatio,
+            overBudget: decision.overBudget,
         });
     }
+    catch {
+        /* silent */
+    }
     return decision.message;
 }
 //# sourceMappingURL=post-task.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * v0.31.0 Pack 2 — PreToolUse:Task routing enforcement.
+ *
+ * Pack 1 (already shipped) built the matcher and telemetry. Pack 2 acts
+ * on that matcher: BEFORE a Task dispatch fires, we inspect
+ * `tool_input.subagent_type` + `tool_input.description`, heuristically
+ * match against the shipped `tp-*` catalog, and redirect (advise / deny)
+ * general-purpose calls that clearly fit a specialised agent.
+ *
+ * Why not straight-deny:
+ *   - The pre-edit rollback in v0.30.4 taught us the cost of a false
+ *     hard-block (stuck sessions, BYPASS env creep). Task routing has
+ *     MORE ambiguity than Edit (descriptions are terse; recall on
+ *     keyword match is imperfect), so the default mode = advise.
+ *
+ * Tier logic (first match wins):
+ *
+ *   1. tool_name !== "Task"                          → allow
+ *   2. subagent_type ∈ tp-*                          → allow
+ *   3. description contains an ESCAPE phrase         → allow
+ *      (ad-hoc / research / explore / multi-step / across the codebase)
+ *   4. matchTpAgent returns null                     → allow
+ *   5. TOKEN_PILOT_FORCE_SUBAGENTS=1 OR mode=strict  → deny
+ *      (hard-block: agent author opted into pedantic routing)
+ *   6. confidence=high                               → advise
+ *   7. confidence=low                                → advise (softer msg)
+ *
+ * Pure decide — all context (agent index, env, mode) is pre-resolved
+ * by the caller so the function stays deterministic and unit-testable.
+ */
+import type { EnforcementMode } from "../server/enforcement-mode.js";
+import type { AgentIndex } from "../core/agent-matcher.js";
+export interface PreTaskInput {
+    tool_name?: string;
+    tool_input?: {
+        subagent_type?: string;
+        description?: string;
+        [k: string]: unknown;
+    };
+}
+export type PreTaskDecision = {
+    kind: "allow";
+} | {
+    kind: "advise";
+    message: string;
+} | {
+    kind: "deny";
+    reason: string;
+};
+export interface PreTaskContext {
+    /** Parsed enforcement mode. `strict` is the only hard-block tier. */
+    mode: EnforcementMode;
+    /** Agent catalog built at startup by buildAgentIndex. */
+    agentIndex: AgentIndex;
+    /** TOKEN_PILOT_FORCE_SUBAGENTS=1 — opt-in strictness regardless of mode. */
+    force: boolean;
+}
+/**
+ * Pure decision function. Caller resolves all context (env, mode,
+ * agent index) up front so this stays a plain input → output mapping.
+ */
+export declare function decidePreTask(input: PreTaskInput, ctx: PreTaskContext): PreTaskDecision;
+/**
+ * Render the Claude Code hook JSON response.
+ *
+ * - allow  → no output (pass-through)
+ * - advise → permissionDecision=allow + additionalContext
+ * - deny   → permissionDecision=deny + reason
+ */
+export declare function renderPreTaskOutput(decision: PreTaskDecision): string | null;
+//# sourceMappingURL=pre-task.d.ts.map

package/dist/hooks/pre-task.js

@@ -0,0 +1,125 @@
+/**
+ * v0.31.0 Pack 2 — PreToolUse:Task routing enforcement.
+ *
+ * Pack 1 (already shipped) built the matcher and telemetry. Pack 2 acts
+ * on that matcher: BEFORE a Task dispatch fires, we inspect
+ * `tool_input.subagent_type` + `tool_input.description`, heuristically
+ * match against the shipped `tp-*` catalog, and redirect (advise / deny)
+ * general-purpose calls that clearly fit a specialised agent.
+ *
+ * Why not straight-deny:
+ *   - The pre-edit rollback in v0.30.4 taught us the cost of a false
+ *     hard-block (stuck sessions, BYPASS env creep). Task routing has
+ *     MORE ambiguity than Edit (descriptions are terse; recall on
+ *     keyword match is imperfect), so the default mode = advise.
+ *
+ * Tier logic (first match wins):
+ *
+ *   1. tool_name !== "Task"                          → allow
+ *   2. subagent_type ∈ tp-*                          → allow
+ *   3. description contains an ESCAPE phrase         → allow
+ *      (ad-hoc / research / explore / multi-step / across the codebase)
+ *   4. matchTpAgent returns null                     → allow
+ *   5. TOKEN_PILOT_FORCE_SUBAGENTS=1 OR mode=strict  → deny
+ *      (hard-block: agent author opted into pedantic routing)
+ *   6. confidence=high                               → advise
+ *   7. confidence=low                                → advise (softer msg)
+ *
+ * Pure decide — all context (agent index, env, mode) is pre-resolved
+ * by the caller so the function stays deterministic and unit-testable.
+ */
+import { matchTpAgent } from "../core/agent-matcher.js";
+/**
+ * Escape phrases that tell us the user genuinely wants open-ended
+ * general-purpose work. Short list of boilerplate — keeping it tight
+ * prevents the escape from eating otherwise-valid routing.
+ *
+ * All checks are lowercased substring matches. Author new entries here
+ * only when tool-audit shows a legitimate pattern getting false-flagged.
+ */
+const ESCAPE_PHRASES = [
+    "ad-hoc",
+    "ad hoc",
+    "one-off",
+    "one off",
+    "open-ended",
+    "research across",
+    "explore multiple",
+    "multi-step",
+    "across the codebase",
+    "across the repo",
+    "general purpose",
+];
+function containsEscape(description) {
+    const n = description.toLowerCase();
+    return ESCAPE_PHRASES.some((p) => n.includes(p));
+}
+/**
+ * Pure decision function. Caller resolves all context (env, mode,
+ * agent index) up front so this stays a plain input → output mapping.
+ */
+export function decidePreTask(input, ctx) {
+    if (input.tool_name !== "Task")
+        return { kind: "allow" };
+    const subagentType = input.tool_input?.subagent_type ?? "";
+    const description = input.tool_input?.description ?? "";
+    // Already a tp-* — routing intent matches catalog. Let it run.
+    if (typeof subagentType === "string" && subagentType.startsWith("tp-")) {
+        return { kind: "allow" };
+    }
+    // No description → nothing to match against. Allow (Claude Code
+    // sometimes dispatches Task with only a subagent_type + session id).
+    if (!description || description.length === 0)
+        return { kind: "allow" };
+    // Author-blessed escape clauses — user is explicitly saying
+    // "this is broad". Respect that.
+    if (containsEscape(description))
+        return { kind: "allow" };
+    const hit = matchTpAgent(description, ctx.agentIndex);
+    if (!hit)
+        return { kind: "allow" };
+    const suggestion = `Consider dispatching \`${hit.agent}\` instead of \`${subagentType || "general-purpose"}\` — ` +
+        `the description matches its trigger phrases (confidence: ${hit.confidence}). ` +
+        `tp-* agents run under a tighter budget and output in terse style, typically ` +
+        `~50-70 % fewer tokens than general-purpose. ` +
+        `Escape: add "ad-hoc" or "open-ended" to the description to bypass, or set ` +
+        `TOKEN_PILOT_MODE=advisory for warn-only behaviour.`;
+    const hardBlock = ctx.force ||
+        ctx.mode === "strict" ||
+        (ctx.mode === "deny" && hit.confidence === "high" && ctx.force);
+    if (hardBlock) {
+        return {
+            kind: "deny",
+            reason: suggestion,
+        };
+    }
+    return { kind: "advise", message: suggestion };
+}
+/**
+ * Render the Claude Code hook JSON response.
+ *
+ * - allow  → no output (pass-through)
+ * - advise → permissionDecision=allow + additionalContext
+ * - deny   → permissionDecision=deny + reason
+ */
+export function renderPreTaskOutput(decision) {
+    if (decision.kind === "allow")
+        return null;
+    if (decision.kind === "advise") {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                additionalContext: decision.message,
+            },
+        });
+    }
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: decision.reason,
+        },
+    });
+}
+//# sourceMappingURL=pre-task.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/index.js

@@ -52,6 +52,8 @@ import { assessClaudeMd } from "./cli/claudemd-hygiene.js";
 import { decidePostBashAdvice, renderPostBashHookOutput, } from "./hooks/post-bash.js";
 import { decidePreBash, renderPreBashOutput } from "./hooks/pre-bash.js";
 import { decidePreGrep, renderPreGrepOutput } from "./hooks/pre-grep.js";
+import { decidePreTask, renderPreTaskOutput } from "./hooks/pre-task.js";
+import { getAgentIndex } from "./hooks/post-task.js";
 import { decidePreEdit, renderPreEditOutput, } from "./hooks/pre-edit.js";
 import { isEditPrepared as isEditPreparedFn } from "./core/edit-prep-state.js";
 import { maybeEmitEcosystemReminder } from "./cli/ecosystem-reminder.js";
@@ -184,6 +186,33 @@ export async function main(cliArgs = process.argv.slice(2)) {
             process.exit(0);
             return;
         }
+        case "hook-pre-task": {
+            // v0.31.0 Pack 2 — route general-purpose Task dispatches to a
+            // `tp-*` specialist when the description clearly matches. Default
+            // (deny / advisory mode) is a non-blocking advise; strict mode or
+            // TOKEN_PILOT_FORCE_SUBAGENTS=1 hard-denies on a high-confidence
+            // match. The matcher is lenient by design (false deny is much
+            // worse than a missed nudge — see pre-edit v0.30.4 rollback).
+            try {
+                const stdin = readFileSync(0, "utf-8");
+                const input = JSON.parse(stdin);
+                const agentIndex = await getAgentIndex();
+                const force = process.env.TOKEN_PILOT_FORCE_SUBAGENTS === "1";
+                const decision = decidePreTask(input, {
+                    mode: parseEnforcementMode(process.env.TOKEN_PILOT_MODE),
+                    agentIndex,
+                    force,
+                });
+                const rendered = renderPreTaskOutput(decision);
+                if (rendered)
+                    process.stdout.write(rendered);
+            }
+            catch {
+                /* silent — hook must not break */
+            }
+            process.exit(0);
+            return;
+        }
         case "hook-post-task": {
             try {
                 const stdin = readFileSync(0, "utf-8");