token-pilot 0.35.0 → 0.39.1

package/dist/index.js

@@ -27,6 +27,7 @@ import { installHook, uninstallHook, cleanStaleHookEntries, isTokenPilotPluginEn
 import { runHookEntryPoint } from "./hooks/safe-runner.js";
 import { loadErrors, formatErrorList } from "./core/error-log.js";
 import { appendDiagnostic } from "./core/event-log.js";
+import { startWorkflow, endWorkflow, listWorkflows, workflowStatus, formatWorkflowStatus, formatWorkflowList, } from "./core/workflow.js";
 import { findBinary, installBinary, checkBinaryUpdate, isNewerVersion, } from "./ast-index/binary-manager.js";
 import { loadConfig } from "./config/loader.js";
 import { isDangerousRoot } from "./core/validation.js";
@@ -229,7 +230,30 @@ export async function main(cliArgs = process.argv.slice(2)) {
                         /* never block dispatch on telemetry */
                     });
                 }
-                const rendered = renderPreTaskOutput(decision);
+                // v0.38.0 — fleet budget guard. When a workflow is active and
+                // its token ceiling is within reach, append a wind-down note
+                // to whatever the routing decision produced. The dispatch is
+                // never hard-blocked on budget (a half-finished fan-out is
+                // worse than a small overrun) — we advise, and surface an
+                // over-budget diagnostic so `workflow status` reflects it.
+                const { activeWorkflowId, workflowStatus, isWorkflowNearBudget } = await import("./core/workflow.js");
+                const wfId = activeWorkflowId();
+                let budgetNote = "";
+                if (wfId) {
+                    const st = await workflowStatus(process.cwd(), wfId);
+                    if (st && isWorkflowNearBudget(st)) {
+                        budgetNote =
+                            `\n\n[token-pilot] workflow ${wfId} is at ${st.pct ?? "~"}% of its ` +
+                                `${st.budget_tokens} token ceiling — finish in-flight work and ` +
+                                `report rather than starting new branches.`;
+                        appendDiagnostic(process.cwd(), {
+                            code: "workflow_near_budget",
+                            level: "warn",
+                            detail: { workflow_id: wfId, pct: st.pct, used: st.used_tokens },
+                        }).catch(() => { });
+                    }
+                }
+                const rendered = renderPreTaskOutput(decision, budgetNote);
                 if (rendered)
                     process.stdout.write(rendered);
             });
@@ -348,6 +372,15 @@ export async function main(cliArgs = process.argv.slice(2)) {
             process.stdout.write(formatErrorList(records) + "\n");
             return;
         }
+        case "workflow": {
+            // v0.38.0 — fleet workflow lifecycle. token-pilot owns the
+            // workflow boundary (we set TOKEN_PILOT_WORKFLOW_ID ourselves),
+            // so this works regardless of whether Claude Code's /workflow
+            // propagates an env var. Subcommands: start / end / status / list.
+            const code = await handleWorkflowCli(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
         case "migrate-hooks": {
             // v0.33.0 — clean stale npx-cache / pinned-version token-pilot
             // hook entries from user-level + project-level settings.json so
@@ -903,6 +936,101 @@ export function handleHookEdit() {
         process.stdout.write(rendered);
     process.exit(0);
 }
+/**
+ * v0.38.0 — `token-pilot workflow <subcommand>` CLI.
+ *
+ *   start <goal> [--budget=N] [--max-parallel=N]
+ *       Create a workflow envelope and print an `export
+ *       TOKEN_PILOT_WORKFLOW_ID=<id>` line. Wrap a fan-out batch with
+ *       this so every hook event gets tagged with the id.
+ *   end [<id>]      Stamp the workflow ended (defaults to active env id).
+ *   status [<id>]   Show live budget + task counts (defaults to env id).
+ *   list            All recorded workflows, newest first.
+ *
+ * Returns a process exit code.
+ */
+export async function handleWorkflowCli(argv) {
+    const projectRoot = process.cwd();
+    const sub = argv[0];
+    const flag = (k) => {
+        for (const a of argv) {
+            if (a.startsWith(`--${k}=`))
+                return a.slice(k.length + 3);
+        }
+        return undefined;
+    };
+    const envId = process.env.TOKEN_PILOT_WORKFLOW_ID ||
+        process.env.CLAUDE_CODE_WORKFLOW_ID ||
+        undefined;
+    switch (sub) {
+        case "start": {
+            const goal = argv.slice(1).filter((a) => !a.startsWith("--")).join(" ");
+            if (!goal) {
+                process.stderr.write('workflow start: a goal is required — `token-pilot workflow start "review last sprint"`\n');
+                return 1;
+            }
+            const budgetRaw = flag("budget");
+            const parallelRaw = flag("max-parallel");
+            const env = await startWorkflow({
+                projectRoot,
+                goal,
+                budgetTokens: budgetRaw ? Number(budgetRaw) : null,
+                maxParallel: parallelRaw ? Number(parallelRaw) : null,
+            });
+            // The id goes to stdout as an `export` line so a user can do
+            //   eval "$(token-pilot workflow start '...')"
+            // and have the env var set for the fan-out that follows.
+            process.stdout.write(`export TOKEN_PILOT_WORKFLOW_ID=${env.workflow_id}\n`);
+            process.stderr.write(`[token-pilot] workflow ${env.workflow_id} started` +
+                (env.budget_tokens ? ` · ${env.budget_tokens} token ceiling` : "") +
+                `\n`);
+            return 0;
+        }
+        case "end": {
+            const id = argv[1] && !argv[1].startsWith("--") ? argv[1] : envId;
+            if (!id) {
+                process.stderr.write("workflow end: no id given and TOKEN_PILOT_WORKFLOW_ID not set.\n");
+                return 1;
+            }
+            const env = await endWorkflow(projectRoot, id);
+            if (!env) {
+                process.stderr.write(`workflow end: unknown workflow "${id}".\n`);
+                return 1;
+            }
+            const status = await workflowStatus(projectRoot, id);
+            if (status)
+                process.stdout.write(formatWorkflowStatus(status) + "\n");
+            process.stderr.write(`[token-pilot] workflow ${id} ended.\n`);
+            return 0;
+        }
+        case "status": {
+            const id = argv[1] && !argv[1].startsWith("--") ? argv[1] : envId;
+            if (!id) {
+                process.stderr.write("workflow status: no id given and TOKEN_PILOT_WORKFLOW_ID not set.\n");
+                return 1;
+            }
+            const status = await workflowStatus(projectRoot, id);
+            if (!status) {
+                process.stderr.write(`workflow status: unknown workflow "${id}".\n`);
+                return 1;
+            }
+            process.stdout.write(formatWorkflowStatus(status) + "\n");
+            return 0;
+        }
+        case "list": {
+            const workflows = await listWorkflows(projectRoot);
+            process.stdout.write(formatWorkflowList(workflows) + "\n");
+            return 0;
+        }
+        default:
+            process.stderr.write("Usage: token-pilot workflow <start|end|status|list>\n" +
+                '  start "<goal>" [--budget=N] [--max-parallel=N]\n' +
+                "  end [<id>]\n" +
+                "  status [<id>]\n" +
+                "  list\n");
+            return sub ? 1 : 0;
+    }
+}
 export async function handleInstallHook(projectRoot) {
     // v0.26.5 — plugin-aware early-return. If we're running as a Claude
     // Code plugin (CLAUDE_PLUGIN_ROOT set) the hooks are already declared

package/package.json

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

package/skills/guide/SKILL.md

@@ -3,6 +3,17 @@ name: guide
 description: Show a quick-reference guide for all Token Pilot tools — when to use each one
 command: guide
 user_invocable: true
+# v0.36.0 — disallowed-tools is a Claude Code 2.1.152+ field that
+# strips the listed tools from the model's surface while this skill
+# is active. The guide just renders Markdown; it never needs Edit /
+# Write / Bash / Task. Defense-in-depth so a runaway model can't
+# mutate the workspace while a help screen is on display.
+disallowed-tools:
+  - Bash
+  - Edit
+  - MultiEdit
+  - Write
+  - Task
 ---
 
 Display the following Token Pilot tool reference to the user. Show it exactly as formatted below.

package/skills/install/SKILL.md

@@ -3,6 +3,16 @@ name: install
 description: Install or check ast-index binary (auto-downloads if missing)
 command: install
 user_invocable: true
+# v0.36.0 — disallowed-tools (Claude Code 2.1.152+). The install
+# skill drives one `npx token-pilot install-ast-index` Bash command;
+# nothing else. Keep Bash, block all write/edit/delegation tools so
+# a rogue interpretation can't extend the install into arbitrary
+# workspace mutation.
+disallowed-tools:
+  - Edit
+  - MultiEdit
+  - Write
+  - Task
 ---
 
 Run the following command to install or verify the ast-index binary:

package/skills/stats/SKILL.md

@@ -3,6 +3,14 @@ name: stats
 description: Show Token Pilot session analytics — token savings, per-tool breakdown, top files, per-agent grouping
 command: stats
 user_invocable: true
+# v0.36.0 — disallowed-tools (Claude Code 2.1.152+). stats only reads
+# the events log and runs `token-pilot stats` variants. No
+# Edit/Write/Task ever — block them defensively.
+disallowed-tools:
+  - Edit
+  - MultiEdit
+  - Write
+  - Task
 ---
 
 Two entry points: