@femtomc/mu-agent 26.2.86 → 26.2.87

package/dist/extensions/planning-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planning-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/planning-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA4FpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAoHnD;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"planning-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/planning-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA4LpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QA8KnD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/extensions/planning-ui.js

@@ -5,6 +5,33 @@ const DEFAULT_STEPS = [
     "Present plan with IDs, ordering, risks",
     "Refine with user feedback until approved",
 ];
+const BAR_CHARS = ["░", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"];
+function phaseTone(phase) {
+    switch (phase) {
+        case "investigating":
+            return "dim";
+        case "drafting":
+            return "accent";
+        case "reviewing":
+            return "warning";
+        case "approved":
+            return "success";
+    }
+}
+function progressBar(done, total, width = 10) {
+    if (width <= 0 || total <= 0) {
+        return "";
+    }
+    const clampedDone = Math.max(0, Math.min(total, done));
+    const filled = (clampedDone / total) * width;
+    const full = Math.floor(filled);
+    const frac = filled - full;
+    const fracIdx = Math.round(frac * (BAR_CHARS.length - 1));
+    const empty = width - full - (fracIdx > 0 ? 1 : 0);
+    return (BAR_CHARS[BAR_CHARS.length - 1].repeat(full) +
+        (fracIdx > 0 ? BAR_CHARS[fracIdx] : "") +
+        BAR_CHARS[0].repeat(Math.max(0, empty)));
+}
 function createDefaultState() {
     return {
         enabled: false,
@@ -37,17 +64,28 @@ function renderPlanningUi(ctx, state) {
     const done = state.steps.filter((step) => step.done).length;
     const total = state.steps.length;
     const phase = summarizePhase(state.phase);
-    const rootSuffix = state.rootIssueId ? ` root:${state.rootIssueId}` : "";
-    ctx.ui.setStatus("mu-planning", ctx.ui.theme.fg("dim", `planning ${done}/${total} · ${phase}${rootSuffix}`));
+    const phaseColor = phaseTone(state.phase);
+    const rootLabel = state.rootIssueId ?? "(unset)";
+    const meter = progressBar(done, total, 10);
+    ctx.ui.setStatus("mu-planning", [
+        ctx.ui.theme.fg("dim", "plan"),
+        ctx.ui.theme.fg(phaseColor, phase),
+        ctx.ui.theme.fg("dim", `${done}/${total}`),
+        ctx.ui.theme.fg(phaseColor, meter),
+        ctx.ui.theme.fg("muted", `root:${rootLabel}`),
+    ].join(` ${ctx.ui.theme.fg("muted", "·")} `));
     const lines = [
-        ctx.ui.theme.fg("accent", `Planning (${phase})`),
-        state.rootIssueId
-            ? ctx.ui.theme.fg("dim", `  root issue: ${state.rootIssueId}`)
-            : ctx.ui.theme.fg("dim", "  root issue: (unset)"),
+        ctx.ui.theme.fg("accent", ctx.ui.theme.bold("Planning board")),
+        `  ${ctx.ui.theme.fg("muted", "phase:")} ${ctx.ui.theme.fg(phaseColor, phase)}`,
+        `  ${ctx.ui.theme.fg("muted", "progress:")} ${ctx.ui.theme.fg("dim", `${done}/${total}`)} ${ctx.ui.theme.fg(phaseColor, meter)}`,
+        `  ${ctx.ui.theme.fg("muted", "root:")} ${ctx.ui.theme.fg("dim", rootLabel)}`,
+        `  ${ctx.ui.theme.fg("dim", "────────────────────────────")}`,
         ...state.steps.map((step, index) => {
             const mark = step.done ? ctx.ui.theme.fg("success", "☑") : ctx.ui.theme.fg("muted", "☐");
-            return `${mark} ${index + 1}. ${step.label}`;
+            const label = step.done ? ctx.ui.theme.fg("dim", step.label) : ctx.ui.theme.fg("text", step.label);
+            return `${mark} ${ctx.ui.theme.fg("muted", `${index + 1}.`)} ${label}`;
         }),
+        ctx.ui.theme.fg("muted", "  /mu plan status · /mu plan phase <...>"),
     ];
     ctx.ui.setWidget("mu-planning", lines, { placement: "belowEditor" });
 }
@@ -67,6 +105,32 @@ function parsePlanningPhase(raw) {
     }
     return null;
 }
+function planningDetails(state) {
+    return {
+        enabled: state.enabled,
+        phase: state.phase,
+        root_issue_id: state.rootIssueId,
+        steps: state.steps.map((step, index) => ({
+            index: index + 1,
+            label: step.label,
+            done: step.done,
+        })),
+    };
+}
+function planningStatusSummary(state) {
+    const done = state.steps.filter((step) => step.done).length;
+    const root = state.rootIssueId ?? "(unset)";
+    return `Planning HUD: ${state.enabled ? "enabled" : "disabled"}\nphase: ${state.phase}\nroot: ${root}\nsteps: ${done}/${state.steps.length}`;
+}
+function planningToolError(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        details: {
+            ok: false,
+            error: message,
+        },
+    };
+}
 export function planningUiExtension(pi) {
     let state = createDefaultState();
     const notify = (ctx, message, level = "info") => {
@@ -75,6 +139,66 @@ export function planningUiExtension(pi) {
     const refresh = (ctx) => {
         renderPlanningUi(ctx, state);
     };
+    const applyPlanningAction = (params) => {
+        switch (params.action) {
+            case "status":
+                return { ok: true, message: planningStatusSummary(state), level: "info" };
+            case "on":
+                state.enabled = true;
+                return { ok: true, message: "Planning HUD enabled.", level: "info" };
+            case "off":
+                state.enabled = false;
+                return { ok: true, message: "Planning HUD disabled.", level: "info" };
+            case "toggle":
+                state.enabled = !state.enabled;
+                return { ok: true, message: `Planning HUD ${state.enabled ? "enabled" : "disabled"}.`, level: "info" };
+            case "reset":
+                state = createDefaultState();
+                return { ok: true, message: "Planning HUD state reset.", level: "info" };
+            case "phase": {
+                const phase = parsePlanningPhase(params.phase ?? "");
+                if (!phase) {
+                    return { ok: false, message: "Invalid phase.", level: "error" };
+                }
+                state.phase = phase;
+                state.enabled = true;
+                return { ok: true, message: `Planning phase set to ${phase}.`, level: "info" };
+            }
+            case "root": {
+                const root = params.root_issue_id?.trim();
+                if (!root) {
+                    return { ok: false, message: "Missing root issue id.", level: "error" };
+                }
+                state.rootIssueId = root.toLowerCase() === "clear" ? null : root;
+                state.enabled = true;
+                return { ok: true, message: `Planning root set to ${state.rootIssueId ?? "(unset)"}.`, level: "info" };
+            }
+            case "check":
+            case "uncheck":
+            case "toggle_step": {
+                const step = params.step;
+                if (typeof step !== "number" || !Number.isFinite(step)) {
+                    return { ok: false, message: "Step index must be a number.", level: "error" };
+                }
+                const parsed = Math.trunc(step);
+                if (parsed < 1 || parsed > state.steps.length) {
+                    return { ok: false, message: `Step index out of range (1-${state.steps.length}).`, level: "error" };
+                }
+                const index = parsed - 1;
+                if (params.action === "check") {
+                    state.steps[index].done = true;
+                }
+                else if (params.action === "uncheck") {
+                    state.steps[index].done = false;
+                }
+                else {
+                    state.steps[index].done = !state.steps[index].done;
+                }
+                state.enabled = true;
+                return { ok: true, message: `Planning step ${index + 1} updated.`, level: "info" };
+            }
+        }
+    };
     pi.on("session_start", async (_event, ctx) => {
         refresh(ctx);
     });
@@ -90,89 +214,88 @@ export function planningUiExtension(pi) {
                 .trim()
                 .split(/\s+/)
                 .filter((token) => token.length > 0);
-            if (tokens.length === 0 || tokens[0] === "status") {
-                const done = state.steps.filter((step) => step.done).length;
-                const root = state.rootIssueId ?? "(unset)";
-                ctx.ui.notify(`Planning HUD: ${state.enabled ? "enabled" : "disabled"}\nphase: ${state.phase}\nroot: ${root}\nsteps: ${done}/${state.steps.length}`, "info");
-                refresh(ctx);
-                return;
-            }
-            switch (tokens[0]) {
+            const command = tokens[0] ?? "status";
+            let params;
+            switch (command) {
                 case "on":
-                    state.enabled = true;
-                    refresh(ctx);
-                    ctx.ui.notify("Planning HUD enabled.", "info");
-                    return;
+                    params = { action: "on" };
+                    break;
                 case "off":
-                    state.enabled = false;
-                    refresh(ctx);
-                    ctx.ui.notify("Planning HUD disabled.", "info");
-                    return;
+                    params = { action: "off" };
+                    break;
                 case "toggle":
-                    state.enabled = !state.enabled;
-                    refresh(ctx);
-                    ctx.ui.notify(`Planning HUD ${state.enabled ? "enabled" : "disabled"}.`, "info");
-                    return;
+                    params = { action: "toggle" };
+                    break;
+                case "status":
+                    params = { action: "status" };
+                    break;
                 case "reset":
-                    state = createDefaultState();
-                    refresh(ctx);
-                    ctx.ui.notify("Planning HUD state reset.", "info");
-                    return;
-                case "phase": {
-                    const phase = parsePlanningPhase(tokens[1] ?? "");
-                    if (!phase) {
-                        notify(ctx, "Invalid phase.", "error");
-                        return;
-                    }
-                    state.phase = phase;
-                    state.enabled = true;
-                    refresh(ctx);
-                    ctx.ui.notify(`Planning phase set to ${phase}.`, "info");
-                    return;
-                }
-                case "root": {
-                    const value = (tokens[1] ?? "").trim();
-                    if (!value) {
-                        notify(ctx, "Missing root issue id.", "error");
-                        return;
-                    }
-                    state.rootIssueId = value.toLowerCase() === "clear" ? null : value;
-                    state.enabled = true;
-                    refresh(ctx);
-                    ctx.ui.notify(`Planning root set to ${state.rootIssueId ?? "(unset)"}.`, "info");
-                    return;
-                }
+                    params = { action: "reset" };
+                    break;
+                case "phase":
+                    params = { action: "phase", phase: tokens[1] };
+                    break;
+                case "root":
+                    params = { action: "root", root_issue_id: tokens[1] };
+                    break;
                 case "check":
+                    params = { action: "check", step: Number.parseInt(tokens[1] ?? "", 10) };
+                    break;
                 case "uncheck":
-                case "toggle-step": {
-                    const indexRaw = tokens[1] ?? "";
-                    const parsed = Number.parseInt(indexRaw, 10);
-                    if (!Number.isFinite(parsed)) {
-                        notify(ctx, "Step index must be a number.", "error");
-                        return;
-                    }
-                    if (parsed < 1 || parsed > state.steps.length) {
-                        notify(ctx, `Step index out of range (1-${state.steps.length}).`, "error");
-                        return;
-                    }
-                    const index = parsed - 1;
-                    if (tokens[0] === "check") {
-                        state.steps[index].done = true;
-                    }
-                    else if (tokens[0] === "uncheck") {
-                        state.steps[index].done = false;
-                    }
-                    else {
-                        state.steps[index].done = !state.steps[index].done;
-                    }
-                    state.enabled = true;
-                    refresh(ctx);
-                    ctx.ui.notify(`Planning step ${index + 1} updated.`, "info");
-                    return;
-                }
+                    params = { action: "uncheck", step: Number.parseInt(tokens[1] ?? "", 10) };
+                    break;
+                case "toggle-step":
+                    params = { action: "toggle_step", step: Number.parseInt(tokens[1] ?? "", 10) };
+                    break;
                 default:
-                    notify(ctx, `Unknown plan command: ${tokens[0]}`, "error");
+                    notify(ctx, `Unknown plan command: ${command}`, "error");
+                    return;
+            }
+            const result = applyPlanningAction(params);
+            refresh(ctx);
+            if (!result.ok) {
+                notify(ctx, result.message, result.level ?? "error");
+                return;
+            }
+            ctx.ui.notify(result.message, result.level ?? "info");
+        },
+    });
+    pi.registerTool({
+        name: "mu_planning_hud",
+        label: "mu planning HUD",
+        description: "Control or inspect planning HUD state (phase, root issue, checklist progress).",
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["status", "on", "off", "toggle", "reset", "phase", "root", "check", "uncheck", "toggle_step"],
+                },
+                phase: {
+                    type: "string",
+                    enum: ["investigating", "drafting", "reviewing", "approved"],
+                },
+                root_issue_id: { type: "string" },
+                step: { type: "integer", minimum: 1 },
+            },
+            required: ["action"],
+            additionalProperties: false,
+        },
+        execute: async (_toolCallId, paramsRaw, _signal, _onUpdate, ctx) => {
+            const params = paramsRaw;
+            const result = applyPlanningAction(params);
+            refresh(ctx);
+            if (!result.ok) {
+                return planningToolError(result.message);
             }
+            return {
+                content: [{ type: "text", text: `${result.message}\n\n${planningStatusSummary(state)}` }],
+                details: {
+                    ok: true,
+                    action: params.action,
+                    ...planningDetails(state),
+                },
+            };
         },
     });
 }

package/dist/extensions/subagents-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subagents-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/subagents-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAuapF,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,QAmRpD;AAED,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"subagents-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/subagents-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA+fpF,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,QAwWpD;AAED,eAAe,oBAAoB,CAAC"}

package/dist/extensions/subagents-ui.js

@@ -251,10 +251,37 @@ async function listIssueSlices(rootId, roleTag) {
         error: null,
     };
 }
-function formatIssueLine(ctx, issue) {
+function formatIssueLine(ctx, issue, opts = {}) {
+    const marker = opts.marker ?? "•";
+    const tone = opts.tone ?? "accent";
     const id = ctx.ui.theme.fg("dim", issue.id);
     const priority = ctx.ui.theme.fg("muted", `p${issue.priority}`);
-    return `  ${ctx.ui.theme.fg("success", "•")} ${id} ${priority} ${truncateOneLine(issue.title)}`;
+    const title = ctx.ui.theme.fg("text", truncateOneLine(issue.title));
+    return `  ${ctx.ui.theme.fg(tone, marker)} ${id} ${priority} ${title}`;
+}
+function queueMeter(value, total, width = 10) {
+    if (width <= 0 || total <= 0) {
+        return "";
+    }
+    const clamped = Math.max(0, Math.min(total, value));
+    const full = Math.floor((clamped / total) * width);
+    const empty = Math.max(0, width - full);
+    return "█".repeat(full) + "░".repeat(empty);
+}
+function formatRefreshAge(lastUpdatedMs) {
+    if (lastUpdatedMs == null) {
+        return "never";
+    }
+    const deltaSec = Math.max(0, Math.round((Date.now() - lastUpdatedMs) / 1000));
+    if (deltaSec < 60) {
+        return `${deltaSec}s ago`;
+    }
+    const mins = Math.floor(deltaSec / 60);
+    if (mins < 60) {
+        return `${mins}m ago`;
+    }
+    const hours = Math.floor(mins / 60);
+    return `${hours}h ago`;
 }
 function renderSubagentsUi(ctx, state) {
     if (!ctx.hasUI) {
@@ -265,57 +292,69 @@ function renderSubagentsUi(ctx, state) {
         ctx.ui.setWidget("mu-subagents", undefined);
         return;
     }
-    const issueScope = state.issueRootId ? `root ${state.issueRootId}` : "all roots";
+    const issueScope = state.issueRootId ? `root:${state.issueRootId}` : "all-roots";
     const roleScope = state.issueRoleTag ? state.issueRoleTag : "(all roles)";
-    const issueStatus = `${state.readyIssues.length} ready / ${state.activeIssues.length} active`;
-    if (state.sessionError || state.issueError) {
-        ctx.ui.setStatus("mu-subagents", ctx.ui.theme.fg("warning", `subagents ${state.sessions.length} · issues ${issueStatus} · degraded`));
-    }
-    else {
-        ctx.ui.setStatus("mu-subagents", ctx.ui.theme.fg("dim", `subagents ${state.sessions.length} · issues ${issueStatus} · ${issueScope}`));
-    }
+    const hasError = Boolean(state.sessionError || state.issueError);
+    const healthColor = hasError ? "warning" : "success";
+    const healthLabel = hasError ? "degraded" : "healthy";
+    const queueTotal = state.readyIssues.length + state.activeIssues.length;
+    const queueBar = queueMeter(state.activeIssues.length, Math.max(1, queueTotal), 10);
+    const refreshAge = formatRefreshAge(state.lastUpdatedMs);
+    ctx.ui.setStatus("mu-subagents", [
+        ctx.ui.theme.fg("dim", "subagents"),
+        ctx.ui.theme.fg(healthColor, healthLabel),
+        ctx.ui.theme.fg("dim", `${state.sessions.length} tmux`),
+        ctx.ui.theme.fg("dim", `${state.readyIssues.length} ready/${state.activeIssues.length} active`),
+        ctx.ui.theme.fg("muted", issueScope),
+    ].join(` ${ctx.ui.theme.fg("muted", "·")} `));
     const lines = [
-        ctx.ui.theme.fg("accent", "Subagents monitor"),
-        ctx.ui.theme.fg("dim", `  tmux prefix: ${state.prefix || "(all sessions)"}`),
-        ctx.ui.theme.fg("dim", `  issue scope: ${issueScope} · tag ${roleScope}`),
+        ctx.ui.theme.fg("accent", ctx.ui.theme.bold("Subagents board")),
+        `  ${ctx.ui.theme.fg("muted", "health:")} ${ctx.ui.theme.fg(healthColor, healthLabel)}`,
+        `  ${ctx.ui.theme.fg("muted", "scope:")} ${ctx.ui.theme.fg("dim", `${issueScope} · ${roleScope}`)}`,
+        `  ${ctx.ui.theme.fg("muted", "tmux prefix:")} ${ctx.ui.theme.fg("dim", state.prefix || "(all sessions)")}`,
+        `  ${ctx.ui.theme.fg("muted", "queues:")} ${ctx.ui.theme.fg("accent", `${state.readyIssues.length} ready`)} ${ctx.ui.theme.fg("muted", "| ")} ${ctx.ui.theme.fg("warning", `${state.activeIssues.length} active`)} ${ctx.ui.theme.fg("dim", queueBar)}`,
+        `  ${ctx.ui.theme.fg("muted", "last refresh:")} ${ctx.ui.theme.fg("dim", refreshAge)}`,
+        `  ${ctx.ui.theme.fg("dim", "────────────────────────────")}`,
+        ctx.ui.theme.fg("accent", `tmux sessions (${state.sessions.length})`),
     ];
     if (state.sessionError) {
         lines.push(ctx.ui.theme.fg("warning", `  tmux error: ${state.sessionError}`));
     }
     else if (state.sessions.length === 0) {
-        lines.push(ctx.ui.theme.fg("muted", "  tmux: (no matching sessions)"));
+        lines.push(ctx.ui.theme.fg("muted", "  (no matching sessions)"));
     }
     else {
         for (const name of state.sessions.slice(0, 8)) {
-            lines.push(`  ${ctx.ui.theme.fg("success", "●")} ${name}`);
+            lines.push(`  ${ctx.ui.theme.fg("success", "●")} ${ctx.ui.theme.fg("text", name)}`);
         }
         if (state.sessions.length > 8) {
             lines.push(ctx.ui.theme.fg("muted", `  ... +${state.sessions.length - 8} more tmux sessions`));
         }
     }
+    lines.push(`  ${ctx.ui.theme.fg("dim", "────────────────────────────")}`);
     if (state.issueError) {
-        lines.push(ctx.ui.theme.fg("warning", `  issue error: ${state.issueError}`));
+        lines.push(ctx.ui.theme.fg("warning", `issue error: ${state.issueError}`));
     }
     else {
-        lines.push(ctx.ui.theme.fg("accent", "Ready issues"));
+        lines.push(ctx.ui.theme.fg("accent", `ready queue (${state.readyIssues.length})`));
         if (state.readyIssues.length === 0) {
             lines.push(ctx.ui.theme.fg("muted", "  (no ready issues)"));
         }
         else {
             for (const issue of state.readyIssues.slice(0, 6)) {
-                lines.push(formatIssueLine(ctx, issue));
+                lines.push(formatIssueLine(ctx, issue, { marker: "→", tone: "accent" }));
             }
             if (state.readyIssues.length > 6) {
                 lines.push(ctx.ui.theme.fg("muted", `  ... +${state.readyIssues.length - 6} more ready issues`));
             }
         }
-        lines.push(ctx.ui.theme.fg("accent", "Active issues"));
+        lines.push(ctx.ui.theme.fg("accent", `active queue (${state.activeIssues.length})`));
         if (state.activeIssues.length === 0) {
             lines.push(ctx.ui.theme.fg("muted", "  (no in-progress issues)"));
         }
         else {
             for (const issue of state.activeIssues.slice(0, 6)) {
-                lines.push(formatIssueLine(ctx, issue));
+                lines.push(formatIssueLine(ctx, issue, { marker: "●", tone: "warning" }));
             }
             if (state.activeIssues.length > 6) {
                 lines.push(ctx.ui.theme.fg("muted", `  ... +${state.activeIssues.length - 6} more active issues`));
@@ -344,6 +383,30 @@ function normalizeRoleTag(raw) {
     }
     return trimmed;
 }
+function subagentsDetails(state) {
+    return {
+        enabled: state.enabled,
+        prefix: state.prefix,
+        issue_root_id: state.issueRootId,
+        issue_role_tag: state.issueRoleTag,
+        sessions: [...state.sessions],
+        ready_issue_ids: state.readyIssues.map((issue) => issue.id),
+        active_issue_ids: state.activeIssues.map((issue) => issue.id),
+        issue_error: state.issueError,
+        session_error: state.sessionError,
+        last_updated_ms: state.lastUpdatedMs,
+    };
+}
+function subagentsToolError(message, state) {
+    return {
+        content: [{ type: "text", text: message }],
+        details: {
+            ok: false,
+            error: message,
+            ...subagentsDetails(state),
+        },
+    };
+}
 export function subagentsUiExtension(pi) {
     let activeCtx = null;
     let pollTimer = null;
@@ -386,6 +449,180 @@ export function subagentsUiExtension(pi) {
     const notify = (ctx, message, level = "info") => {
         ctx.ui.notify(`${message}\n\n${subagentsUsageText()}`, level);
     };
+    const statusSummary = () => {
+        const when = state.lastUpdatedMs == null ? "never" : new Date(state.lastUpdatedMs).toLocaleTimeString();
+        const status = state.enabled ? "enabled" : "disabled";
+        const issueScope = state.issueRootId ?? "(all roots)";
+        const issueRole = state.issueRoleTag ?? "(all roles)";
+        const issueError = state.issueError ? `\nissue_error: ${state.issueError}` : "";
+        const tmuxError = state.sessionError ? `\ntmux_error: ${state.sessionError}` : "";
+        return {
+            level: state.issueError || state.sessionError ? "warning" : "info",
+            text: [
+                `Subagents monitor ${status}`,
+                `prefix: ${state.prefix || "(all sessions)"}`,
+                `issue_root: ${issueScope}`,
+                `issue_role: ${issueRole}`,
+                `sessions: ${state.sessions.length}`,
+                `ready_issues: ${state.readyIssues.length}`,
+                `active_issues: ${state.activeIssues.length}`,
+                `last refresh: ${when}`,
+            ].join("\n") + issueError + tmuxError,
+        };
+    };
+    const applySubagentsAction = async (params, ctx) => {
+        switch (params.action) {
+            case "status": {
+                const summary = statusSummary();
+                return { ok: true, message: summary.text, level: summary.level };
+            }
+            case "on":
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return { ok: true, message: "Subagents monitor enabled.", level: "info" };
+            case "off":
+                state.enabled = false;
+                stopPolling();
+                renderSubagentsUi(ctx, state);
+                return { ok: true, message: "Subagents monitor disabled.", level: "info" };
+            case "toggle":
+                state.enabled = !state.enabled;
+                if (state.enabled) {
+                    ensurePolling();
+                    await refresh(ctx);
+                }
+                else {
+                    stopPolling();
+                    renderSubagentsUi(ctx, state);
+                }
+                return { ok: true, message: `Subagents monitor ${state.enabled ? "enabled" : "disabled"}.`, level: "info" };
+            case "refresh":
+                await refresh(ctx);
+                return { ok: true, message: "Subagents monitor refreshed.", level: "info" };
+            case "set_prefix": {
+                const value = params.prefix?.trim();
+                if (!value) {
+                    return { ok: false, message: "Missing prefix value.", level: "error" };
+                }
+                state.prefix = value.toLowerCase() === "clear" ? "" : value;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return { ok: true, message: `Subagents prefix set to ${state.prefix || "(all sessions)"}.`, level: "info" };
+            }
+            case "set_root": {
+                const value = params.root_issue_id?.trim();
+                if (!value) {
+                    return { ok: false, message: "Missing root issue id.", level: "error" };
+                }
+                state.issueRootId = value.toLowerCase() === "clear" ? null : value;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return { ok: true, message: `Subagents root set to ${state.issueRootId ?? "(all roots)"}.`, level: "info" };
+            }
+            case "set_role": {
+                const value = params.role_tag?.trim();
+                if (!value) {
+                    return { ok: false, message: "Missing role/tag value.", level: "error" };
+                }
+                state.issueRoleTag = normalizeRoleTag(value);
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return { ok: true, message: `Subagents issue tag filter set to ${state.issueRoleTag ?? "(all roles)"}.`, level: "info" };
+            }
+            case "spawn": {
+                if (!state.issueRootId) {
+                    return {
+                        ok: false,
+                        message: "Set a root first (`/mu subagents root <root-id>`) before spawning.",
+                        level: "error",
+                    };
+                }
+                let spawnLimit = null;
+                if (params.count != null && params.count !== "all") {
+                    const countNum = typeof params.count === "number" ? params.count : Number.parseInt(String(params.count), 10);
+                    const parsed = Math.trunc(countNum);
+                    if (!Number.isFinite(parsed) || parsed < 1 || parsed > ISSUE_LIST_LIMIT) {
+                        return { ok: false, message: `Spawn count must be 1-${ISSUE_LIST_LIMIT} or 'all'.`, level: "error" };
+                    }
+                    spawnLimit = parsed;
+                }
+                const issueSlices = await listIssueSlices(state.issueRootId, state.issueRoleTag);
+                state.readyIssues = issueSlices.ready;
+                state.activeIssues = issueSlices.active;
+                state.issueError = issueSlices.error;
+                if (issueSlices.error) {
+                    state.enabled = true;
+                    ensurePolling();
+                    renderSubagentsUi(ctx, state);
+                    return { ok: false, message: `Cannot spawn: ${issueSlices.error}`, level: "error" };
+                }
+                const candidates = spawnLimit == null ? issueSlices.ready : issueSlices.ready.slice(0, spawnLimit);
+                if (candidates.length === 0) {
+                    state.enabled = true;
+                    ensurePolling();
+                    await refresh(ctx);
+                    return { ok: true, message: "No ready issues to spawn for current root/tag filter.", level: "info" };
+                }
+                const spawnPrefix = state.prefix.length > 0 ? state.prefix : DEFAULT_PREFIX;
+                const tmux = await listTmuxSessions(spawnPrefix);
+                if (tmux.error) {
+                    state.sessionError = tmux.error;
+                    state.enabled = true;
+                    ensurePolling();
+                    renderSubagentsUi(ctx, state);
+                    return { ok: false, message: `Cannot spawn: ${tmux.error}`, level: "error" };
+                }
+                const existingSessions = [...tmux.sessions];
+                const runId = spawnRunId();
+                const launched = [];
+                const skipped = [];
+                const failed = [];
+                for (const issue of candidates) {
+                    if (issueHasSession(existingSessions, issue.id)) {
+                        skipped.push(`${issue.id} (session exists)`);
+                        continue;
+                    }
+                    let sessionName = `${spawnPrefix}${runId}-${issue.id}`;
+                    if (existingSessions.includes(sessionName)) {
+                        let suffix = 1;
+                        while (existingSessions.includes(`${sessionName}-${suffix}`)) {
+                            suffix += 1;
+                        }
+                        sessionName = `${sessionName}-${suffix}`;
+                    }
+                    const spawned = await spawnIssueTmuxSession({
+                        cwd: ctx.cwd,
+                        sessionName,
+                        issue,
+                    });
+                    if (spawned.ok) {
+                        existingSessions.push(sessionName);
+                        launched.push(`${issue.id} -> ${sessionName}`);
+                    }
+                    else {
+                        failed.push(`${issue.id} (${spawned.error ?? "unknown error"})`);
+                    }
+                }
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                const summary = [
+                    `Spawned ${launched.length}/${candidates.length} ready issue sessions.`,
+                    launched.length > 0 ? `launched: ${launched.join(", ")}` : "launched: (none)",
+                    `skipped: ${skipped.length}`,
+                    `failed: ${failed.length}`,
+                ];
+                if (failed.length > 0) {
+                    summary.push(`failures: ${failed.join("; ")}`);
+                }
+                return { ok: true, message: summary.join("\n"), level: failed.length > 0 ? "warning" : "info" };
+            }
+        }
+    };
     pi.on("session_start", async (_event, ctx) => {
         activeCtx = ctx;
         if (state.enabled) {
@@ -414,188 +651,94 @@ export function subagentsUiExtension(pi) {
                 .trim()
                 .split(/\s+/)
                 .filter((token) => token.length > 0);
-            if (tokens.length === 0 || tokens[0] === "status") {
-                const when = state.lastUpdatedMs == null ? "never" : new Date(state.lastUpdatedMs).toLocaleTimeString();
-                const status = state.enabled ? "enabled" : "disabled";
-                const issueScope = state.issueRootId ?? "(all roots)";
-                const issueRole = state.issueRoleTag ?? "(all roles)";
-                const issueError = state.issueError ? `\nissue_error: ${state.issueError}` : "";
-                const tmuxError = state.sessionError ? `\ntmux_error: ${state.sessionError}` : "";
-                ctx.ui.notify([
-                    `Subagents monitor ${status}`,
-                    `prefix: ${state.prefix || "(all sessions)"}`,
-                    `issue_root: ${issueScope}`,
-                    `issue_role: ${issueRole}`,
-                    `sessions: ${state.sessions.length}`,
-                    `ready_issues: ${state.readyIssues.length}`,
-                    `active_issues: ${state.activeIssues.length}`,
-                    `last refresh: ${when}`,
-                ].join("\n") + issueError + tmuxError, state.issueError || state.sessionError ? "warning" : "info");
-                renderSubagentsUi(ctx, state);
-                return;
-            }
-            switch (tokens[0]) {
+            const command = tokens[0] ?? "status";
+            let params;
+            switch (command) {
+                case "status":
+                    params = { action: "status" };
+                    break;
                 case "on":
-                    state.enabled = true;
-                    ensurePolling();
-                    await refresh(ctx);
-                    ctx.ui.notify("Subagents monitor enabled.", "info");
-                    return;
+                    params = { action: "on" };
+                    break;
                 case "off":
-                    state.enabled = false;
-                    stopPolling();
-                    renderSubagentsUi(ctx, state);
-                    ctx.ui.notify("Subagents monitor disabled.", "info");
-                    return;
+                    params = { action: "off" };
+                    break;
                 case "toggle":
-                    state.enabled = !state.enabled;
-                    if (state.enabled) {
-                        ensurePolling();
-                        await refresh(ctx);
-                    }
-                    else {
-                        stopPolling();
-                        renderSubagentsUi(ctx, state);
-                    }
-                    ctx.ui.notify(`Subagents monitor ${state.enabled ? "enabled" : "disabled"}.`, "info");
-                    return;
-                case "refresh": {
-                    await refresh(ctx);
-                    ctx.ui.notify("Subagents monitor refreshed.", "info");
-                    return;
-                }
-                case "prefix": {
-                    const value = tokens.slice(1).join(" ").trim();
-                    if (!value) {
-                        notify(ctx, "Missing prefix value.", "error");
-                        return;
-                    }
-                    state.prefix = value.toLowerCase() === "clear" ? "" : value;
-                    state.enabled = true;
-                    ensurePolling();
-                    await refresh(ctx);
-                    ctx.ui.notify(`Subagents prefix set to ${state.prefix || "(all sessions)"}.`, "info");
-                    return;
-                }
-                case "root": {
-                    const value = tokens.slice(1).join(" ").trim();
-                    if (!value) {
-                        notify(ctx, "Missing root issue id.", "error");
-                        return;
-                    }
-                    state.issueRootId = value.toLowerCase() === "clear" ? null : value;
-                    state.enabled = true;
-                    ensurePolling();
-                    await refresh(ctx);
-                    ctx.ui.notify(`Subagents root set to ${state.issueRootId ?? "(all roots)"}.`, "info");
-                    return;
-                }
-                case "role": {
-                    const value = tokens.slice(1).join(" ").trim();
-                    if (!value) {
-                        notify(ctx, "Missing role/tag value.", "error");
-                        return;
-                    }
-                    state.issueRoleTag = normalizeRoleTag(value);
-                    state.enabled = true;
-                    ensurePolling();
-                    await refresh(ctx);
-                    ctx.ui.notify(`Subagents issue tag filter set to ${state.issueRoleTag ?? "(all roles)"}.`, "info");
-                    return;
-                }
-                case "spawn": {
-                    if (!state.issueRootId) {
-                        notify(ctx, "Set a root first (`/mu subagents root <root-id>`) before spawning.", "error");
-                        return;
-                    }
-                    let spawnLimit = null;
-                    const limitToken = tokens[1]?.trim();
-                    if (limitToken && limitToken.toLowerCase() !== "all") {
-                        const parsed = Number.parseInt(limitToken, 10);
-                        if (!Number.isFinite(parsed) || parsed < 1 || parsed > ISSUE_LIST_LIMIT) {
-                            notify(ctx, `Spawn count must be 1-${ISSUE_LIST_LIMIT} or 'all'.`, "error");
-                            return;
-                        }
-                        spawnLimit = parsed;
-                    }
-                    const issueSlices = await listIssueSlices(state.issueRootId, state.issueRoleTag);
-                    state.readyIssues = issueSlices.ready;
-                    state.activeIssues = issueSlices.active;
-                    state.issueError = issueSlices.error;
-                    if (issueSlices.error) {
-                        state.enabled = true;
-                        ensurePolling();
-                        renderSubagentsUi(ctx, state);
-                        notify(ctx, `Cannot spawn: ${issueSlices.error}`, "error");
-                        return;
-                    }
-                    const candidates = spawnLimit == null ? issueSlices.ready : issueSlices.ready.slice(0, spawnLimit);
-                    if (candidates.length === 0) {
-                        state.enabled = true;
-                        ensurePolling();
-                        await refresh(ctx);
-                        ctx.ui.notify("No ready issues to spawn for current root/tag filter.", "info");
-                        return;
-                    }
-                    const spawnPrefix = state.prefix.length > 0 ? state.prefix : DEFAULT_PREFIX;
-                    const tmux = await listTmuxSessions(spawnPrefix);
-                    if (tmux.error) {
-                        state.sessionError = tmux.error;
-                        state.enabled = true;
-                        ensurePolling();
-                        renderSubagentsUi(ctx, state);
-                        notify(ctx, `Cannot spawn: ${tmux.error}`, "error");
-                        return;
-                    }
-                    const existingSessions = [...tmux.sessions];
-                    const runId = spawnRunId();
-                    const launched = [];
-                    const skipped = [];
-                    const failed = [];
-                    for (const issue of candidates) {
-                        if (issueHasSession(existingSessions, issue.id)) {
-                            skipped.push(`${issue.id} (session exists)`);
-                            continue;
-                        }
-                        let sessionName = `${spawnPrefix}${runId}-${issue.id}`;
-                        if (existingSessions.includes(sessionName)) {
-                            let suffix = 1;
-                            while (existingSessions.includes(`${sessionName}-${suffix}`)) {
-                                suffix += 1;
+                    params = { action: "toggle" };
+                    break;
+                case "refresh":
+                    params = { action: "refresh" };
+                    break;
+                case "prefix":
+                    params = { action: "set_prefix", prefix: tokens.slice(1).join(" ") };
+                    break;
+                case "root":
+                    params = { action: "set_root", root_issue_id: tokens.slice(1).join(" ") };
+                    break;
+                case "role":
+                    params = { action: "set_role", role_tag: tokens.slice(1).join(" ") };
+                    break;
+                case "spawn":
+                    params = {
+                        action: "spawn",
+                        count: (() => {
+                            const token = tokens[1]?.trim();
+                            if (!token || token.toLowerCase() === "all") {
+                                return "all";
                             }
-                            sessionName = `${sessionName}-${suffix}`;
-                        }
-                        const spawned = await spawnIssueTmuxSession({
-                            cwd: ctx.cwd,
-                            sessionName,
-                            issue,
-                        });
-                        if (spawned.ok) {
-                            existingSessions.push(sessionName);
-                            launched.push(`${issue.id} -> ${sessionName}`);
-                        }
-                        else {
-                            failed.push(`${issue.id} (${spawned.error ?? "unknown error"})`);
-                        }
-                    }
-                    state.enabled = true;
-                    ensurePolling();
-                    await refresh(ctx);
-                    const summary = [
-                        `Spawned ${launched.length}/${candidates.length} ready issue sessions.`,
-                        launched.length > 0 ? `launched: ${launched.join(", ")}` : "launched: (none)",
-                        `skipped: ${skipped.length}`,
-                        `failed: ${failed.length}`,
-                    ];
-                    if (failed.length > 0) {
-                        summary.push(`failures: ${failed.join("; ")}`);
-                    }
-                    ctx.ui.notify(summary.join("\n"), failed.length > 0 ? "warning" : "info");
-                    return;
-                }
+                            const parsed = Number.parseInt(token, 10);
+                            return Number.isFinite(parsed) ? parsed : Number.NaN;
+                        })(),
+                    };
+                    break;
                 default:
-                    notify(ctx, `Unknown subagents command: ${tokens[0]}`, "error");
+                    notify(ctx, `Unknown subagents command: ${command}`, "error");
+                    return;
+            }
+            const result = await applySubagentsAction(params, ctx);
+            if (!result.ok) {
+                notify(ctx, result.message, result.level);
+                return;
+            }
+            ctx.ui.notify(result.message, result.level);
+        },
+    });
+    pi.registerTool({
+        name: "mu_subagents_hud",
+        label: "mu subagents HUD",
+        description: "Control or inspect subagents HUD state, including tmux scope, issue queue filters, and ready-queue spawning.",
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["status", "on", "off", "toggle", "refresh", "set_prefix", "set_root", "set_role", "spawn"],
+                },
+                prefix: { type: "string" },
+                root_issue_id: { type: "string" },
+                role_tag: { type: "string" },
+                count: {
+                    anyOf: [{ type: "integer", minimum: 1, maximum: ISSUE_LIST_LIMIT }, { type: "string", enum: ["all"] }],
+                },
+            },
+            required: ["action"],
+            additionalProperties: false,
+        },
+        execute: async (_toolCallId, paramsRaw, _signal, _onUpdate, ctx) => {
+            activeCtx = ctx;
+            const params = paramsRaw;
+            const result = await applySubagentsAction(params, ctx);
+            if (!result.ok) {
+                return subagentsToolError(result.message, state);
             }
+            return {
+                content: [{ type: "text", text: result.message }],
+                details: {
+                    ok: true,
+                    action: params.action,
+                    ...subagentsDetails(state),
+                },
+            };
         },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.2.86",
+  "version": "26.2.87",
   "description": "Shared agent runtime for mu assistant sessions, orchestration roles, and serve extensions.",
   "keywords": [
     "mu",
@@ -24,7 +24,7 @@
     "themes/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.2.86",
+    "@femtomc/mu-core": "26.2.87",
     "@mariozechner/pi-agent-core": "^0.53.0",
     "@mariozechner/pi-ai": "^0.53.0",
     "@mariozechner/pi-coding-agent": "^0.53.0",

package/prompts/skills/planning/SKILL.md

@@ -45,6 +45,20 @@ Optional planning HUD (interactive operator session):
 /mu plan phase investigating
 ```
 
+Tool contract (preferred when tools are available):
+
+- Tool: `mu_planning_hud`
+- Actions: `status`, `on`, `off`, `toggle`, `reset`, `phase`, `root`, `check`, `uncheck`, `toggle_step`
+- Parameters:
+  - `phase`: `investigating|drafting|reviewing|approved`
+  - `root_issue_id`: issue ID or `clear`
+  - `step`: 1-based checklist index
+
+Example tool calls:
+- Set phase: `{"action":"phase","phase":"drafting"}`
+- Bind root: `{"action":"root","root_issue_id":"<root-id>"}`
+- Update checklist: `{"action":"check","step":2}`
+
 Also inspect repo files directly (read/bash) for implementation constraints.
 
 ### B) Draft DAG in mu-issue

package/prompts/skills/subagents/SKILL.md

@@ -85,6 +85,23 @@ The widget picks up tracker decomposition by reading `mu issues ready` and
 Use `spawn` to launch tmux sessions directly from the ready queue for the
 current root/tag filter.
 
+Tool contract (preferred when tools are available):
+
+- Tool: `mu_subagents_hud`
+- Actions: `status`, `on`, `off`, `toggle`, `refresh`, `set_prefix`, `set_root`, `set_role`, `spawn`
+- Parameters:
+  - `prefix`: tmux prefix or `clear`
+  - `root_issue_id`: issue root ID or `clear`
+  - `role_tag`: issue tag filter (for example `role:worker`) or `clear`
+  - `count`: integer 1..40 or `"all"` for spawn
+
+Example tool calls:
+- Configure root + role:
+  - `{"action":"set_root","root_issue_id":"<root-id>"}`
+  - `{"action":"set_role","role_tag":"role:worker"}`
+- Refresh status: `{"action":"refresh"}`
+- Spawn from ready queue: `{"action":"spawn","count":"all"}`
+
 ## Handoffs and follow-up turns
 
 With `mu exec`, follow up by issuing another `mu exec` command in the same tmux pane