@tintinweb/pi-subagents 0.4.9 → 0.4.11

package/dist/index.js

@@ -9,18 +9,20 @@
  * Commands:
  *   /agents                 — Interactive agent management menu
  */
-import { existsSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
+import { join } from "node:path";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { steerAgent, getAgentConversation, getDefaultMaxTurns, setDefaultMaxTurns, getGraceTurns, setGraceTurns } from "./agent-runner.js";
-import { GroupJoinManager } from "./group-join.js";
-import { getAvailableTypes, getAllTypes, getDefaultAgentNames, getUserAgentNames, getAgentConfig, resolveType, registerAgents, BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
+import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { GroupJoinManager } from "./group-join.js";
 import { resolveModel } from "./model-resolver.js";
-import { AgentWidget, SPINNER, formatTokens, formatMs, formatDuration, getDisplayName, getPromptModeLabel, describeActivity, } from "./ui/agent-widget.js";
+import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { AgentWidget, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 // ---- Shared helpers ----
 /** Tool execute return value for a text response. */
 function textResult(msg, details) {
@@ -41,8 +43,8 @@ function safeFormatTokens(session) {
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
  * Used by both foreground and background paths to avoid duplication.
  */
-function createActivityTracker(onStreamUpdate) {
-    const state = { activeTools: new Map(), toolUses: 0, tokens: "", responseText: "", session: undefined };
+function createActivityTracker(maxTurns, onStreamUpdate) {
+    const state = { activeTools: new Map(), toolUses: 0, turnCount: 1, maxTurns, tokens: "", responseText: "", session: undefined };
     const callbacks = {
         onToolActivity: (activity) => {
             if (activity.type === "start") {
@@ -64,6 +66,10 @@ function createActivityTracker(onStreamUpdate) {
             state.responseText = fullText;
             onStreamUpdate?.();
         },
+        onTurnEnd: (turnCount) => {
+            state.turnCount = turnCount;
+            onStreamUpdate?.();
+        },
         onSessionCreated: (session) => {
             state.session = session;
         },
@@ -89,12 +95,47 @@ function getStatusNote(status) {
         default: return "";
     }
 }
+/** Escape XML special characters to prevent injection in structured notifications. */
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Format a structured task notification matching Claude Code's <task-notification> XML. */
+function formatTaskNotification(record, resultMaxLen) {
+    const status = getStatusLabel(record.status, record.error);
+    const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+    let totalTokens = 0;
+    try {
+        if (record.session) {
+            const stats = record.session.getSessionStats();
+            totalTokens = stats.tokens?.total ?? 0;
+        }
+    }
+    catch { /* session stats unavailable */ }
+    const resultPreview = record.result
+        ? record.result.length > resultMaxLen
+            ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+            : record.result
+        : "No output.";
+    return [
+        `<task-notification>`,
+        `<task-id>${record.id}</task-id>`,
+        record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
+        record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
+        `<status>${escapeXml(status)}</status>`,
+        `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+        `<result>${escapeXml(resultPreview)}</result>`,
+        `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
+        `</task-notification>`,
+    ].filter(Boolean).join('\n');
+}
 /** Build AgentDetails from a base + record-specific fields. */
-function buildDetails(base, record, overrides) {
+function buildDetails(base, record, activity, overrides) {
     return {
         ...base,
         toolUses: record.toolUses,
         tokens: safeFormatTokens(record.session),
+        turnCount: activity?.turnCount,
+        maxTurns: activity?.maxTurns,
         durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
         status: record.status,
         agentId: record.id,
@@ -102,7 +143,78 @@ function buildDetails(base, record, overrides) {
         ...overrides,
     };
 }
+/** Build notification details for the custom message renderer. */
+function buildNotificationDetails(record, resultMaxLen, activity) {
+    let totalTokens = 0;
+    try {
+        if (record.session)
+            totalTokens = record.session.getSessionStats().tokens?.total ?? 0;
+    }
+    catch { }
+    return {
+        id: record.id,
+        description: record.description,
+        status: record.status,
+        toolUses: record.toolUses,
+        turnCount: activity?.turnCount ?? 0,
+        maxTurns: activity?.maxTurns,
+        totalTokens,
+        durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+        outputFile: record.outputFile,
+        error: record.error,
+        resultPreview: record.result
+            ? record.result.length > resultMaxLen
+                ? record.result.slice(0, resultMaxLen) + "…"
+                : record.result
+            : "No output.",
+    };
+}
 export default function (pi) {
+    // ---- Register custom notification renderer ----
+    pi.registerMessageRenderer("subagent-notification", (message, { expanded }, theme) => {
+        const d = message.details;
+        if (!d)
+            return undefined;
+        function renderOne(d) {
+            const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
+            const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+            const statusText = isError ? d.status
+                : d.status === "steered" ? "completed (steered)"
+                    : "completed";
+            // Line 1: icon + agent description + status
+            let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+            // Line 2: stats
+            const parts = [];
+            if (d.turnCount > 0)
+                parts.push(formatTurns(d.turnCount, d.maxTurns));
+            if (d.toolUses > 0)
+                parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+            if (d.totalTokens > 0)
+                parts.push(formatTokens(d.totalTokens));
+            if (d.durationMs > 0)
+                parts.push(formatMs(d.durationMs));
+            if (parts.length) {
+                line += "\n  " + parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+            }
+            // Line 3: result preview (collapsed) or full (expanded)
+            if (expanded) {
+                const lines = d.resultPreview.split("\n").slice(0, 30);
+                for (const l of lines)
+                    line += "\n" + theme.fg("dim", `  ${l}`);
+            }
+            else {
+                const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
+                line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
+            }
+            // Line 4: output file link (if present)
+            if (d.outputFile) {
+                line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
+            }
+            return line;
+        }
+        const all = [d, ...(d.others ?? [])];
+        return new Text(all.map(renderOne).join("\n"), 0, 0);
+    });
     /** Reload agents from .pi/agents/*.md and merge with defaults (called on init and each Agent invocation). */
     const reloadCustomAgents = () => {
         const userAgents = loadCustomAgents(process.cwd());
@@ -112,60 +224,120 @@ export default function (pi) {
     reloadCustomAgents();
     // ---- Agent activity tracking + widget ----
     const agentActivity = new Map();
+    // ---- Cancellable pending notifications ----
+    // Holds notifications briefly so get_subagent_result can cancel them
+    // before they reach pi.sendMessage (fire-and-forget).
+    const pendingNudges = new Map();
+    const NUDGE_HOLD_MS = 200;
+    function scheduleNudge(key, send, delay = NUDGE_HOLD_MS) {
+        cancelNudge(key);
+        pendingNudges.set(key, setTimeout(() => {
+            pendingNudges.delete(key);
+            send();
+        }, delay));
+    }
+    function cancelNudge(key) {
+        const timer = pendingNudges.get(key);
+        if (timer != null) {
+            clearTimeout(timer);
+            pendingNudges.delete(key);
+        }
+    }
     // ---- Individual nudge helper (async join mode) ----
+    function emitIndividualNudge(record) {
+        if (record.resultConsumed)
+            return; // re-check at send time
+        const notification = formatTaskNotification(record, 500);
+        const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : '';
+        pi.sendMessage({
+            customType: "subagent-notification",
+            content: notification + footer,
+            display: true,
+            details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
+        }, { deliverAs: "followUp" });
+    }
     function sendIndividualNudge(record) {
-        const displayName = getDisplayName(record.type);
-        const duration = formatDuration(record.startedAt, record.completedAt);
-        const status = getStatusLabel(record.status, record.error);
-        const resultPreview = record.result
-            ? record.result.length > 500
-                ? record.result.slice(0, 500) + "\n...(truncated, use get_subagent_result for full output)"
-                : record.result
-            : "No output.";
         agentActivity.delete(record.id);
         widget.markFinished(record.id);
-        const tokens = safeFormatTokens(record.session);
-        const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
-        pi.sendUserMessage(`Background agent completed: ${displayName} (${record.description})\n` +
-            `Agent ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n\n` +
-            resultPreview, { deliverAs: "followUp" });
+        scheduleNudge(record.id, () => emitIndividualNudge(record));
         widget.update();
     }
-    /** Format a single agent's summary for grouped notification. */
-    function formatAgentSummary(record) {
-        const displayName = getDisplayName(record.type);
-        const duration = formatDuration(record.startedAt, record.completedAt);
-        const status = getStatusLabel(record.status, record.error);
-        const resultPreview = record.result
-            ? record.result.length > 300
-                ? record.result.slice(0, 300) + "\n...(truncated)"
-                : record.result
-            : "No output.";
-        const tokens = safeFormatTokens(record.session);
-        const toolStats = tokens ? `Tools: ${record.toolUses} | ${tokens}` : `Tools: ${record.toolUses}`;
-        return `- ${displayName} (${record.description})\n  ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n  ${resultPreview}`;
-    }
     // ---- Group join manager ----
     const groupJoin = new GroupJoinManager((records, partial) => {
-        // Filter out agents whose results were already consumed via get_subagent_result
-        const unconsumed = records.filter(r => !r.resultConsumed);
         for (const r of records) {
             agentActivity.delete(r.id);
             widget.markFinished(r.id);
         }
-        // If all results were already consumed, skip the notification entirely
-        if (unconsumed.length === 0) {
-            widget.update();
-            return;
-        }
-        const total = unconsumed.length;
-        const label = partial ? `${total} agent(s) finished (partial — others still running)` : `${total} agent(s) finished`;
-        const summary = unconsumed.map(r => formatAgentSummary(r)).join("\n\n");
-        pi.sendUserMessage(`Background agent group completed: ${label}\n\n${summary}\n\nUse get_subagent_result for full output.`, { deliverAs: "followUp" });
+        const groupKey = `group:${records.map(r => r.id).join(",")}`;
+        scheduleNudge(groupKey, () => {
+            // Re-check at send time
+            const unconsumed = records.filter(r => !r.resultConsumed);
+            if (unconsumed.length === 0) {
+                widget.update();
+                return;
+            }
+            const notifications = unconsumed.map(r => formatTaskNotification(r, 300)).join('\n\n');
+            const label = partial
+                ? `${unconsumed.length} agent(s) finished (partial — others still running)`
+                : `${unconsumed.length} agent(s) finished`;
+            const [first, ...rest] = unconsumed;
+            const details = buildNotificationDetails(first, 300, agentActivity.get(first.id));
+            if (rest.length > 0) {
+                details.others = rest.map(r => buildNotificationDetails(r, 300, agentActivity.get(r.id)));
+            }
+            pi.sendMessage({
+                customType: "subagent-notification",
+                content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+                display: true,
+                details,
+            }, { deliverAs: "followUp" });
+        });
         widget.update();
     }, 30_000);
+    /** Helper: build event data for lifecycle events from an AgentRecord. */
+    function buildEventData(record) {
+        const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+        let tokens;
+        try {
+            if (record.session) {
+                const stats = record.session.getSessionStats();
+                tokens = {
+                    input: stats.tokens?.input ?? 0,
+                    output: stats.tokens?.output ?? 0,
+                    total: stats.tokens?.total ?? 0,
+                };
+            }
+        }
+        catch { /* session stats unavailable */ }
+        return {
+            id: record.id,
+            type: record.type,
+            description: record.description,
+            result: record.result,
+            error: record.error,
+            status: record.status,
+            toolUses: record.toolUses,
+            durationMs,
+            tokens,
+        };
+    }
     // Background completion: route through group join or send individual nudge
     const manager = new AgentManager((record) => {
+        // Emit lifecycle event based on terminal status
+        const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+        const eventData = buildEventData(record);
+        if (isError) {
+            pi.events.emit("subagents:failed", eventData);
+        }
+        else {
+            pi.events.emit("subagents:completed", eventData);
+        }
+        // Persist final record for cross-extension history reconstruction
+        pi.appendEntry("subagents:record", {
+            id: record.id, type: record.type, description: record.description,
+            status: record.status, result: record.result, error: record.error,
+            startedAt: record.startedAt, completedAt: record.completedAt,
+        });
         // Skip notification if result was already consumed via get_subagent_result
         if (record.resultConsumed) {
             agentActivity.delete(record.id);
@@ -186,6 +358,13 @@ export default function (pi) {
         // 'held' → do nothing, group will fire later
         // 'delivered' → group callback already fired
         widget.update();
+    }, undefined, (record) => {
+        // Emit started event when agent transitions to running (including from queue)
+        pi.events.emit("subagents:started", {
+            id: record.id,
+            type: record.type,
+            description: record.description,
+        });
     });
     // Expose manager via Symbol.for() global registry for cross-package access.
     // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
@@ -193,11 +372,36 @@ export default function (pi) {
     globalThis[MANAGER_KEY] = {
         waitForAll: () => manager.waitForAll(),
         hasRunning: () => manager.hasRunning(),
+        spawn: (piRef, ctx, type, prompt, options) => manager.spawn(piRef, ctx, type, prompt, options),
+        getRecord: (id) => manager.getRecord(id),
     };
-    // Wait for all subagents on shutdown, then dispose the manager
+    // --- Cross-extension RPC via pi.events ---
+    let currentCtx;
+    // Capture ctx from session_start for RPC spawn handler
+    pi.on("session_start", async (_event, ctx) => {
+        currentCtx = ctx;
+        manager.clearCompleted(); // preserve existing behavior
+    });
+    pi.on("session_switch", () => { manager.clearCompleted(); });
+    const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc } = registerRpcHandlers({
+        events: pi.events,
+        pi,
+        getCtx: () => currentCtx,
+        manager,
+    });
+    // Broadcast readiness so extensions loaded after us can discover us
+    pi.events.emit("subagents:ready", {});
+    // On shutdown, abort all agents immediately and clean up.
+    // If the session is going down, there's nothing left to consume agent results.
     pi.on("session_shutdown", async () => {
+        unsubSpawnRpc();
+        unsubPingRpc();
+        currentCtx = undefined;
         delete globalThis[MANAGER_KEY];
-        await manager.waitForAll();
+        manager.abortAll();
+        for (const timer of pendingNudges.values())
+            clearTimeout(timer);
+        pendingNudges.clear();
         manager.dispose();
     });
     // Live widget: show running agents above editor
@@ -306,6 +510,7 @@ Guidelines:
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).
 - Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
         parameters: Type.Object({
             prompt: Type.String({
@@ -324,7 +529,7 @@ Guidelines:
                 description: "Thinking level: off, minimal, low, medium, high, xhigh. Overrides agent default.",
             })),
             max_turns: Type.Optional(Type.Number({
-                description: "Maximum number of agentic turns before stopping.",
+                description: "Maximum number of agentic turns before stopping. Omit for unlimited (default).",
                 minimum: 1,
             })),
             run_in_background: Type.Optional(Type.Boolean({
@@ -339,6 +544,9 @@ Guidelines:
             inherit_context: Type.Optional(Type.Boolean({
                 description: "If true, fork parent conversation into the agent. Default: false (fresh context).",
             })),
+            isolation: Type.Optional(Type.Literal("worktree", {
+                description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
+            })),
             join_mode: Type.Optional(Type.Union([
                 Type.Literal("async"),
                 Type.Literal("group"),
@@ -356,13 +564,16 @@ Guidelines:
                 const text = result.content[0]?.type === "text" ? result.content[0].text : "";
                 return new Text(text, 0, 0);
             }
-            // Helper: build "haiku · thinking: high · 3 tool uses · 33.8k tokens" stats string
+            // Helper: build "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k tokens" stats string
             const stats = (d) => {
                 const parts = [];
                 if (d.modelName)
                     parts.push(d.modelName);
                 if (d.tags)
                     parts.push(...d.tags);
+                if (d.turnCount != null && d.turnCount > 0) {
+                    parts.push(formatTurns(d.turnCount, d.maxTurns));
+                }
                 if (d.toolUses > 0)
                     parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
                 if (d.tokens)
@@ -426,7 +637,7 @@ Guidelines:
             return new Text(line, 0, 0);
         },
         // ---- Execute ----
-        execute: async (_toolCallId, params, signal, onUpdate, ctx) => {
+        execute: async (toolCallId, params, signal, onUpdate, ctx) => {
             // Ensure we have UI context for widget rendering
             widget.setUICtx(ctx.ui);
             // Reload custom agents so new .pi/agents/*.md files are picked up without restart
@@ -458,6 +669,7 @@ Guidelines:
             const inheritContext = params.inherit_context ?? customConfig?.inheritContext ?? false;
             const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
             const isolated = params.isolated ?? customConfig?.isolated ?? false;
+            const isolation = params.isolation ?? customConfig?.isolation;
             // Build display tags for non-default config
             const parentModelId = ctx.model?.id;
             const effectiveModelId = model?.id;
@@ -472,6 +684,9 @@ Guidelines:
                 agentTags.push(`thinking: ${thinking}`);
             if (isolated)
                 agentTags.push("isolated");
+            if (isolation === "worktree")
+                agentTags.push("worktree");
+            const effectiveMaxTurns = params.max_turns ?? customConfig?.maxTurns ?? getDefaultMaxTurns();
             // Shared base fields for all AgentDetails in this call
             const detailBase = {
                 displayName,
@@ -497,8 +712,20 @@ Guidelines:
             }
             // Background execution
             if (runInBackground) {
-                const { state: bgState, callbacks: bgCallbacks } = createActivityTracker();
-                const id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+                const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
+                // Wrap onSessionCreated to wire output file streaming.
+                // The callback lazily reads record.outputFile (set right after spawn)
+                // rather than closing over a value that doesn't exist yet.
+                let id;
+                const origBgOnSession = bgCallbacks.onSessionCreated;
+                bgCallbacks.onSessionCreated = (session) => {
+                    origBgOnSession(session);
+                    const rec = manager.getRecord(id);
+                    if (rec?.outputFile) {
+                        rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
+                    }
+                };
+                id = manager.spawn(pi, ctx, subagentType, params.prompt, {
                     description: params.description,
                     model,
                     maxTurns: params.max_turns,
@@ -506,13 +733,19 @@ Guidelines:
                     inheritContext,
                     thinkingLevel: thinking,
                     isBackground: true,
+                    isolation,
                     ...bgCallbacks,
                 });
-                // Determine join mode and track for batching
+                // Set output file + join mode synchronously after spawn, before the
+                // event loop yields — onSessionCreated is async so this is safe.
                 const joinMode = params.join_mode ?? defaultJoinMode;
                 const record = manager.getRecord(id);
-                if (record)
+                if (record) {
                     record.joinMode = joinMode;
+                    record.toolCallId = toolCallId;
+                    record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
+                    writeInitialEntry(record.outputFile, id, params.prompt, ctx.cwd);
+                }
                 if (joinMode === 'async') {
                     // Explicit async — not part of any batch
                 }
@@ -528,11 +761,19 @@ Guidelines:
                 agentActivity.set(id, bgState);
                 widget.ensureTimer();
                 widget.update();
+                // Emit created event
+                pi.events.emit("subagents:created", {
+                    id,
+                    type: subagentType,
+                    description: params.description,
+                    isBackground: true,
+                });
                 const isQueued = record?.status === "queued";
                 return textResult(`Agent ${isQueued ? "queued" : "started"} in background.\n` +
                     `Agent ID: ${id}\n` +
                     `Type: ${displayName}\n` +
                     `Description: ${params.description}\n` +
+                    (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
                     (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
                     `\nYou will be notified when this agent completes.\n` +
                     `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
@@ -547,6 +788,8 @@ Guidelines:
                     ...detailBase,
                     toolUses: fgState.toolUses,
                     tokens: fgState.tokens,
+                    turnCount: fgState.turnCount,
+                    maxTurns: fgState.maxTurns,
                     durationMs: Date.now() - startedAt,
                     status: "running",
                     activity: describeActivity(fgState.activeTools, fgState.responseText),
@@ -557,7 +800,7 @@ Guidelines:
                     details: details,
                 });
             };
-            const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(streamUpdate);
+            const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
             // Wire session creation to register in widget
             const origOnSession = fgCallbacks.onSessionCreated;
             fgCallbacks.onSessionCreated = (session) => {
@@ -584,6 +827,7 @@ Guidelines:
                 isolated,
                 inheritContext,
                 thinkingLevel: thinking,
+                isolation,
                 ...fgCallbacks,
             });
             clearInterval(spinnerInterval);
@@ -594,7 +838,7 @@ Guidelines:
             }
             // Get final token count
             const tokenText = safeFormatTokens(fgState.session);
-            const details = buildDetails(detailBase, record, { tokens: tokenText });
+            const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
             const fallbackNote = fellBack
                 ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
                 : "";
@@ -630,8 +874,13 @@ Guidelines:
             if (!record) {
                 return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
             }
-            // Wait for completion if requested
+            // Wait for completion if requested.
+            // Pre-mark resultConsumed BEFORE awaiting: onComplete fires inside .then()
+            // (attached earlier at spawn time) and always runs before this await resumes.
+            // Setting the flag here prevents a redundant follow-up notification.
             if (params.wait && record.status === "running" && record.promise) {
+                record.resultConsumed = true;
+                cancelNudge(params.agent_id);
                 await record.promise;
             }
             const displayName = getDisplayName(record.type);
@@ -653,6 +902,7 @@ Guidelines:
             // Mark result as consumed — suppresses the completion notification
             if (record.status !== "running" && record.status !== "queued") {
                 record.resultConsumed = true;
+                cancelNudge(params.agent_id);
             }
             // Verbose: include full conversation
             if (params.verbose && record.session) {
@@ -687,10 +937,16 @@ Guidelines:
                 return textResult(`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`);
             }
             if (!record.session) {
-                return textResult(`Agent "${params.agent_id}" has no active session yet. It may still be initializing.`);
+                // Session not ready yet — queue the steer for delivery once initialized
+                if (!record.pendingSteers)
+                    record.pendingSteers = [];
+                record.pendingSteers.push(params.message);
+                pi.events.emit("subagents:steered", { id: record.id, message: params.message });
+                return textResult(`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`);
             }
             try {
                 await steerAgent(record.session, params.message);
+                pi.events.emit("subagents:steered", { id: record.id, message: params.message });
                 return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.`);
             }
             catch (err) {
@@ -961,12 +1217,18 @@ Guidelines:
             fmFields.push("skills: false");
         else if (Array.isArray(cfg.skills))
             fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+        if (cfg.disallowedTools?.length)
+            fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
         if (cfg.inheritContext)
             fmFields.push("inherit_context: true");
         if (cfg.runInBackground)
             fmFields.push("run_in_background: true");
         if (cfg.isolated)
             fmFields.push("isolated: true");
+        if (cfg.memory)
+            fmFields.push(`memory: ${cfg.memory}`);
+        if (cfg.isolation)
+            fmFields.push(`isolation: ${cfg.isolation}`);
         const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
         const { writeFileSync } = await import("node:fs");
         writeFileSync(targetPath, content, "utf-8");
@@ -1073,13 +1335,16 @@ description: <one-line description shown in UI>
 tools: <comma-separated built-in tools: read, bash, edit, write, grep, find, ls. Use "none" for no tools. Omit for all tools>
 model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-20251001". Omit to inherit parent model>
 thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
-max_turns: <optional max agentic turns, default 50. Omit for default>
+max_turns: <optional max agentic turns. 0 or omit for unlimited (default)>
 prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
 extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
-skills: <true (inherit all), false (none). Default: true>
+skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
+disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
 run_in_background: <true to run in background by default. Default: false>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>
+isolation: <"worktree" to run in isolated git worktree. Omit for normal>
 ---
 
 <system prompt body — instructions for the agent>
@@ -1205,7 +1470,7 @@ ${systemPrompt}
     async function showSettings(ctx) {
         const choice = await ctx.ui.select("Settings", [
             `Max concurrency (current: ${manager.getMaxConcurrent()})`,
-            `Default max turns (current: ${getDefaultMaxTurns()})`,
+            `Default max turns (current: ${getDefaultMaxTurns() ?? "unlimited"})`,
             `Grace turns (current: ${getGraceTurns()})`,
             `Join mode (current: ${getDefaultJoinMode()})`,
         ]);
@@ -1225,15 +1490,19 @@ ${systemPrompt}
             }
         }
         else if (choice.startsWith("Default max turns")) {
-            const val = await ctx.ui.input("Default max turns before wrap-up", String(getDefaultMaxTurns()));
+            const val = await ctx.ui.input("Default max turns before wrap-up (0 = unlimited)", String(getDefaultMaxTurns() ?? 0));
             if (val) {
                 const n = parseInt(val, 10);
-                if (n >= 1) {
+                if (n === 0) {
+                    setDefaultMaxTurns(undefined);
+                    ctx.ui.notify("Default max turns set to unlimited", "info");
+                }
+                else if (n >= 1) {
                     setDefaultMaxTurns(n);
                     ctx.ui.notify(`Default max turns set to ${n}`, "info");
                 }
                 else {
-                    ctx.ui.notify("Must be a positive integer.", "warning");
+                    ctx.ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
                 }
             }
         }