@heyhuynhgiabuu/pi-task 0.1.6 → 0.2.0

package/dist/index.js

@@ -1,470 +1,74 @@
 /**
  * Task Tool — Delegate complex work to specialist agents.
  *
- * Spawns pi CLI in a tmux split pane (so you can watch it live) and
- * detects completion via RESULT.md polling. On completion, tool call
- * count and duration are reported as a notification.
+ * Spawns pi CLI in a tmux split pane (foreground) or background.
+ * Completion is detected from the subagent's final assistant message
+ * in the persistent session JSONL (stopReason gating). The final message
+ * is the authoritative result; no RESULT.md is used.
  *
  * Three agent sources:
  *   - .pi/agents/*.md        project-local agents
  *   - ~/.pi/agent/agents/*.md user-global agents (fallback)
  *
  * P0: Persistent task registry (appendEntry + JSON), --session resume,
- *     sendMessage completion notification.
- * P1: Foreground mode (background:false, inline subprocess), pane death
- *     detection, 30-minute timeout.
+ *     sendMessage completion notification, Ctrl+O expand/collapse.
+ * P1: Foreground mode (background:false), pane death detection, timeout.
  */
-import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Type } from "@sinclair/typebox";
-import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { buildAgentToolSelection } from "./agent-tools.js";
-import { normalizeConversationId, parseMetadataFromBody, readTaskBlock, readTaskSessionsRegistry, renderConversationSessions, writeConversationArtifacts, writeTaskSessionsRegistry, } from "./conversation.js";
-import { TASK_BACKGROUND_DEFAULT, TASK_RESULT_XML_INSTRUCTIONS, TASK_TOOL_DESCRIPTION, buildTmuxSplitWindowArgs, chooseTmuxSplitDirection, formatBackgroundReceipt, buildPiArgs, parseResultXml, formatMs, shellQuote, discoverAgents, formatAgentList, countToolUses, readRecentToolCalls, } from "./helpers.js";
+import { BACKGROUND_CHECK_MS, COUNT_POLL_MS, MAX_POLL_ERRORS, TASK_TIMEOUT_MS, } from "./constants.js";
+import { findJsonlSessionByName, normalizeConversationId, parseMetadataFromBody, readTaskBlock, findTaskSessionHistory, readRegistry, readTaskSessionsRegistry, renderConversationSessions, upsertTaskSessionHistory, writeConversationArtifacts, writeRegistry, writeTaskSessionsRegistry, } from "./conversation.js";
+import { TASK_BACKGROUND_DEFAULT, TASK_TOOL_DESCRIPTION, buildPiArgs, countToolUses, discoverAgents, formatAgentList, formatBackgroundReceipt, parseResultXml, shellQuote, } from "./helpers.js";
+import { completeTask, createTaskWidgetController, restoreActiveBackgroundTasks, startBackgroundPolling, startToolStatsPolling, } from "./lifecycle/index.js";
 import { runSdkSubagent } from "./subagent/runSdk.js";
 import { checkTaskCompletion, waitForTaskCompletion as waitForSessionTaskCompletion, } from "./subagent/waitCompletion.js";
-import { renderTaskWidget, TASK_WIDGET_RENDER_MS, } from "./task-widget.js";
+import { hasTmux, killAgentPane, paneExists, setPaneRemainOnExit, splitWindowPane, wrapWithPaneExitWatcher, } from "./subagent/tmux.js";
+import { buildTaskPrompt, createTaskCompleteRenderer, renderCall, renderResult, taskParametersSchema, } from "./tool/index.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const BUNDLED_AGENT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "agents");
-const BACKGROUND_CHECK_MS = 10_000; // poll every 10 sec
-const COUNT_POLL_MS = 3_000; // update toolcall counts every 3 sec
-const TASK_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutes
 // Conversation helpers live in ./conversation.js.
-function readRegistry(piDir) {
-    const path = join(piDir, "task-registry.json");
-    try {
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch {
-        return [];
-    }
-}
-function writeRegistry(piDir, entries) {
-    const path = join(piDir, "task-registry.json");
-    writeFileSync(path, JSON.stringify(entries, null, 2), "utf-8");
-}
-function readTaskSessionHistory(piDir) {
-    const path = join(piDir, "task-session-history.json");
-    try {
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch {
-        return [];
-    }
-}
-function writeTaskSessionHistory(piDir, entries) {
-    const path = join(piDir, "task-session-history.json");
-    writeFileSync(path, JSON.stringify(entries, null, 2), "utf-8");
-}
-function upsertTaskSessionHistory(piDir, entry) {
-    const entries = readTaskSessionHistory(piDir);
-    const index = entries.findIndex((existing) => existing.id === entry.id);
-    if (index >= 0) {
-        entries[index] = { ...entries[index], ...entry };
-    }
-    else {
-        entries.push(entry);
-    }
-    writeTaskSessionHistory(piDir, entries);
-}
-function findTaskSessionHistory(piDir, idOrSessionName) {
-    return readTaskSessionHistory(piDir).find((entry) => entry.id === idOrSessionName || entry.sessionName === idOrSessionName);
-}
-function findJsonlSessionByName(piDir, sessionName, agentType) {
-    const artifactsDir = join(piDir, "artifacts");
-    const sessionDir = join(artifactsDir, "sessions");
-    try {
-        if (!existsSync(sessionDir))
-            return undefined;
-        const files = readdirSync(sessionDir)
-            .filter((file) => file.endsWith(".jsonl"))
-            .sort()
-            .reverse();
-        for (const file of files) {
-            const content = readFileSync(join(sessionDir, file), "utf-8");
-            let startedAt = Date.now();
-            for (const rawLine of content.split("\n")) {
-                const line = rawLine.trim();
-                if (!line)
-                    continue;
-                try {
-                    const entry = JSON.parse(line);
-                    if (entry.type === "session" && entry.timestamp) {
-                        const parsed = Date.parse(entry.timestamp);
-                        if (Number.isFinite(parsed))
-                            startedAt = parsed;
-                    }
-                    if (entry.type === "session_info") {
-                        const name = entry.name ?? entry.session_info?.name;
-                        if (name === sessionName) {
-                            return {
-                                id: sessionName,
-                                agentType,
-                                description: `Resumed session ${sessionName}`,
-                                sessionName,
-                                sessionRef: join(sessionDir, file),
-                                startedAt,
-                                piDir,
-                                dir: artifactsDir,
-                                status: "done",
-                                background: false,
-                            };
-                        }
-                        break;
-                    }
-                }
-                catch {
-                    // Skip malformed lines
-                }
-            }
-        }
-    }
-    catch {
-        return undefined;
-    }
-    return undefined;
-}
-// ─── Tmux Helpers ────────────────────────────────────────────────────────────
-function tmuxCmd(args) {
-    return execFileSync("tmux", args, {
-        encoding: "utf-8",
-        stdio: ["ignore", "pipe", "pipe"],
-    }).trim();
-}
-function hasTmux() {
-    try {
-        execFileSync("tmux", ["-V"], { stdio: "ignore" });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function paneExists(paneId) {
-    try {
-        return tmuxCmd(["list-panes", "-a", "-F", "#{pane_id}"])
-            .split("\n")
-            .includes(paneId);
-    }
-    catch {
-        return false;
-    }
-}
-function getCurrentPaneId() {
-    try {
-        return tmuxCmd(["display-message", "-p", "#{pane_id}"]);
-    }
-    catch {
-        return null;
-    }
-}
-function getCurrentPaneSize(targetPane) {
-    try {
-        const args = ["display-message", "-p", "#{pane_width} #{pane_height}"];
-        if (targetPane)
-            args.splice(1, 0, "-t", targetPane);
-        const raw = tmuxCmd(args);
-        const [widthRaw, heightRaw] = raw.trim().split(/\s+/, 2);
-        const width = Number(widthRaw);
-        const height = Number(heightRaw);
-        if (!Number.isFinite(width) || !Number.isFinite(height))
-            return null;
-        return { width, height };
-    }
-    catch {
-        return null;
-    }
-}
-function splitWindowPane(cwd, command) {
-    const originalPane = getCurrentPaneId();
-    const paneSize = getCurrentPaneSize(originalPane);
-    const direction = chooseTmuxSplitDirection(paneSize?.width ?? 0, paneSize?.height ?? 0);
-    const paneId = tmuxCmd(buildTmuxSplitWindowArgs(cwd, command, direction, originalPane));
-    return { paneId, originalPane };
-}
-function killAgentPane(paneId, originalPane) {
-    if (paneId) {
-        try {
-            if (paneExists(paneId))
-                tmuxCmd(["kill-pane", "-t", paneId]);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    if (originalPane) {
-        try {
-            tmuxCmd(["select-pane", "-t", originalPane]);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
-// ─── Process a completed task (sendMessage + registry cleanup) ──────────────
-function completeTask(pi, id, task, content, phase, piDir) {
-    // Kill the tmux pane if still alive
-    killAgentPane(task.paneId, task.originalPane);
-    const parsed = parseResultXml(content);
-    const durationMs = Date.now() - task.startedAt;
-    const completedSessionRef = findJsonlSessionByName(piDir, task.sessionName, task.agentType)?.sessionRef;
-    upsertTaskSessionHistory(piDir, {
-        id,
-        agentType: task.agentType,
-        description: task.description,
-        sessionName: task.sessionName,
-        startedAt: task.startedAt,
-        paneId: task.paneId,
-        piDir,
-        dir: task.dir,
-        conversationId: task.conversationId,
-        sessionRef: completedSessionRef,
-        status: phase,
-        completedAt: Date.now(),
-        background: true,
-    });
-    // Send completion notification
-    pi.sendMessage({
-        customType: "task-complete",
-        content: `Background task ${id} (${task.agentType}) ${phase}.\n\nResult:\n${content}`,
-        display: true,
-        details: {
-            task_id: id,
-            agent_type: task.agentType,
-            description: task.description,
-            phase,
-            status: phase,
-            result: content,
-            summary: parsed.summary,
-            findings: parsed.findings,
-            confidence: parsed.confidence,
-            duration_ms: durationMs,
-            tool_uses: task.toolUses,
-            turn_count: task.turns,
-        },
-    }, {
-        triggerTurn: true,
-        deliverAs: "followUp",
-    });
-    // Remove from registry
-    const entries = readRegistry(piDir).filter((e) => e.id !== id);
-    writeRegistry(piDir, entries);
-}
 // ─── Extension Entry Point ──────────────────────────────────────────────────
 export default function (pi) {
     // Prevent recursive loading
     if (process.env.PI_TASK_TOOL_DISABLED === "1")
         return;
     // ── Background task tracker ────────────────────────────────────────────
+    const { piDir } = discoverAgents(process.cwd(), BUNDLED_AGENT_DIR);
     const backgroundTasks = new Map();
     const foregroundTasks = new Map();
-    let widgetCtx = null;
+    const taskWidget = createTaskWidgetController(foregroundTasks, backgroundTasks);
+    const { ensureTaskWidget, clearTaskWidgetIfIdle } = taskWidget;
     // ── Restore active tasks from registry on load ──────────────────────────
-    const { piDir } = discoverAgents(process.cwd());
-    const registry = readRegistry(piDir);
-    const staleIds = [];
-    for (const entry of registry) {
-        // Only restore if artifact dir still exists
-        if (!existsSync(entry.dir)) {
-            staleIds.push(entry.id);
-            continue;
-        }
-        // Check if tmux pane is still alive
-        const paneAlive = entry.paneId ? paneExists(entry.paneId) : false;
-        if (!paneAlive) {
-            staleIds.push(entry.id);
-            continue;
-        }
-        const bgtask = {
-            dir: entry.dir,
-            agentType: entry.agentType,
-            sessionName: entry.sessionName,
-            paneId: entry.paneId,
-            originalPane: null,
-            description: entry.description,
-            startedAt: entry.startedAt,
-            toolUses: 0,
-            turns: 0,
-            conversationId: entry.conversationId,
-            recentCalls: [],
-        };
-        backgroundTasks.set(entry.id, bgtask);
-    }
-    if (staleIds.length) {
-        writeRegistry(piDir, registry.filter((e) => !staleIds.includes(e.id)));
-    }
+    restoreActiveBackgroundTasks(piDir, backgroundTasks);
     // ── Widget / timer setup ───────────────────────────────────────────────
-    let widgetTimer = null;
-    function stopWidget() {
-        if (widgetTimer) {
-            clearInterval(widgetTimer);
-            widgetTimer = null;
-        }
-    }
-    const countInterval = setInterval(() => {
-        for (const task of [
-            ...foregroundTasks.values(),
-            ...backgroundTasks.values(),
-        ]) {
-            const sessionDir = join(task.dir, "sessions");
-            // Single walk: counts + recent tool-call history with status
-            const { toolUses, turns, recent } = readRecentToolCalls(sessionDir, 12, task.sessionName);
-            task.toolUses = toolUses;
-            task.turns = turns;
-            task.recentCalls = recent;
-        }
-    }, COUNT_POLL_MS);
-    // Theme reference is captured at setWidget time so renderWidget can use it.
-    let widgetTheme = null;
-    function renderWidget(width) {
-        // Defensive: never let a render exception kill the TUI. If anything
-        // throws (theme lookup miss, malformed session JSONL, etc.), fall
-        // back to a minimal single-line summary so the TUI stays alive.
-        try {
-            return renderTaskWidget({
-                foregroundTasks: foregroundTasks.entries(),
-                backgroundTasks: backgroundTasks.entries(),
-                foregroundCount: foregroundTasks.size,
-                backgroundCount: backgroundTasks.size,
-                width,
-                theme: widgetTheme,
-            });
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            const active = [
-                ...Array.from(foregroundTasks.entries()),
-                ...Array.from(backgroundTasks.entries()),
-            ];
-            if (active.length === 0)
-                return [];
-            const [, task] = active[0];
-            return [
-                truncateToWidth(`${task.agentType}  \u2022 ${formatMs(Date.now() - task.startedAt)}  (render error: ${msg})`, Math.min(width, 120)),
-            ];
-        }
-    }
-    function ensureTaskWidget(targetCtx) {
-        if (widgetCtx || targetCtx.mode !== "tui")
-            return;
-        widgetCtx = targetCtx;
-        targetCtx.ui.setWidget("task", (tui, theme) => {
-            widgetTheme = theme ?? null;
-            widgetTimer = setInterval(() => tui.requestRender(), TASK_WIDGET_RENDER_MS);
-            // Don't keep the process alive just for the widget refresh.
-            widgetTimer.unref?.();
-            return {
-                render: (width) => renderWidget(width),
-                invalidate: () => { },
-                dispose: () => {
-                    widgetTheme = null;
-                    stopWidget();
-                },
-            };
-        });
-    }
-    function clearTaskWidgetIfIdle() {
-        if (foregroundTasks.size > 0 || backgroundTasks.size > 0)
-            return;
-        stopWidget();
-        if (widgetCtx) {
-            widgetCtx.ui.setWidget("task", undefined);
-            widgetCtx = null;
-        }
-    }
+    const countInterval = startToolStatsPolling(foregroundTasks, backgroundTasks, COUNT_POLL_MS);
     // ── Polling loop (background task completion, pane death, timeout) ──────
-    const checkInterval = setInterval(async () => {
-        if (backgroundTasks.size === 0) {
-            clearTaskWidgetIfIdle();
-            return;
-        }
-        const now = Date.now();
-        const ids = Array.from(backgroundTasks.keys());
-        for (const id of ids) {
-            const task = backgroundTasks.get(id);
-            if (!task)
-                continue;
-            // ── Check timeout ────────────────────────────────────────────
-            if (now - task.startedAt > TASK_TIMEOUT_MS) {
-                killAgentPane(task.paneId, task.originalPane);
-                backgroundTasks.delete(id);
-                clearTaskWidgetIfIdle();
-                completeTask(pi, id, task, "Task timed out after 30 minutes", "timeout", piDir);
-                continue;
-            }
-            const snapshot = await checkTaskCompletion({
-                resultPath: join(task.dir, "RESULT.md"),
-                sessionDir: join(task.dir, "sessions"),
-                sessionName: task.sessionName,
-                paneId: task.paneId,
-                sinceMs: task.startedAt,
-            });
-            if (snapshot.status === "running") {
-                continue;
-            }
-            const phase = snapshot.status === "completed" ? "done" : "failed";
-            backgroundTasks.delete(id);
-            clearTaskWidgetIfIdle();
-            completeTask(pi, id, task, snapshot.content, phase, piDir);
-        }
+    const checkInterval = startBackgroundPolling({
+        backgroundTasks,
+        checkTaskCompletion,
+        killAgentPane: (paneId, originalPane) => {
+            if (paneId)
+                killAgentPane(paneId, originalPane);
+        },
+        clearTaskWidgetIfIdle,
+        completeTask,
+        TASK_TIMEOUT_MS,
+        MAX_POLL_ERRORS,
+        piDir,
+        pi,
     }, BACKGROUND_CHECK_MS);
     // ── Cleanup on shutdown ────────────────────────────────────────────────
     pi.on("session_shutdown", () => {
         clearInterval(checkInterval);
         clearInterval(countInterval);
-        stopWidget();
-        if (widgetCtx) {
-            widgetCtx.ui.setWidget("task", undefined);
-            widgetCtx = null;
-        }
+        taskWidget.dispose();
     });
     // ── Custom notification renderer ───────────────────────────────────────
-    pi.registerMessageRenderer?.("task-complete", (message, { expanded }, theme) => {
-        const d = message.details;
-        if (!d)
-            return undefined;
-        const agentType = d.agent_type || "";
-        const desc = d.description || "";
-        const summary = d.summary || "";
-        const findings = d.findings || "";
-        const confidence = d.confidence || "";
-        const durationMs = d.duration_ms || 0;
-        const toolUses = d.tool_uses || 0;
-        let line = " " + theme.fg("accent", agentType);
-        if (desc)
-            line += theme.fg("dim", ` - ${desc}`);
-        const useStr = toolUses > 0 ? `${toolUses} toolcalls` : "";
-        const durStr = durationMs >= 1000 ? formatMs(durationMs) : "";
-        const statsParts = [useStr, durStr].filter(Boolean);
-        const statsText = statsParts.join(" • ");
-        const confStr = confidence ? confidence.toUpperCase() : "";
-        const confColor = confidence === "high"
-            ? "success"
-            : confidence === "low"
-                ? "error"
-                : "accent";
-        if (statsText || confStr) {
-            line += "\n ";
-            if (confStr)
-                line += theme.fg(confColor, `[${confStr}]`);
-            if (statsText)
-                line += (confStr ? " " : "") + theme.fg("dim", statsText);
-        }
-        if (expanded) {
-            if (summary)
-                line += "\n " + theme.fg("muted", summary);
-            if (findings)
-                line += "\n " + theme.fg("dim", findings);
-        }
-        if (!line.trim())
-            return undefined;
-        const subtleBg = (text) => `\x1b[48;2;30;28;44m${text}\x1b[0m`;
-        return new Text(line, 0, 1, subtleBg);
-    });
+    pi.registerMessageRenderer?.("task-complete", createTaskCompleteRenderer());
     // ── Tool Registration ──────────────────────────────────────────────────
     pi.registerTool({
         name: "task",
@@ -481,27 +85,7 @@ export default function (pi) {
             "After delegated work completes, read changed files, review diff, verify scope, and run relevant checks",
             "Send the user a concise summary of the result since the agent's output is not user-visible",
         ],
-        parameters: Type.Object({
-            agent_type: Type.String({
-                description: "The type of specialist agent to use for this task",
-            }),
-            prompt: Type.String({
-                description: "The complete task for the agent to perform. Be detailed and self-contained.",
-            }),
-            description: Type.String({
-                description: "A short (3-5 word) summary of the task",
-            }),
-            task_id: Type.Optional(Type.String({
-                description: "Resume an existing background task by id instead of starting a new task.",
-            })),
-            conversation_id: Type.Optional(Type.String({
-                description: "Durable specialist conversation id. Reuses .pi/artifacts/task-<id>/sessions when called again.",
-            })),
-            background: Type.Optional(Type.Boolean({
-                description: "Run in background (async). You will be notified when it completes. DO NOT sleep, poll, ask the task for status, or duplicate its work while it runs in background.",
-                default: true,
-            })),
-        }),
+        parameters: taskParametersSchema(),
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             const { agents, piDir } = discoverAgents(ctx.cwd, BUNDLED_AGENT_DIR);
             const parentToolNames = pi
@@ -552,30 +136,12 @@ export default function (pi) {
             }
             let id;
             let sessionName;
-            let resultPath;
             let resume = false;
             let resumeSessionRef;
             const artifactsDir = join(piDir, "artifacts");
             if (registeredTaskId) {
                 id = registeredTaskId;
                 sessionName = conversationId ?? `task-${id}`;
-                resultPath = join(artifactsDir, `RESULT-${id}.md`);
-                if (!existsSync(resultPath)) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `conversation_id "${conversationId}" has no prior result file at ${resultPath}. Cannot resume.`,
-                            },
-                        ],
-                        details: {
-                            phase: "failed",
-                            error: "Conversation result missing",
-                            conversation_id: conversationId,
-                        },
-                        isError: true,
-                    };
-                }
                 const block = readTaskBlock(piDir, id);
                 const previousMetadata = parseMetadataFromBody(block?.body);
                 const metadataAgent = previousMetadata?.agent_type;
@@ -686,7 +252,6 @@ export default function (pi) {
                 // flat in artifactsDir, no per-task subdir.
                 id = entry.id;
                 sessionName = entry.sessionName;
-                resultPath = join(artifactsDir, `RESULT-${id}.md`);
                 resume = true;
                 resumeSessionRef = entry.sessionRef;
                 // If background and pane still alive, reattach to tracker
@@ -743,7 +308,6 @@ export default function (pi) {
             else {
                 id = `${Date.now().toString(36)}-${randomUUID().slice(0, 4)}`;
                 sessionName = conversationId ?? `task-${id}`;
-                resultPath = join(artifactsDir, `RESULT-${id}.md`);
             }
             if (conversationId && !hasTmux()) {
                 return {
@@ -774,32 +338,24 @@ export default function (pi) {
             const isBackground = params.background ?? TASK_BACKGROUND_DEFAULT;
             // default true
             // ── Build the prompt (instructions are inlined; no CONTEXT.md file) ─
-            const promptContent = [
-                `# Task: ${descText}`,
-                "",
-                `## Agent`,
-                `${agent.name} (${agent.source})`,
-                "",
-                `## Instructions`,
-                params.prompt,
-                "",
-                `## Working Directory`,
-                ctx.cwd,
-                "",
-                `## Output`,
-                "Your final assistant message is the result. End with a clear summary of what you did and any findings. No file write is required.",
-                "",
-                "Use this format for the summary:",
-                "",
-                "```",
-                TASK_RESULT_XML_INSTRUCTIONS,
-                "```",
-            ].join("\n");
-            const sessionDir = join(artifactsDir, "sessions");
+            const promptContent = buildTaskPrompt({
+                description: descText,
+                agentName: agent.name,
+                agentSource: agent.source,
+                prompt: params.prompt,
+                cwd: ctx.cwd,
+            });
+            const sessionDir = join(artifactsDir, "sessions", id);
             await mkdir(sessionDir, { recursive: true });
             // ─── Build and run the sub-agent pi process ──────────────────────────
             const piArgs = buildPiArgs(agent, sessionName, sessionDir, promptContent, resume, parentToolNames, resumeSessionRef);
             const envPrefix = `PI_TASK_TOOL_DISABLED=1`;
+            const forceTmuxBackend = process.env.PI_TASK_BACKEND === "tmux" ||
+                process.env.PI_TASK_USE_TMUX_BACKEND === "1";
+            const forceSdkBackend = process.env.PI_TASK_BACKEND === "sdk" ||
+                process.env.PI_TASK_USE_SDK_BACKEND === "1";
+            const tmuxAvailable = hasTmux();
+            const useSdkBackend = forceSdkBackend || (!forceTmuxBackend && !tmuxAvailable);
             const toolSelection = buildAgentToolSelection({
                 tools: agent.tools,
                 disallowedTools: agent.disallowedTools,
@@ -834,8 +390,10 @@ export default function (pi) {
                 foregroundTasks.set(id, foregroundTask);
                 ensureTaskWidget(ctx);
             }
-            // Prefer tmux for observability, but fall back to the SDK in headless/CI/RPC.
-            if (!hasTmux()) {
+            // Prefer tmux when the parent Pi is running inside tmux so users can watch
+            // the subagent's interactive Pi TUI. Fall back to the SDK only when tmux is
+            // unavailable, or when explicitly forced with PI_TASK_BACKEND=sdk.
+            if (useSdkBackend) {
                 if (isBackground) {
                     const bgtask = {
                         dir: artifactsDir,
@@ -887,14 +445,12 @@ export default function (pi) {
                         content: [
                             {
                                 type: "text",
-                                text: `Task ${id} started with SDK backend (tmux unavailable).`,
+                                text: `Task ${id} started with SDK backend.`,
                             },
                         ],
                         details: {
                             task_id: id,
                             background: true,
-                            backend: "sdk",
-                            result_path: resultPath,
                             conversation_id: conversationId,
                         },
                     };
@@ -919,7 +475,6 @@ export default function (pi) {
                             phase: "done",
                             backend: "sdk",
                             session_path: sessionPath,
-                            result_path: resultPath,
                             conversation_id: conversationId,
                         },
                     };
@@ -944,12 +499,15 @@ export default function (pi) {
                 }
             }
             const shellCommand = `${envPrefix} pi ${piArgs.map((a) => shellQuote(a)).join(" ")}`;
+            const sessionFile = join(sessionDir, sessionName + ".jsonl");
+            const tmuxCommand = wrapWithPaneExitWatcher(sessionFile, `cd ${shellQuote(ctx.cwd)} && ${shellCommand}`);
             let paneId;
             let originalPane;
             try {
-                const splitResult = splitWindowPane(ctx.cwd, `cd ${shellQuote(ctx.cwd)} && ${shellCommand}`);
+                const splitResult = splitWindowPane(ctx.cwd, tmuxCommand);
                 paneId = splitResult.paneId;
                 originalPane = splitResult.originalPane;
+                setPaneRemainOnExit(paneId, true);
                 if (foregroundTask) {
                     foregroundTask.paneId = paneId;
                     foregroundTask.originalPane = originalPane;
@@ -985,8 +543,31 @@ export default function (pi) {
                     status: "running",
                     background: false,
                 });
+                // Poll tool-call progress while waiting for completion
+                let lastToolCalls = -1;
+                const onAbort = () => clearInterval(toolProgressInterval);
+                const toolProgressInterval = setInterval(() => {
+                    try {
+                        const stats = countToolUses(sessionDir, sessionName);
+                        if (stats.toolUses > 0 && stats.toolUses !== lastToolCalls) {
+                            lastToolCalls = stats.toolUses;
+                            _onUpdate?.({
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `${stats.toolUses} tool call${stats.toolUses !== 1 ? "s" : ""}`,
+                                    },
+                                ],
+                                details: { toolCalls: stats.toolUses },
+                            });
+                        }
+                    }
+                    catch {
+                        // session file may not exist yet
+                    }
+                }, COUNT_POLL_MS);
+                signal?.addEventListener("abort", onAbort, { once: true });
                 const completion = await waitForSessionTaskCompletion({
-                    resultPath,
                     sessionDir,
                     sessionName,
                     paneId,
@@ -995,6 +576,8 @@ export default function (pi) {
                     pollMs: 1000,
                     sinceMs: startedAt,
                 });
+                clearInterval(toolProgressInterval);
+                signal?.removeEventListener("abort", onAbort);
                 const content = completion.content;
                 const phase = completion.status === "completed"
                     ? "done"
@@ -1017,7 +600,9 @@ export default function (pi) {
                     completedAt: Date.now(),
                     background: false,
                 });
-                killAgentPane(paneId, originalPane);
+                if (phase === "done") {
+                    killAgentPane(paneId, originalPane);
+                }
                 foregroundTasks.delete(id);
                 clearTaskWidgetIfIdle();
                 if (conversationId) {
@@ -1038,13 +623,7 @@ export default function (pi) {
                     content: [
                         {
                             type: "text",
-                            text: [
-                                `${parsed.status || "done"}: ${parsed.summary || content.slice(0, 300)}`,
-                                toolUses > 0 ? `\n${toolUses} toolcalls` : "",
-                                durationMs >= 1000 ? `\n${formatMs(durationMs)}` : "",
-                            ]
-                                .filter(Boolean)
-                                .join(""),
+                            text: parsed.summary || content.trim(),
                         },
                     ],
                     details: {
@@ -1052,7 +631,7 @@ export default function (pi) {
                         agent_type: agent.name,
                         description: descText,
                         phase,
-                        status: phase === "done" ? parsed.status || "done" : phase,
+                        status: "done",
                         summary: parsed.summary || "",
                         findings: parsed.findings || "",
                         evidence: parsed.evidence || "",
@@ -1112,13 +691,7 @@ export default function (pi) {
                     // Clean registry
                     const remaining = readRegistry(piDir).filter((e) => e.id !== id);
                     writeRegistry(piDir, remaining);
-                    if (backgroundTasks.size === 0) {
-                        stopWidget();
-                        if (widgetCtx) {
-                            widgetCtx.ui.setWidget("task", undefined);
-                            widgetCtx = null;
-                        }
-                    }
+                    clearTaskWidgetIfIdle();
                 }, { once: true });
             }
             // ── Sticky widget ──────────────────────────────────────────────────
@@ -1144,79 +717,8 @@ export default function (pi) {
                 },
             };
         },
-        renderCall(args, theme, _context) {
-            const agentName = args.agent_type || "...";
-            const desc = args.description || "";
-            let text = theme.fg("toolTitle", "");
-            text += theme.fg("accent", agentName);
-            if (desc)
-                text += theme.fg("dim", ` - ${desc}`);
-            return new Text(text, 0, 0);
-        },
-        renderResult(result, { expanded }, theme, _context) {
-            const d = result.details;
-            if (!d)
-                return new Text("", 0, 0);
-            if (d.background) {
-                const toolUses = d.tool_uses || 0;
-                const durationMs = d.duration_ms || 0;
-                const confidence = d.confidence || "";
-                const useStr = toolUses > 0 ? `${toolUses} toolcalls` : "";
-                const durStr = durationMs >= 1000 ? formatMs(durationMs) : "";
-                const statsParts = [useStr, durStr].filter(Boolean);
-                const statsText = statsParts.join(" \u2022 ");
-                const confStr = confidence ? `[${confidence.toUpperCase()}]` : "";
-                const statsLine = [confStr, statsText].filter(Boolean).join(" ");
-                const subtleBg = (text) => `\x1b[48;2;30;28;44m${text}\x1b[0m`;
-                return new Text(statsLine ? " " + theme.fg("dim", statsLine.trim()) : "", 0, 0, subtleBg);
-            }
-            if (d.phase === "timeout" ||
-                d.phase === "aborted" ||
-                d.phase === "failed") {
-                const line = theme.fg("error", "x") + " " + theme.fg("dim", `[${d.phase}]`);
-                return new Text(line, 0, 0);
-            }
-            const isError = d.status === "failure" ||
-                d.status === "blocked" ||
-                d.status === "unknown" ||
-                d.status === "timeout" ||
-                d.status === "failed";
-            const durationMs = d.duration_ms || 0;
-            const toolUses = d.tool_uses || 0;
-            const useStr = toolUses > 0 ? `${toolUses} toolcalls` : "";
-            const durStr = durationMs >= 1000 ? formatMs(durationMs) : "";
-            const statsParts = [useStr, durStr].filter(Boolean);
-            const statsStr = statsParts.length
-                ? " " + theme.fg("dim", statsParts.join(" • "))
-                : "";
-            const icon = isError ? theme.fg("error", "x") : theme.fg("success", "✓");
-            const statusLabel = d.status && d.status !== "done" ? d.status : "done";
-            let line = icon +
-                " " +
-                theme.fg(isError ? "error" : "success", statusLabel) +
-                statsStr;
-            if (expanded) {
-                const s = d.summary || "";
-                const f = d.findings || "";
-                const e = d.evidence || "";
-                if (s)
-                    line += "\n" + theme.fg("muted", s);
-                if (f)
-                    line += "\n" + theme.fg("dim", f);
-                if (e)
-                    line += "\n" + theme.fg("muted", "Evidence: ") + theme.fg("dim", e);
-            }
-            else {
-                const preview = (d.summary || "").slice(0, 80);
-                if (preview)
-                    line += "\n" + theme.fg("dim", `  ⎿  ${preview}`);
-                else
-                    line +=
-                        "\n" +
-                            theme.fg("dim", `  ⎿  ${isError ? d.status || "error" : "Done"}`);
-            }
-            return new Text(line, 0, 0);
-        },
+        renderCall,
+        renderResult,
     });
     pi.registerCommand("task-sessions", {
         description: "List durable pi-task conversations",