token-pilot 0.36.0 → 0.39.2

package/dist/core/workflow.js

@@ -0,0 +1,269 @@
+/**
+ * v0.38.0 — fleet workflow lifecycle.
+ *
+ * The fleet design note (docs/design/2026-06-tp-fleet-dynamic-workflows.md)
+ * flagged one blocker: it assumed Claude Code's `/workflow` would set a
+ * propagated workflow-id env var on dispatched subagents. The 2.1.131
+ * bundle has no such variable, so building tagging/budget against it
+ * would be the v0.34.0-args mistake again (shipping against an
+ * interface that may not exist).
+ *
+ * Resolution: token-pilot OWNS the workflow boundary. A user wraps a
+ * batch of fan-out work with `token-pilot workflow start` / `end`,
+ * which writes an envelope file and exports `TOKEN_PILOT_WORKFLOW_ID`.
+ * Every hook reads that env var and tags its events. No dependency on
+ * Claude Code's `/workflow` — and if CC ever propagates its own
+ * workflow id env var, we read that too (see activeWorkflowId).
+ *
+ * State lives in `<projectRoot>/.token-pilot/workflows/`:
+ *   <id>.json                 — the envelope (goal, budget, started/ended)
+ * Events stay in the normal hook-events.jsonl, tagged with workflow_id.
+ *
+ * Pure-ish: all filesystem helpers swallow errors (telemetry must
+ * never break a hook). The `now`/`id` injection points keep the unit
+ * tests deterministic.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { appendEvent, loadEventsTree, } from "./event-log.js";
+export const WORKFLOW_SUBDIR = ".token-pilot/workflows";
+// ─── env access ──────────────────────────────────────────────────────
+/**
+ * Resolve the active workflow id. token-pilot's own env var takes
+ * precedence.
+ *
+ * Note (verified against CC 2.1.161): Claude Code's `/workflow` does
+ * NOT export a per-workflow id env var to dispatched subagents — the
+ * bundle only has the `CLAUDE_CODE_WORKFLOWS` feature flag and an
+ * internal `WorkflowId`. The extra names below are a harmless
+ * forward-compat probe (they return null today); token-pilot's fleet
+ * workflows are independent and rely solely on our own
+ * `TOKEN_PILOT_WORKFLOW_ID`. Returns null when none is set.
+ */
+export function activeWorkflowId(env = process.env) {
+    return (env.TOKEN_PILOT_WORKFLOW_ID ||
+        env.CLAUDE_CODE_WORKFLOW_ID ||
+        env.CLAUDE_WORKFLOW_ID ||
+        null);
+}
+// ─── id generation ───────────────────────────────────────────────────
+/**
+ * Build a workflow id. Format `wf-<base36 ts>-<suffix>`. `now` and
+ * `suffix` are injectable for deterministic tests; production passes a
+ * timestamp + a short random token.
+ */
+export function makeWorkflowId(now, suffix) {
+    return `wf-${now.toString(36)}-${suffix}`;
+}
+// ─── paths ───────────────────────────────────────────────────────────
+function workflowDir(projectRoot) {
+    return join(projectRoot, WORKFLOW_SUBDIR);
+}
+function envelopePath(projectRoot, id) {
+    return join(workflowDir(projectRoot), `${id}.json`);
+}
+/**
+ * Create a workflow envelope and return it. The caller is responsible
+ * for exporting `TOKEN_PILOT_WORKFLOW_ID=<id>` into the environment of
+ * the work that follows (the CLI prints an `export` line for this).
+ */
+export async function startWorkflow(input) {
+    const now = input.now ?? Date.now();
+    const suffix = input.idSuffix ?? Math.floor(now % 1_000_000).toString(36).padStart(4, "0");
+    const envelope = {
+        workflow_id: makeWorkflowId(now, suffix),
+        started_at: now,
+        ended_at: null,
+        goal: input.goal,
+        budget_tokens: input.budgetTokens ?? null,
+        max_parallel: input.maxParallel ?? null,
+    };
+    try {
+        await fs.mkdir(workflowDir(input.projectRoot), { recursive: true });
+        await fs.writeFile(envelopePath(input.projectRoot, envelope.workflow_id), JSON.stringify(envelope, null, 2) + "\n");
+    }
+    catch {
+        /* best-effort — never block the caller */
+    }
+    return envelope;
+}
+export async function loadWorkflow(projectRoot, id) {
+    try {
+        const raw = await fs.readFile(envelopePath(projectRoot, id), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.workflow_id === "string")
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Mark a workflow ended (stamps ended_at) and emit a frozen
+ * `event:"workflow"` completion record into hook-events.jsonl.
+ *
+ * v0.39.0 — the envelope stores only the static plan (goal, budget,
+ * timestamps); the aggregates (tokens used, task count) are computed
+ * live from tagged events. Freezing them in a single summary row at
+ * end time makes historical analysis cheap and survives event-log
+ * rotation (which could otherwise drop the underlying per-task rows).
+ * Returns the updated envelope, or null when the id is unknown.
+ */
+export async function endWorkflow(projectRoot, id, now = Date.now()) {
+    const env = await loadWorkflow(projectRoot, id);
+    if (!env)
+        return null;
+    env.ended_at = now;
+    try {
+        await fs.writeFile(envelopePath(projectRoot, id), JSON.stringify(env, null, 2) + "\n");
+    }
+    catch {
+        /* best-effort */
+    }
+    // Freeze the aggregates into a completion event.
+    try {
+        const events = await loadEventsTree(projectRoot);
+        const status = computeWorkflowStatus(env, events);
+        const summary = {
+            ts: now,
+            session_id: "workflow",
+            agent_type: null,
+            agent_id: null,
+            workflow_id: id,
+            event: "workflow",
+            file: "",
+            lines: 0,
+            estTokens: status.used_tokens,
+            summaryTokens: 0,
+            savedTokens: 0,
+            level: "info",
+            code: "workflow_complete",
+            detail: {
+                goal: env.goal,
+                budget_tokens: env.budget_tokens,
+                used_tokens: status.used_tokens,
+                pct: status.pct,
+                task_count: status.task_count,
+                over_budget_workers: status.over_budget_workers,
+                duration_ms: env.ended_at - env.started_at,
+            },
+        };
+        // Pass the workflow_id explicitly so appendEvent keeps it even if
+        // the env var has already been unset by the time `end` runs.
+        await appendEvent(projectRoot, summary);
+    }
+    catch {
+        /* completion telemetry is best-effort */
+    }
+    return env;
+}
+/** List all workflow envelopes, newest first. */
+export async function listWorkflows(projectRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(workflowDir(projectRoot));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const env = await loadWorkflow(projectRoot, name.replace(/\.json$/, ""));
+        if (env)
+            out.push(env);
+    }
+    out.sort((a, b) => b.started_at - a.started_at);
+    return out;
+}
+// ─── budget + telemetry ──────────────────────────────────────────────
+/**
+ * Pure aggregation of a workflow's status from its envelope + the set
+ * of events tagged with its id. Separated from I/O so tests drive it
+ * directly.
+ */
+export function computeWorkflowStatus(envelope, events) {
+    const mine = events.filter((e) => e.workflow_id === envelope.workflow_id);
+    let used = 0;
+    let taskCount = 0;
+    let overWorkers = 0;
+    for (const e of mine) {
+        if (e.event === "task") {
+            taskCount++;
+            used += e.estTokens || 0;
+            if (e.overBudget)
+                overWorkers++;
+        }
+    }
+    const pct = envelope.budget_tokens && envelope.budget_tokens > 0
+        ? Math.round((used / envelope.budget_tokens) * 100)
+        : null;
+    return {
+        workflow_id: envelope.workflow_id,
+        goal: envelope.goal,
+        budget_tokens: envelope.budget_tokens,
+        used_tokens: used,
+        pct,
+        event_count: mine.length,
+        task_count: taskCount,
+        over_budget_workers: overWorkers,
+        ended: envelope.ended_at != null,
+    };
+}
+/**
+ * Load a workflow's live status from disk (envelope + tagged events
+ * across the repo tree). Returns null when the id is unknown.
+ */
+export async function workflowStatus(projectRoot, id) {
+    const envelope = await loadWorkflow(projectRoot, id);
+    if (!envelope)
+        return null;
+    const events = await loadEventsTree(projectRoot);
+    return computeWorkflowStatus(envelope, events);
+}
+/**
+ * Returns true when the workflow's used tokens are within `nearPct`
+ * percent of its ceiling (or over). Used by the pre-task hook to warn
+ * the fleet to wind down before the ceiling is breached. False when no
+ * budget is set.
+ */
+export function isWorkflowNearBudget(status, nearPct = 90) {
+    if (status.budget_tokens == null || status.budget_tokens <= 0)
+        return false;
+    return status.used_tokens >= status.budget_tokens * (nearPct / 100);
+}
+// ─── formatting ──────────────────────────────────────────────────────
+function humanTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}k`;
+    return `${n}`;
+}
+export function formatWorkflowStatus(status) {
+    const lines = [];
+    lines.push(`workflow ${status.workflow_id}${status.ended ? " (ended)" : ""}`);
+    lines.push(`  goal:        ${status.goal}`);
+    const budget = status.budget_tokens != null
+        ? `${humanTokens(status.budget_tokens)} ceiling`
+        : "no ceiling";
+    const pct = status.pct != null ? ` (${status.pct}%)` : "";
+    lines.push(`  budget:      ${budget} · ${humanTokens(status.used_tokens)} used${pct}`);
+    lines.push(`  tasks:       ${status.task_count} dispatched · ${status.over_budget_workers} over-budget`);
+    lines.push(`  events:      ${status.event_count} tagged`);
+    return lines.join("\n");
+}
+export function formatWorkflowList(workflows) {
+    if (workflows.length === 0)
+        return "No workflows recorded.";
+    const lines = [`${workflows.length} workflow(s):`];
+    for (const w of workflows) {
+        const state = w.ended_at ? "ended " : "active";
+        const budget = w.budget_tokens != null ? `${humanTokens(w.budget_tokens)} ceiling` : "—";
+        lines.push(`  [${state}] ${w.workflow_id}  ${budget}  ${w.goal}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=workflow.js.map

package/dist/hooks/installer.js

@@ -130,12 +130,21 @@ function createHookConfig(options) {
             PostToolUse: [
                 {
                     matcher: "Bash",
-                    // v0.35.0 — async: true keeps telemetry off the hot path
+                    // v0.35.0 — async: true keeps the advisory off the hot path.
+                    // post-bash writes NO telemetry (advisory-only), so detached
+                    // execution is safe here.
                     hooks: [hookEntry("hook-post-bash", options, { async: true })],
                 },
                 {
                     matcher: "Task",
-                    hooks: [hookEntry("hook-post-task", options, { async: true })],
+                    // v0.39.2 — post-task MUST run synchronously. It writes the
+                    // `event:"task"` record via appendEvent (mkdir + stat +
+                    // appendFile). Under `async: true` Claude Code fires the hook
+                    // detached and may reap the process before those writes flush
+                    // — the suspected cause of persistently zero task events in
+                    // hook-events.jsonl despite subagents being dispatched.
+                    // Telemetry integrity > the ~5ms saved on a non-hot-path hook.
+                    hooks: [hookEntry("hook-post-task", options)],
                 },
             ],
         },

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

@@ -19,9 +19,24 @@ export declare const OVER_BUDGET_LOG = "over-budget.log";
 export declare const OVER_BUDGET_TOLERANCE = 0.1;
 export declare function parseAgentBudget(body: string): number | null;
 /**
- * Count approx tokens in the `tool_response.content[*].text` blocks of a
- * PostToolUse hook input for the Task tool. Returns null for anything
- * other than a well-formed Task response.
+ * Extract the subagent's token count from a PostToolUse:Task hook input.
+ *
+ * v0.37.0 — the Task tool's `tool_response` carries an authoritative
+ * `totalTokens` field. Verified by inspecting the Claude Code 2.1.131
+ * bundle: the Task result object is
+ *   { agentId, agentType, content, totalDurationMs, totalTokens, totalToolUseCount, usage }
+ * Earlier versions of this function only summed `content[*].text`
+ * lengths / 4 — a rough heuristic that returned 0 whenever the
+ * response wasn't a `{content:[{text}]}` array, leaving the budget
+ * watchdog and task token-weighting permanently at zero.
+ *
+ * Resolution order:
+ *   1. `tool_response.totalTokens` (exact, preferred)
+ *   2. `tool_response.usage.output_tokens` (exact, alternate shape)
+ *   3. char/4 over `content[*].text` (legacy heuristic fallback)
+ *   4. char/4 over a plain string `content`
+ *
+ * Returns null only when no signal at all is available.
  */
 export declare function extractSubagentTokens(input: {
     tool_name?: string;

package/dist/hooks/post-task.js

@@ -30,9 +30,24 @@ export function parseAgentBudget(body) {
     return Number.isFinite(n) && n > 0 ? n : null;
 }
 /**
- * Count approx tokens in the `tool_response.content[*].text` blocks of a
- * PostToolUse hook input for the Task tool. Returns null for anything
- * other than a well-formed Task response.
+ * Extract the subagent's token count from a PostToolUse:Task hook input.
+ *
+ * v0.37.0 — the Task tool's `tool_response` carries an authoritative
+ * `totalTokens` field. Verified by inspecting the Claude Code 2.1.131
+ * bundle: the Task result object is
+ *   { agentId, agentType, content, totalDurationMs, totalTokens, totalToolUseCount, usage }
+ * Earlier versions of this function only summed `content[*].text`
+ * lengths / 4 — a rough heuristic that returned 0 whenever the
+ * response wasn't a `{content:[{text}]}` array, leaving the budget
+ * watchdog and task token-weighting permanently at zero.
+ *
+ * Resolution order:
+ *   1. `tool_response.totalTokens` (exact, preferred)
+ *   2. `tool_response.usage.output_tokens` (exact, alternate shape)
+ *   3. char/4 over `content[*].text` (legacy heuristic fallback)
+ *   4. char/4 over a plain string `content`
+ *
+ * Returns null only when no signal at all is available.
  */
 export function extractSubagentTokens(input) {
     if (input.tool_name !== "Task")
@@ -40,15 +55,33 @@ export function extractSubagentTokens(input) {
     const resp = input.tool_response;
     if (!resp || typeof resp !== "object")
         return null;
-    const parts = Array.isArray(resp.content) ? resp.content : [];
-    let chars = 0;
-    for (const p of parts) {
-        if (typeof p?.text === "string")
-            chars += p.text.length;
+    // 1. Authoritative totalTokens.
+    if (typeof resp.totalTokens === "number" && resp.totalTokens > 0) {
+        return Math.round(resp.totalTokens);
     }
-    if (chars === 0)
-        return null;
-    return Math.ceil(chars / 4);
+    // 2. usage shape (alternate / future-proof).
+    const usage = resp.usage;
+    if (usage && typeof usage === "object") {
+        const out = usage.total_tokens ?? usage.output_tokens;
+        if (typeof out === "number" && out > 0)
+            return Math.round(out);
+    }
+    // 3. Legacy heuristic over content[*].text.
+    if (Array.isArray(resp.content)) {
+        let chars = 0;
+        for (const p of resp.content) {
+            if (p && typeof p.text === "string") {
+                chars += p.text.length;
+            }
+        }
+        if (chars > 0)
+            return Math.ceil(chars / 4);
+    }
+    // 4. Plain-string content.
+    if (typeof resp.content === "string" && resp.content.length > 0) {
+        return Math.ceil(resp.content.length / 4);
+    }
+    return null;
 }
 export function decideBudgetAdvice(input) {
     if (input.budget == null || input.budget <= 0) {

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

@@ -63,9 +63,14 @@ export declare function decidePreTask(input: PreTaskInput, ctx: PreTaskContext):
 /**
  * Render the Claude Code hook JSON response.
  *
- * - allow  → no output (pass-through)
- * - advise → permissionDecision=allow + additionalContext
- * - deny   → permissionDecision=deny + reason
+ * - allow  → no output (pass-through), UNLESS `append` carries a fleet
+ *            budget note — then emit an allow + additionalContext so the
+ *            note still reaches the agent.
+ * - advise → permissionDecision=allow + additionalContext (+ append)
+ * - deny   → permissionDecision=deny + reason (+ append)
+ *
+ * v0.38.0 — `append` is an optional trailing string (the workflow
+ * near-budget wind-down note). Empty / omitted leaves output unchanged.
  */
-export declare function renderPreTaskOutput(decision: PreTaskDecision): string | null;
+export declare function renderPreTaskOutput(decision: PreTaskDecision, append?: string): string | null;
 //# sourceMappingURL=pre-task.d.ts.map

package/dist/hooks/pre-task.js

@@ -132,19 +132,34 @@ export function decidePreTask(input, ctx) {
 /**
  * Render the Claude Code hook JSON response.
  *
- * - allow  → no output (pass-through)
- * - advise → permissionDecision=allow + additionalContext
- * - deny   → permissionDecision=deny + reason
+ * - allow  → no output (pass-through), UNLESS `append` carries a fleet
+ *            budget note — then emit an allow + additionalContext so the
+ *            note still reaches the agent.
+ * - advise → permissionDecision=allow + additionalContext (+ append)
+ * - deny   → permissionDecision=deny + reason (+ append)
+ *
+ * v0.38.0 — `append` is an optional trailing string (the workflow
+ * near-budget wind-down note). Empty / omitted leaves output unchanged.
  */
-export function renderPreTaskOutput(decision) {
-    if (decision.kind === "allow")
-        return null;
+export function renderPreTaskOutput(decision, append = "") {
+    const extra = append || "";
+    if (decision.kind === "allow") {
+        if (!extra)
+            return null;
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                additionalContext: extra.trimStart(),
+            },
+        });
+    }
     if (decision.kind === "advise") {
         return JSON.stringify({
             hookSpecificOutput: {
                 hookEventName: "PreToolUse",
                 permissionDecision: "allow",
-                additionalContext: decision.message,
+                additionalContext: decision.message + extra,
             },
         });
     }
@@ -152,7 +167,7 @@ export function renderPreTaskOutput(decision) {
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: "deny",
-            permissionDecisionReason: decision.reason,
+            permissionDecisionReason: decision.reason + extra,
         },
     });
 }

package/dist/hooks/session-start.js

@@ -318,6 +318,18 @@ export async function handleSessionStart(opts) {
                         : `${surfaced}`;
                 sessionTitle = `[TP] ${human} saved`;
             }
+            // v0.38.0 — when a fleet workflow is active, prefer a
+            // workflow-progress title so a long fan-out run shows live
+            // task count + budget in the window title.
+            const { activeWorkflowId, workflowStatus } = await import("../core/workflow.js");
+            const wfId = activeWorkflowId();
+            if (wfId) {
+                const st = await workflowStatus(opts.projectRoot, wfId);
+                if (st) {
+                    const pct = st.pct != null ? ` · ${st.pct}%` : "";
+                    sessionTitle = `[TP] wf · ${st.task_count} tasks${pct}`;
+                }
+            }
         }
         catch {
             /* sessionTitle is best-effort decoration; never block startup */

package/dist/index.d.ts

@@ -58,6 +58,20 @@ export declare function runHookReadDispatch(filePathArg: string | undefined, mod
  * (file existence, prep-state lookup, env vars).
  */
 export declare function handleHookEdit(): void;
+/**
+ * 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 declare function handleWorkflowCli(argv: string[]): Promise<number>;
 export declare function handleInstallHook(projectRoot: string): Promise<void>;
 export declare function handleUninstallHook(projectRoot: string): Promise<void>;
 export declare function handleInstallAstIndex(): Promise<void>;

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/hooks/hooks.json

@@ -92,8 +92,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-task",
-            "async": true
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-task"
           }
         ]
       }