@femtomc/mu-agent 26.2.86 → 26.2.88

package/dist/extensions/subagents-ui.js

@@ -1,30 +1,62 @@
 import { registerMuSubcommand } from "./mu-command-dispatcher.js";
 const DEFAULT_PREFIX = "mu-sub-";
 const DEFAULT_ROLE_TAG = "role:worker";
+const DEFAULT_SPAWN_MODE = "worker";
 const ISSUE_LIST_LIMIT = 40;
 const MU_CLI_TIMEOUT_MS = 12_000;
+const DEFAULT_REFRESH_INTERVAL_MS = 8_000;
+const MIN_REFRESH_SECONDS = 2;
+const MAX_REFRESH_SECONDS = 120;
+const DEFAULT_STALE_AFTER_MS = 60_000;
+const MIN_STALE_SECONDS = 10;
+const MAX_STALE_SECONDS = 3_600;
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\"'\"'")}'`;
 }
 function spawnRunId(now = new Date()) {
-    return now.toISOString().replaceAll(/[-:TZ.]/g, "").slice(0, 14);
+    return now
+        .toISOString()
+        .replaceAll(/[-:TZ.]/g, "")
+        .slice(0, 14);
+}
+function sessionMatchesIssue(sessionName, issueId) {
+    return (sessionName === issueId ||
+        sessionName.endsWith(`-${issueId}`) ||
+        sessionName.includes(`-${issueId}-`) ||
+        sessionName.includes(`_${issueId}`));
 }
 function issueHasSession(sessions, issueId) {
-    return sessions.some((session) => session === issueId ||
-        session.endsWith(`-${issueId}`) ||
-        session.includes(`-${issueId}-`) ||
-        session.includes(`_${issueId}`));
+    return sessions.some((sessionName) => sessionMatchesIssue(sessionName, issueId));
 }
-function buildSubagentPrompt(issue) {
-    return [
-        `Work issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
-        `First run: mu issues claim ${issue.id}.`,
-        `Keep forum updates in topic issue:${issue.id}.`,
-        "When done, close with an explicit outcome and summary.",
-    ].join(" ");
+function buildSubagentPrompt(issue, mode) {
+    switch (mode) {
+        case "worker":
+            return [
+                `Work issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
+                `First run: mu issues claim ${issue.id}.`,
+                `Keep forum updates in topic issue:${issue.id}.`,
+                "When done, close with an explicit outcome and summary.",
+            ].join(" ");
+        case "reviewer":
+            return [
+                `Review issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
+                `First run: mu issues claim ${issue.id}.`,
+                "Validate acceptance criteria with concrete checks and evidence.",
+                "Post PASS/FAIL verdict, blockers, and required fixes in topic issue:<id>.",
+                "Close the issue with explicit outcome and review summary.",
+            ].join(" ");
+        case "researcher":
+            return [
+                `Research issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
+                `First run: mu issues claim ${issue.id}.`,
+                "Collect concrete evidence and options; call out uncertainty explicitly.",
+                `Keep findings in topic issue:${issue.id}.`,
+                "Close the issue with a concise recommendation and rationale.",
+            ].join(" ");
+    }
 }
 async function spawnIssueTmuxSession(opts) {
-    const shellCommand = `cd ${shellQuote(opts.cwd)} && mu exec ${shellQuote(buildSubagentPrompt(opts.issue))} ; rc=$?; echo __MU_DONE__:$rc`;
+    const shellCommand = `cd ${shellQuote(opts.cwd)} && mu exec ${shellQuote(buildSubagentPrompt(opts.issue, opts.mode))} ; rc=$?; echo __MU_DONE__:$rc`;
     let proc = null;
     try {
         proc = Bun.spawn({
@@ -63,6 +95,10 @@ function createDefaultState() {
         activeIssues: [],
         issueError: null,
         lastUpdatedMs: null,
+        refreshIntervalMs: DEFAULT_REFRESH_INTERVAL_MS,
+        staleAfterMs: DEFAULT_STALE_AFTER_MS,
+        spawnPaused: false,
+        spawnMode: DEFAULT_SPAWN_MODE,
     };
 }
 function truncateOneLine(input, maxLen = 68) {
@@ -164,7 +200,11 @@ async function runMuCli(args) {
         timedOut = true;
         proc?.kill();
     }, MU_CLI_TIMEOUT_MS);
-    const [exitCode, stdout, stderr] = await Promise.all([proc.exited, readableText(proc.stdout), readableText(proc.stderr)]);
+    const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        readableText(proc.stdout),
+        readableText(proc.stderr),
+    ]);
     clearTimeout(timeout);
     return {
         exitCode,
@@ -188,7 +228,11 @@ async function listTmuxSessions(prefix) {
         const message = err instanceof Error ? err.message : String(err);
         return { sessions: [], error: `failed to launch tmux: ${message}` };
     }
-    const [exitCode, stdout, stderr] = await Promise.all([proc.exited, readableText(proc.stdout), readableText(proc.stderr)]);
+    const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        readableText(proc.stdout),
+        readableText(proc.stderr),
+    ]);
     const stderrTrimmed = stderr.trim();
     if (exitCode !== 0) {
         const lowered = stderrTrimmed.toLowerCase();
@@ -251,10 +295,138 @@ 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 isRefreshStale(lastUpdatedMs, staleAfterMs) {
+    if (lastUpdatedMs == null) {
+        return false;
+    }
+    return Date.now() - lastUpdatedMs > staleAfterMs;
+}
+function computeQueueDrift(sessions, activeIssues) {
+    const activeWithoutSessionIds = activeIssues
+        .filter((issue) => !issueHasSession(sessions, issue.id))
+        .map((issue) => issue.id);
+    const orphanSessions = sessions.filter((sessionName) => !activeIssues.some((issue) => sessionMatchesIssue(sessionName, issue.id)));
+    return {
+        activeWithoutSessionIds,
+        orphanSessions,
+    };
+}
+function normalizeRoleTag(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "clear") {
+        return null;
+    }
+    if (trimmed === "worker" || trimmed === "orchestrator" || trimmed === "reviewer" || trimmed === "researcher") {
+        return `role:${trimmed}`;
+    }
+    return trimmed;
+}
+function parseSpawnMode(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === "worker" || value === "reviewer" || value === "researcher") {
+        return value;
+    }
+    return null;
+}
+function parseOnOff(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (value === "on" || value === "yes" || value === "true" || value === "1") {
+        return true;
+    }
+    if (value === "off" || value === "no" || value === "false" || value === "0") {
+        return false;
+    }
+    return null;
+}
+function parseSnapshotFormat(raw) {
+    const value = (raw ?? "compact").trim().toLowerCase();
+    return value === "multiline" ? "multiline" : "compact";
+}
+function parseSecondsBounded(secondsRaw, minSeconds, maxSeconds, field) {
+    if (typeof secondsRaw !== "number" || !Number.isFinite(secondsRaw)) {
+        return { ok: false, error: `${field} must be a number.` };
+    }
+    const rounded = Math.round(secondsRaw);
+    if (rounded < minSeconds || rounded > maxSeconds) {
+        return { ok: false, error: `${field} must be ${minSeconds}-${maxSeconds} seconds.` };
+    }
+    return { ok: true, ms: rounded * 1_000 };
+}
+function subagentsSnapshot(state, format) {
+    const issueScope = state.issueRootId ?? "(all roots)";
+    const roleScope = state.issueRoleTag ?? "(all roles)";
+    const drift = computeQueueDrift(state.sessions, state.activeIssues);
+    const refreshStale = isRefreshStale(state.lastUpdatedMs, state.staleAfterMs);
+    const staleCount = drift.activeWithoutSessionIds.length + drift.orphanSessions.length;
+    const health = state.issueError || state.sessionError || refreshStale || staleCount > 0 ? "degraded" : "healthy";
+    const refreshAge = formatRefreshAge(state.lastUpdatedMs);
+    const paused = state.spawnPaused ? "yes" : "no";
+    const refreshSeconds = Math.round(state.refreshIntervalMs / 1_000);
+    const staleAfterSeconds = Math.round(state.staleAfterMs / 1_000);
+    if (format === "multiline") {
+        return [
+            "Subagents HUD snapshot",
+            `health: ${health}`,
+            `prefix: ${state.prefix || "(all sessions)"}`,
+            `issue_root: ${issueScope}`,
+            `issue_role: ${roleScope}`,
+            `spawn_mode: ${state.spawnMode}`,
+            `spawn_paused: ${paused}`,
+            `queues: ${state.readyIssues.length} ready / ${state.activeIssues.length} active`,
+            `sessions: ${state.sessions.length}`,
+            `drift_active_without_session: ${drift.activeWithoutSessionIds.length}`,
+            `drift_orphan_sessions: ${drift.orphanSessions.length}`,
+            `refresh_age: ${refreshAge}`,
+            `refresh_stale: ${refreshStale ? "yes" : "no"}`,
+            `refresh_seconds: ${refreshSeconds}`,
+            `stale_after_seconds: ${staleAfterSeconds}`,
+        ].join("\n");
+    }
+    return [
+        "HUD(subagents)",
+        `health=${health}`,
+        `root=${issueScope}`,
+        `role=${roleScope}`,
+        `mode=${state.spawnMode}`,
+        `paused=${paused}`,
+        `ready=${state.readyIssues.length}`,
+        `active=${state.activeIssues.length}`,
+        `sessions=${state.sessions.length}`,
+        `drift=${staleCount}`,
+        `refresh=${refreshAge}`,
+    ].join(" · ");
 }
 function renderSubagentsUi(ctx, state) {
     if (!ctx.hasUI) {
@@ -265,89 +437,152 @@ 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 refreshStale = isRefreshStale(state.lastUpdatedMs, state.staleAfterMs);
+    const drift = computeQueueDrift(state.sessions, state.activeIssues);
+    const staleCount = drift.activeWithoutSessionIds.length + drift.orphanSessions.length;
+    const hasError = Boolean(state.sessionError || state.issueError || refreshStale || staleCount > 0);
+    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);
+    const pausedLabel = state.spawnPaused ? "yes" : "no";
+    const pausedColor = state.spawnPaused ? "warning" : "dim";
+    const refreshSeconds = Math.round(state.refreshIntervalMs / 1_000);
+    const staleAfterSeconds = Math.round(state.staleAfterMs / 1_000);
+    ctx.ui.setStatus("mu-subagents", [
+        ctx.ui.theme.fg("dim", "subagents"),
+        ctx.ui.theme.fg(healthColor, healthLabel),
+        ctx.ui.theme.fg("dim", `${state.spawnMode}`),
+        ctx.ui.theme.fg(pausedColor, `paused:${pausedLabel}`),
+        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", "spawn mode:")} ${ctx.ui.theme.fg("accent", state.spawnMode)}`,
+        `  ${ctx.ui.theme.fg("muted", "spawn paused:")} ${ctx.ui.theme.fg(pausedColor, pausedLabel)}`,
+        `  ${ctx.ui.theme.fg("muted", "refresh:")} ${ctx.ui.theme.fg("dim", `${refreshSeconds}s`)} ${ctx.ui.theme.fg("muted", "| stale after:")} ${ctx.ui.theme.fg("dim", `${staleAfterSeconds}s`)}`,
+        `  ${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(refreshStale ? "warning" : "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`));
             }
         }
     }
+    if (refreshStale) {
+        lines.push(ctx.ui.theme.fg("warning", `refresh warning: last successful refresh is stale (>${staleAfterSeconds}s)`));
+    }
+    if (drift.activeWithoutSessionIds.length > 0) {
+        lines.push(ctx.ui.theme.fg("warning", `drift warning: active issues without tmux sessions (${drift.activeWithoutSessionIds.length})`));
+        lines.push(ctx.ui.theme.fg("warning", `  missing sessions for: ${drift.activeWithoutSessionIds.slice(0, 8).join(", ")}${drift.activeWithoutSessionIds.length > 8 ? " ..." : ""}`));
+    }
+    if (drift.orphanSessions.length > 0) {
+        lines.push(ctx.ui.theme.fg("warning", `drift warning: tmux sessions without active issues (${drift.orphanSessions.length})`));
+        lines.push(ctx.ui.theme.fg("warning", `  orphan sessions: ${drift.orphanSessions.slice(0, 8).join(", ")}${drift.orphanSessions.length > 8 ? " ..." : ""}`));
+    }
     ctx.ui.setWidget("mu-subagents", lines, { placement: "belowEditor" });
 }
 function subagentsUsageText() {
     return [
         "Usage:",
-        "  /mu subagents on|off|toggle|status|refresh",
+        "  /mu subagents on|off|toggle|status|refresh|snapshot",
         "  /mu subagents prefix <text|clear>",
         "  /mu subagents root <issue-id|clear>",
         "  /mu subagents role <tag|clear>",
+        "  /mu subagents mode <worker|reviewer|researcher>",
+        "  /mu subagents refresh-interval <seconds>",
+        "  /mu subagents stale-after <seconds>",
+        "  /mu subagents pause <on|off>",
         "  /mu subagents spawn [N|all]",
     ].join("\n");
 }
-function normalizeRoleTag(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed || trimmed.toLowerCase() === "clear") {
-        return null;
-    }
-    if (trimmed === "worker" || trimmed === "orchestrator") {
-        return `role:${trimmed}`;
-    }
-    return trimmed;
+function subagentsDetails(state) {
+    const drift = computeQueueDrift(state.sessions, state.activeIssues);
+    return {
+        enabled: state.enabled,
+        prefix: state.prefix,
+        issue_root_id: state.issueRootId,
+        issue_role_tag: state.issueRoleTag,
+        spawn_mode: state.spawnMode,
+        spawn_paused: state.spawnPaused,
+        refresh_seconds: Math.round(state.refreshIntervalMs / 1_000),
+        stale_after_seconds: Math.round(state.staleAfterMs / 1_000),
+        sessions: [...state.sessions],
+        ready_issue_ids: state.readyIssues.map((issue) => issue.id),
+        active_issue_ids: state.activeIssues.map((issue) => issue.id),
+        active_without_session_ids: drift.activeWithoutSessionIds,
+        orphan_sessions: drift.orphanSessions,
+        refresh_stale: isRefreshStale(state.lastUpdatedMs, state.staleAfterMs),
+        issue_error: state.issueError,
+        session_error: state.sessionError,
+        last_updated_ms: state.lastUpdatedMs,
+        snapshot_compact: subagentsSnapshot(state, "compact"),
+        snapshot_multiline: subagentsSnapshot(state, "multiline"),
+    };
+}
+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;
-    let state = createDefaultState();
+    const state = createDefaultState();
     const refresh = async (ctx) => {
         if (!state.enabled) {
             renderSubagentsUi(ctx, state);
@@ -381,11 +616,368 @@ export function subagentsUiExtension(pi) {
                 return;
             }
             void refresh(activeCtx);
-        }, 8_000);
+        }, state.refreshIntervalMs);
+    };
+    const restartPolling = () => {
+        if (!state.enabled) {
+            return;
+        }
+        stopPolling();
+        ensurePolling();
     };
     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 drift = computeQueueDrift(state.sessions, state.activeIssues);
+        const refreshStale = isRefreshStale(state.lastUpdatedMs, state.staleAfterMs);
+        const issueError = state.issueError ? `\nissue_error: ${state.issueError}` : "";
+        const tmuxError = state.sessionError ? `\ntmux_error: ${state.sessionError}` : "";
+        const driftInfo = drift.activeWithoutSessionIds.length > 0 || drift.orphanSessions.length > 0
+            ? `\ndrift_active_without_session: ${drift.activeWithoutSessionIds.length}\ndrift_orphan_sessions: ${drift.orphanSessions.length}`
+            : "";
+        const staleInfo = refreshStale ? "\nrefresh_stale: yes" : "\nrefresh_stale: no";
+        return {
+            level: state.issueError ||
+                state.sessionError ||
+                refreshStale ||
+                drift.activeWithoutSessionIds.length > 0 ||
+                drift.orphanSessions.length > 0
+                ? "warning"
+                : "info",
+            text: [
+                `Subagents monitor ${status}`,
+                `prefix: ${state.prefix || "(all sessions)"}`,
+                `issue_root: ${issueScope}`,
+                `issue_role: ${issueRole}`,
+                `spawn_mode: ${state.spawnMode}`,
+                `spawn_paused: ${state.spawnPaused ? "yes" : "no"}`,
+                `refresh_seconds: ${Math.round(state.refreshIntervalMs / 1_000)}`,
+                `stale_after_seconds: ${Math.round(state.staleAfterMs / 1_000)}`,
+                `sessions: ${state.sessions.length}`,
+                `ready_issues: ${state.readyIssues.length}`,
+                `active_issues: ${state.activeIssues.length}`,
+                `last refresh: ${when}`,
+            ].join("\n") +
+                issueError +
+                tmuxError +
+                driftInfo +
+                staleInfo,
+        };
+    };
+    const applySubagentsAction = async (params, ctx) => {
+        switch (params.action) {
+            case "status": {
+                const summary = statusSummary();
+                return { ok: true, message: summary.text, level: summary.level };
+            }
+            case "snapshot": {
+                const format = parseSnapshotFormat(params.snapshot_format);
+                return { ok: true, message: subagentsSnapshot(state, format), level: "info" };
+            }
+            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 "set_mode": {
+                const modeRaw = params.spawn_mode?.trim() ?? "";
+                const mode = parseSpawnMode(modeRaw);
+                if (!mode) {
+                    return { ok: false, message: "Invalid spawn mode.", level: "error" };
+                }
+                state.spawnMode = mode;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return { ok: true, message: `Subagents spawn mode set to ${mode}.`, level: "info" };
+            }
+            case "set_refresh_interval": {
+                const parsed = parseSecondsBounded(params.refresh_seconds, MIN_REFRESH_SECONDS, MAX_REFRESH_SECONDS, "refresh_seconds");
+                if (!parsed.ok) {
+                    return { ok: false, message: parsed.error, level: "error" };
+                }
+                state.refreshIntervalMs = parsed.ms;
+                state.enabled = true;
+                restartPolling();
+                await refresh(ctx);
+                return {
+                    ok: true,
+                    message: `Subagents refresh interval set to ${Math.round(state.refreshIntervalMs / 1_000)}s.`,
+                    level: "info",
+                };
+            }
+            case "set_stale_after": {
+                const parsed = parseSecondsBounded(params.stale_after_seconds, MIN_STALE_SECONDS, MAX_STALE_SECONDS, "stale_after_seconds");
+                if (!parsed.ok) {
+                    return { ok: false, message: parsed.error, level: "error" };
+                }
+                state.staleAfterMs = parsed.ms;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return {
+                    ok: true,
+                    message: `Subagents stale threshold set to ${Math.round(state.staleAfterMs / 1_000)}s.`,
+                    level: "info",
+                };
+            }
+            case "set_spawn_paused": {
+                if (typeof params.spawn_paused !== "boolean") {
+                    return { ok: false, message: "spawn_paused must be a boolean.", level: "error" };
+                }
+                state.spawnPaused = params.spawn_paused;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return {
+                    ok: true,
+                    message: `Subagents spawn pause set to ${state.spawnPaused ? "on" : "off"}.`,
+                    level: "info",
+                };
+            }
+            case "update": {
+                const changed = [];
+                let refreshIntervalChanged = false;
+                if (params.prefix !== undefined) {
+                    if (typeof params.prefix !== "string") {
+                        return { ok: false, message: "prefix must be a string.", level: "error" };
+                    }
+                    const trimmed = params.prefix.trim();
+                    if (trimmed.length === 0) {
+                        return { ok: false, message: "prefix must not be empty.", level: "error" };
+                    }
+                    state.prefix = trimmed.toLowerCase() === "clear" ? "" : trimmed;
+                    changed.push("prefix");
+                }
+                if (params.root_issue_id !== undefined) {
+                    if (typeof params.root_issue_id !== "string") {
+                        return { ok: false, message: "root_issue_id must be a string.", level: "error" };
+                    }
+                    const trimmed = params.root_issue_id.trim();
+                    if (trimmed.length === 0) {
+                        return { ok: false, message: "root_issue_id must not be empty.", level: "error" };
+                    }
+                    state.issueRootId = trimmed.toLowerCase() === "clear" ? null : trimmed;
+                    changed.push("root_issue_id");
+                }
+                if (params.role_tag !== undefined) {
+                    if (typeof params.role_tag !== "string") {
+                        return { ok: false, message: "role_tag must be a string.", level: "error" };
+                    }
+                    const trimmed = params.role_tag.trim();
+                    if (trimmed.length === 0) {
+                        return { ok: false, message: "role_tag must not be empty.", level: "error" };
+                    }
+                    state.issueRoleTag = normalizeRoleTag(trimmed);
+                    changed.push("role_tag");
+                }
+                if (params.spawn_mode !== undefined) {
+                    if (typeof params.spawn_mode !== "string") {
+                        return { ok: false, message: "spawn_mode must be a string.", level: "error" };
+                    }
+                    const mode = parseSpawnMode(params.spawn_mode);
+                    if (!mode) {
+                        return { ok: false, message: "Invalid spawn mode.", level: "error" };
+                    }
+                    state.spawnMode = mode;
+                    changed.push("spawn_mode");
+                }
+                if (params.refresh_seconds !== undefined) {
+                    const parsed = parseSecondsBounded(params.refresh_seconds, MIN_REFRESH_SECONDS, MAX_REFRESH_SECONDS, "refresh_seconds");
+                    if (!parsed.ok) {
+                        return { ok: false, message: parsed.error, level: "error" };
+                    }
+                    state.refreshIntervalMs = parsed.ms;
+                    refreshIntervalChanged = true;
+                    changed.push("refresh_seconds");
+                }
+                if (params.stale_after_seconds !== undefined) {
+                    const parsed = parseSecondsBounded(params.stale_after_seconds, MIN_STALE_SECONDS, MAX_STALE_SECONDS, "stale_after_seconds");
+                    if (!parsed.ok) {
+                        return { ok: false, message: parsed.error, level: "error" };
+                    }
+                    state.staleAfterMs = parsed.ms;
+                    changed.push("stale_after_seconds");
+                }
+                if (params.spawn_paused !== undefined) {
+                    if (typeof params.spawn_paused !== "boolean") {
+                        return { ok: false, message: "spawn_paused must be a boolean.", level: "error" };
+                    }
+                    state.spawnPaused = params.spawn_paused;
+                    changed.push("spawn_paused");
+                }
+                if (changed.length === 0) {
+                    return { ok: false, message: "No update fields provided.", level: "error" };
+                }
+                state.enabled = true;
+                if (refreshIntervalChanged) {
+                    restartPolling();
+                }
+                else {
+                    ensurePolling();
+                }
+                await refresh(ctx);
+                return { ok: true, message: `Subagents monitor updated (${changed.join(", ")}).`, level: "info" };
+            }
+            case "spawn": {
+                if (state.spawnPaused) {
+                    return {
+                        ok: false,
+                        message: "Spawn is paused. Use set_spawn_paused=false before spawning.",
+                        level: "error",
+                    };
+                }
+                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,
+                        mode: state.spawnMode,
+                    });
+                    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 (mode=${state.spawnMode}).`,
+                    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) {
@@ -407,195 +999,142 @@ export function subagentsUiExtension(pi) {
     registerMuSubcommand(pi, {
         subcommand: "subagents",
         summary: "Monitor tmux subagent sessions + issue queue, and spawn ready issue sessions",
-        usage: "/mu subagents on|off|toggle|status|refresh|prefix|root|role|spawn",
+        usage: "/mu subagents on|off|toggle|status|refresh|snapshot|prefix|root|role|mode|refresh-interval|stale-after|pause|spawn",
         handler: async (args, ctx) => {
             activeCtx = ctx;
             const tokens = args
                 .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 "snapshot":
+                    params = { action: "snapshot", snapshot_format: tokens[1] };
+                    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;
+                    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 "mode":
+                    params = { action: "set_mode", spawn_mode: tokens[1] };
+                    break;
+                case "refresh-interval":
+                    params = { action: "set_refresh_interval", refresh_seconds: Number.parseFloat(tokens[1] ?? "") };
+                    break;
+                case "stale-after":
+                    params = { action: "set_stale_after", stale_after_seconds: Number.parseFloat(tokens[1] ?? "") };
+                    break;
+                case "pause": {
+                    const parsed = parseOnOff(tokens[1]);
+                    params = { action: "set_spawn_paused", spawn_paused: parsed ?? undefined };
+                    break;
                 }
-                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;
+                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, queue filters, spawn profile, and health policies.",
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: [
+                        "status",
+                        "snapshot",
+                        "on",
+                        "off",
+                        "toggle",
+                        "refresh",
+                        "set_prefix",
+                        "set_root",
+                        "set_role",
+                        "set_mode",
+                        "set_refresh_interval",
+                        "set_stale_after",
+                        "set_spawn_paused",
+                        "update",
+                        "spawn",
+                    ],
+                },
+                prefix: { type: "string" },
+                root_issue_id: { type: "string" },
+                role_tag: { type: "string" },
+                spawn_mode: { type: "string", enum: ["worker", "reviewer", "researcher"] },
+                refresh_seconds: { type: "number", minimum: MIN_REFRESH_SECONDS, maximum: MAX_REFRESH_SECONDS },
+                stale_after_seconds: { type: "number", minimum: MIN_STALE_SECONDS, maximum: MAX_STALE_SECONDS },
+                spawn_paused: { type: "boolean" },
+                snapshot_format: { type: "string", enum: ["compact", "multiline"] },
+                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),
+                },
+            };
         },
     });
 }