gsd-pi 2.78.0 → 2.78.1-dev.82bcf6b71

package/dist/resources/extensions/subagent/index.js

@@ -26,6 +26,7 @@ import { discoverAgents } from "./agents.js";
 import { createIsolation, mergeDeltaPatches, readIsolationMode, } from "./isolation.js";
 import { registerWorker, updateWorker } from "./worker-registry.js";
 import { loadEffectiveGSDPreferences } from "../gsd/preferences.js";
+import { emitJournalEvent } from "../gsd/journal.js";
 import { CmuxClient, shellEscape } from "../cmux/index.js";
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
@@ -541,11 +542,13 @@ export default function (pi) {
             "Use chain mode to pipeline: scout finds context, planner designs, worker implements.",
         ].join(" "),
         promptGuidelines: [
-            "Use subagent to delegate self-contained tasks that benefit from an isolated context window.",
-            "Use scout agent first when you need codebase context before implementing.",
-            "Use chain mode for scout→planner→worker or worker→reviewer→worker pipelines.",
-            "Use parallel mode when tasks are independent and don't need each other's output.",
-            "Always check available agents with /subagent before choosing one.",
+            "Prefer subagent dispatch over inline work whenever a task is self-contained — recon, planning, review, refactor, test writing, security audit, doc writing. Each dispatch gets a fresh context window, so your main session stays focused on synthesis.",
+            "Before reading more than ~3 files to understand something, dispatch the scout agent and work from its compressed report instead.",
+            "Before any change touching ≥2 packages, the orchestration kernel, auto-mode, or a public API, dispatch the planner agent first. Plan first, then implement.",
+            "You MUST use parallel mode when ≥2 ready tasks are independent of each other's output. Do not serialize independent tasks manually — that wastes wall time and context.",
+            "Use chain mode for sequential pipelines where each step's output feeds the next: scout → planner → worker, or worker → reviewer → worker.",
+            "Before opening a PR or marking a slice complete, dispatch the reviewer agent (and security agent if the change touches auth, network, parsing, file IO, or shell exec).",
+            "Always check available agents with /subagent before choosing one — there are bundled specialists plus any project-scoped agents.",
         ],
         parameters: SubagentParams,
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -580,204 +583,347 @@ export default function (pi) {
                     details: makeDetails("single")([]),
                 };
             }
-            if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
-                const requestedAgentNames = new Set();
-                if (params.chain)
-                    for (const step of params.chain)
-                        requestedAgentNames.add(step.agent);
-                if (params.tasks)
-                    for (const t of params.tasks)
-                        requestedAgentNames.add(t.agent);
-                if (params.agent)
-                    requestedAgentNames.add(params.agent);
-                const projectAgentsRequested = Array.from(requestedAgentNames)
-                    .map((name) => agents.find((a) => a.name === name))
-                    .filter((a) => a?.source === "project");
-                if (projectAgentsRequested.length > 0) {
-                    const names = projectAgentsRequested.map((a) => a.name).join(", ");
-                    const dir = discovery.projectAgentsDir ?? "(unknown)";
-                    const ok = await ctx.ui.confirm("Run project-local agents?", `Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`);
-                    if (!ok)
+            // Dispatch telemetry — emit invoked once per dispatch and completed before each return.
+            // Fresh flowId per dispatch (subagent runs aren't currently plumbed with the parent
+            // auto-mode flowId; per-dispatch ids still let us measure frequency, batch size, mode).
+            const dispatchMode = hasChain ? "chain" : hasTasks ? "parallel" : "single";
+            const dispatchAgents = hasChain
+                ? params.chain.map((s) => s.agent)
+                : hasTasks
+                    ? params.tasks.map((t) => t.agent)
+                    : params.agent
+                        ? [params.agent]
+                        : [];
+            const dispatchTasks = hasChain
+                ? params.chain.map((s) => s.task)
+                : hasTasks
+                    ? params.tasks.map((t) => t.task)
+                    : params.task
+                        ? [params.task]
+                        : [];
+            const dispatchId = crypto.randomUUID();
+            const dispatchStartMs = Date.now();
+            let finalResults = [];
+            let dispatchCompletedEmitted = false;
+            emitJournalEvent(ctx.cwd, {
+                ts: new Date().toISOString(),
+                flowId: dispatchId,
+                seq: 0,
+                eventType: "subagent-invoked",
+                data: {
+                    dispatchId,
+                    mode: dispatchMode,
+                    agents: dispatchAgents,
+                    batchSize: dispatchAgents.length,
+                    unitType: getCurrentPhase() ?? null,
+                    isolated: useIsolation,
+                },
+            });
+            const zeroUsage = () => ({
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                cost: 0,
+                contextTokens: 0,
+                turns: 0,
+            });
+            const errorMessageFor = (err) => err instanceof Error ? err.message : String(err || "subagent dispatch failed");
+            const makeFailureResult = (err, agent, task, step) => {
+                const message = errorMessageFor(err);
+                return {
+                    agent,
+                    agentSource: "unknown",
+                    task,
+                    exitCode: 1,
+                    messages: [],
+                    stderr: message,
+                    usage: zeroUsage(),
+                    stopReason: signal?.aborted ? "aborted" : "error",
+                    errorMessage: message,
+                    ...(step !== undefined ? { step } : {}),
+                };
+            };
+            const synthesizeFailureResults = (err) => {
+                if (finalResults.length > 0) {
+                    let patchedRunning = false;
+                    const patched = finalResults.map((result) => {
+                        if (result.exitCode !== -1)
+                            return result;
+                        patchedRunning = true;
+                        const message = errorMessageFor(err);
                         return {
-                            content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
-                            details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+                            ...result,
+                            exitCode: 1,
+                            stderr: result.stderr || message,
+                            stopReason: signal?.aborted ? "aborted" : "error",
+                            errorMessage: result.errorMessage || message,
+                            usage: result.usage ?? zeroUsage(),
                         };
+                    });
+                    if (patchedRunning || patched.some((result) => result.exitCode !== 0))
+                        return patched;
+                    const nextIndex = finalResults.length < dispatchAgents.length ? finalResults.length : 0;
+                    if (nextIndex > 0) {
+                        return [
+                            ...finalResults,
+                            makeFailureResult(err, dispatchAgents[nextIndex] ?? "unknown", dispatchTasks[nextIndex] ?? "", dispatchMode === "chain" ? nextIndex + 1 : undefined),
+                        ];
+                    }
                 }
-            }
-            if (params.chain && params.chain.length > 0) {
-                const results = [];
-                let previousOutput = "";
-                for (let i = 0; i < params.chain.length; i++) {
-                    const step = params.chain[i];
-                    const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
-                    // Create update callback that includes all previous results
-                    const chainUpdate = onUpdate
-                        ? (partial) => {
-                            // Combine completed results with current streaming result
-                            const currentResult = partial.details?.results[0];
-                            if (currentResult) {
-                                const allResults = [...results, currentResult];
-                                onUpdate({
-                                    content: partial.content,
-                                    details: makeDetails("chain")(allResults),
-                                });
+                const agentsForFailure = dispatchAgents.length > 0 ? dispatchAgents : ["unknown"];
+                return agentsForFailure.map((agent, index) => makeFailureResult(err, agent, dispatchTasks[index] ?? "", dispatchMode === "chain" ? index + 1 : undefined));
+            };
+            const finishDispatch = (results) => {
+                if (dispatchCompletedEmitted)
+                    return;
+                finalResults = results;
+                dispatchCompletedEmitted = true;
+                const successCount = results.filter((r) => r.exitCode === 0).length;
+                const failureCount = results.filter((r) => r.exitCode !== 0).length;
+                const totalCost = results.reduce((s, r) => s + (r.usage?.cost ?? 0), 0);
+                const totalInputTokens = results.reduce((s, r) => s + (r.usage?.input ?? 0), 0);
+                const totalOutputTokens = results.reduce((s, r) => s + (r.usage?.output ?? 0), 0);
+                emitJournalEvent(ctx.cwd, {
+                    ts: new Date().toISOString(),
+                    flowId: dispatchId,
+                    seq: 1,
+                    eventType: "subagent-completed",
+                    data: {
+                        dispatchId,
+                        mode: dispatchMode,
+                        agents: dispatchAgents,
+                        successCount,
+                        failureCount,
+                        totalCost,
+                        totalInputTokens,
+                        totalOutputTokens,
+                        wallTimeMs: Date.now() - dispatchStartMs,
+                    },
+                });
+            };
+            try {
+                if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
+                    const requestedAgentNames = new Set();
+                    if (params.chain)
+                        for (const step of params.chain)
+                            requestedAgentNames.add(step.agent);
+                    if (params.tasks)
+                        for (const t of params.tasks)
+                            requestedAgentNames.add(t.agent);
+                    if (params.agent)
+                        requestedAgentNames.add(params.agent);
+                    const projectAgentsRequested = Array.from(requestedAgentNames)
+                        .map((name) => agents.find((a) => a.name === name))
+                        .filter((a) => a?.source === "project");
+                    if (projectAgentsRequested.length > 0) {
+                        const names = projectAgentsRequested.map((a) => a.name).join(", ");
+                        const dir = discovery.projectAgentsDir ?? "(unknown)";
+                        const ok = await ctx.ui.confirm("Run project-local agents?", `Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`);
+                        if (!ok) {
+                            finishDispatch([]);
+                            return {
+                                content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
+                                details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+                            };
+                        }
+                    }
+                }
+                if (params.chain && params.chain.length > 0) {
+                    const results = [];
+                    finalResults = results;
+                    let previousOutput = "";
+                    for (let i = 0; i < params.chain.length; i++) {
+                        const step = params.chain[i];
+                        const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
+                        // Create update callback that includes all previous results
+                        const chainUpdate = onUpdate
+                            ? (partial) => {
+                                // Combine completed results with current streaming result
+                                const currentResult = partial.details?.results[0];
+                                if (currentResult) {
+                                    const allResults = [...results, currentResult];
+                                    onUpdate({
+                                        content: partial.content,
+                                        details: makeDetails("chain")(allResults),
+                                    });
+                                }
                             }
+                            : undefined;
+                        const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"));
+                        results.push(result);
+                        const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+                        if (isError) {
+                            const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+                            finishDispatch(results);
+                            return {
+                                content: [{ type: "text", text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}` }],
+                                details: makeDetails("chain")(results),
+                                isError: true,
+                            };
                         }
-                        : undefined;
-                    const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"));
-                    results.push(result);
-                    const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-                    if (isError) {
-                        const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+                        previousOutput = getFinalOutput(result.messages);
+                    }
+                    finishDispatch(results);
+                    return {
+                        content: [{ type: "text", text: getFinalOutput(results[results.length - 1].messages) || "(no output)" }],
+                        details: makeDetails("chain")(results),
+                    };
+                }
+                if (params.tasks && params.tasks.length > 0) {
+                    if (params.tasks.length > MAX_PARALLEL_TASKS) {
+                        finishDispatch([]);
                         return {
-                            content: [{ type: "text", text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}` }],
-                            details: makeDetails("chain")(results),
-                            isError: true,
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+                                },
+                            ],
+                            details: makeDetails("parallel")([]),
                         };
                     }
-                    previousOutput = getFinalOutput(result.messages);
-                }
-                return {
-                    content: [{ type: "text", text: getFinalOutput(results[results.length - 1].messages) || "(no output)" }],
-                    details: makeDetails("chain")(results),
-                };
-            }
-            if (params.tasks && params.tasks.length > 0) {
-                if (params.tasks.length > MAX_PARALLEL_TASKS)
+                    // Track all results for streaming updates
+                    const allResults = new Array(params.tasks.length);
+                    // Initialize placeholder results
+                    for (let i = 0; i < params.tasks.length; i++) {
+                        allResults[i] = {
+                            agent: params.tasks[i].agent,
+                            agentSource: "unknown",
+                            task: params.tasks[i].task,
+                            exitCode: -1, // -1 = still running
+                            messages: [],
+                            stderr: "",
+                            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+                        };
+                    }
+                    finalResults = allResults;
+                    const emitParallelUpdate = () => {
+                        if (onUpdate) {
+                            const running = allResults.filter((r) => r.exitCode === -1).length;
+                            const done = allResults.filter((r) => r.exitCode !== -1).length;
+                            onUpdate({
+                                content: [
+                                    { type: "text", text: `Parallel: ${done}/${allResults.length} done, ${running} running...` },
+                                ],
+                                details: makeDetails("parallel")([...allResults]),
+                            });
+                        }
+                    };
+                    const MAX_RETRIES = 1; // Retry failed tasks once
+                    const batchId = crypto.randomUUID();
+                    const batchSize = params.tasks.length;
+                    // Pre-create a grid layout for cmux splits so agents get a clean tiled arrangement
+                    const gridSurfaces = cmuxSplitsEnabled
+                        ? await cmuxClient.createGridLayout(Math.min(batchSize, MAX_CONCURRENCY))
+                        : [];
+                    const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
+                        const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
+                        const runTask = () => cmuxSplitsEnabled
+                            ? runSingleAgentInCmuxSplit(cmuxClient, gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"), ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
+                                if (partial.details?.results[0]) {
+                                    allResults[index] = partial.details.results[0];
+                                    emitParallelUpdate();
+                                }
+                            }, makeDetails("parallel"))
+                            : runSingleAgent(ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
+                                if (partial.details?.results[0]) {
+                                    allResults[index] = partial.details.results[0];
+                                    emitParallelUpdate();
+                                }
+                            }, makeDetails("parallel"));
+                        let result = await runTask();
+                        // Auto-retry failed tasks (likely API rate limit or transient error)
+                        const isFailed = result.exitCode !== 0 || (result.messages.length === 0 && !signal?.aborted);
+                        if (isFailed && MAX_RETRIES > 0 && !signal?.aborted) {
+                            result = await runTask();
+                        }
+                        updateWorker(workerId, result.exitCode === 0 ? "completed" : "failed");
+                        allResults[index] = result;
+                        emitParallelUpdate();
+                        return result;
+                    });
+                    finalResults = results;
+                    const successCount = results.filter((r) => r.exitCode === 0).length;
+                    const summaries = results.map((r) => {
+                        const isError = r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+                        const output = isError
+                            ? (r.errorMessage || r.stderr || getFinalOutput(r.messages) || "(no output)")
+                            : getFinalOutput(r.messages);
+                        return `[${r.agent}] ${r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`}: ${output || "(no output)"}`;
+                    });
+                    finishDispatch(results);
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+                                text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n")}`,
                             },
                         ],
-                        details: makeDetails("parallel")([]),
-                    };
-                // Track all results for streaming updates
-                const allResults = new Array(params.tasks.length);
-                // Initialize placeholder results
-                for (let i = 0; i < params.tasks.length; i++) {
-                    allResults[i] = {
-                        agent: params.tasks[i].agent,
-                        agentSource: "unknown",
-                        task: params.tasks[i].task,
-                        exitCode: -1, // -1 = still running
-                        messages: [],
-                        stderr: "",
-                        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+                        details: makeDetails("parallel")(results),
                     };
                 }
-                const emitParallelUpdate = () => {
-                    if (onUpdate) {
-                        const running = allResults.filter((r) => r.exitCode === -1).length;
-                        const done = allResults.filter((r) => r.exitCode !== -1).length;
-                        onUpdate({
-                            content: [
-                                { type: "text", text: `Parallel: ${done}/${allResults.length} done, ${running} running...` },
-                            ],
-                            details: makeDetails("parallel")([...allResults]),
-                        });
-                    }
-                };
-                const MAX_RETRIES = 1; // Retry failed tasks once
-                const batchId = crypto.randomUUID();
-                const batchSize = params.tasks.length;
-                // Pre-create a grid layout for cmux splits so agents get a clean tiled arrangement
-                const gridSurfaces = cmuxSplitsEnabled
-                    ? await cmuxClient.createGridLayout(Math.min(batchSize, MAX_CONCURRENCY))
-                    : [];
-                const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
-                    const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
-                    const runTask = () => cmuxSplitsEnabled
-                        ? runSingleAgentInCmuxSplit(cmuxClient, gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"), ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
-                            if (partial.details?.results[0]) {
-                                allResults[index] = partial.details.results[0];
-                                emitParallelUpdate();
-                            }
-                        }, makeDetails("parallel"))
-                        : runSingleAgent(ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
-                            if (partial.details?.results[0]) {
-                                allResults[index] = partial.details.results[0];
-                                emitParallelUpdate();
+                if (params.agent && params.task) {
+                    let isolation = null;
+                    let mergeResult;
+                    try {
+                        const effectiveCwd = params.cwd ?? ctx.cwd;
+                        if (useIsolation) {
+                            const taskId = crypto.randomUUID();
+                            isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
+                        }
+                        const result = cmuxSplitsEnabled
+                            ? await runSingleAgentInCmuxSplit(cmuxClient, "right", ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, onUpdate, makeDetails("single"))
+                            : await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, onUpdate, makeDetails("single"));
+                        finalResults = [result];
+                        // Capture and merge delta if isolated
+                        if (isolation) {
+                            const patches = await isolation.captureDelta();
+                            if (patches.length > 0) {
+                                mergeResult = await mergeDeltaPatches(effectiveCwd, patches);
                             }
-                        }, makeDetails("parallel"));
-                    let result = await runTask();
-                    // Auto-retry failed tasks (likely API rate limit or transient error)
-                    const isFailed = result.exitCode !== 0 || (result.messages.length === 0 && !signal?.aborted);
-                    if (isFailed && MAX_RETRIES > 0 && !signal?.aborted) {
-                        result = await runTask();
-                    }
-                    updateWorker(workerId, result.exitCode === 0 ? "completed" : "failed");
-                    allResults[index] = result;
-                    emitParallelUpdate();
-                    return result;
-                });
-                const successCount = results.filter((r) => r.exitCode === 0).length;
-                const summaries = results.map((r) => {
-                    const isError = r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
-                    const output = isError
-                        ? (r.errorMessage || r.stderr || getFinalOutput(r.messages) || "(no output)")
-                        : getFinalOutput(r.messages);
-                    return `[${r.agent}] ${r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`}: ${output || "(no output)"}`;
-                });
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n")}`,
-                        },
-                    ],
-                    details: makeDetails("parallel")(results),
-                };
-            }
-            if (params.agent && params.task) {
-                let isolation = null;
-                let mergeResult;
-                try {
-                    const effectiveCwd = params.cwd ?? ctx.cwd;
-                    if (useIsolation) {
-                        const taskId = crypto.randomUUID();
-                        isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
-                    }
-                    const result = cmuxSplitsEnabled
-                        ? await runSingleAgentInCmuxSplit(cmuxClient, "right", ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, onUpdate, makeDetails("single"))
-                        : await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, onUpdate, makeDetails("single"));
-                    // Capture and merge delta if isolated
-                    if (isolation) {
-                        const patches = await isolation.captureDelta();
-                        if (patches.length > 0) {
-                            mergeResult = await mergeDeltaPatches(effectiveCwd, patches);
                         }
-                    }
-                    const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-                    if (isError) {
-                        const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+                        const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+                        if (isError) {
+                            const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+                            finishDispatch([result]);
+                            return {
+                                content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}` }],
+                                details: makeDetails("single")([result]),
+                                isError: true,
+                            };
+                        }
+                        let outputText = getFinalOutput(result.messages) || "(no output)";
+                        if (mergeResult && !mergeResult.success) {
+                            outputText += `\n\n⚠ Patch merge failed: ${mergeResult.error || "unknown error"}`;
+                        }
+                        finishDispatch([result]);
                         return {
-                            content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}` }],
+                            content: [{ type: "text", text: outputText }],
                             details: makeDetails("single")([result]),
-                            isError: true,
                         };
                     }
-                    let outputText = getFinalOutput(result.messages) || "(no output)";
-                    if (mergeResult && !mergeResult.success) {
-                        outputText += `\n\n⚠ Patch merge failed: ${mergeResult.error || "unknown error"}`;
-                    }
-                    return {
-                        content: [{ type: "text", text: outputText }],
-                        details: makeDetails("single")([result]),
-                    };
-                }
-                finally {
-                    if (isolation) {
-                        await isolation.cleanup();
+                    finally {
+                        if (isolation) {
+                            await isolation.cleanup();
+                        }
                     }
                 }
+                finishDispatch([]);
+                const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
+                return {
+                    content: [{ type: "text", text: `Invalid parameters. Available agents: ${available}` }],
+                    details: makeDetails("single")([]),
+                };
+            }
+            catch (err) {
+                if (!dispatchCompletedEmitted)
+                    finalResults = synthesizeFailureResults(err);
+                throw err;
+            }
+            finally {
+                finishDispatch(finalResults);
             }
-            const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
-            return {
-                content: [{ type: "text", text: `Invalid parameters. Available agents: ${available}` }],
-                details: makeDetails("single")([]),
-            };
         },
         renderCall(args, theme) {
             const scope = args.agentScope ?? "both";

package/dist/resources/skills/create-gsd-extension/SKILL.md

@@ -19,8 +19,8 @@ Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from
 3. **Commands** — Give users slash commands (`pi.registerCommand()`). Users type `/mycommand`.
 
 **Non-negotiable rules:**
-- Use `StringEnum` from `@mariozechner/pi-ai` for string enum params (NOT `Type.Union`/`Type.Literal` — breaks Google's API)
-- Truncate tool output to 50KB / 2000 lines max (use `truncateHead`/`truncateTail` from `@mariozechner/pi-coding-agent`)
+- Use `StringEnum` from `@gsd/pi-ai` for string enum params (NOT `Type.Union`/`Type.Literal` — breaks Google's API)
+- Truncate tool output to 50KB / 2000 lines max (use `truncateHead`/`truncateTail` from `@gsd/pi-coding-agent`)
 - Store stateful tool state in `details` for branching support
 - Check `signal?.aborted` in long-running tool executions
 - Use `pi.exec()` not `child_process` for shell commands
@@ -34,10 +34,10 @@ Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from
 
 | Package | Purpose |
 |---------|---------|
-| `@mariozechner/pi-coding-agent` | `ExtensionAPI`, `ExtensionContext`, `Theme`, event types, tool utilities, `DynamicBorder`, `BorderedLoader`, `CustomEditor`, `highlightCode` |
+| `@gsd/pi-coding-agent` | `ExtensionAPI`, `ExtensionContext`, `Theme`, event types, tool utilities, `DynamicBorder`, `BorderedLoader`, `CustomEditor`, `highlightCode` |
 | `@sinclair/typebox` | `Type.Object`, `Type.String`, `Type.Number`, `Type.Optional`, `Type.Boolean`, `Type.Array` |
-| `@mariozechner/pi-ai` | `StringEnum` (required for string enums), `Type` re-export |
-| `@mariozechner/pi-tui` | `Text`, `Box`, `Container`, `Spacer`, `Markdown`, `SelectList`, `Input`, `matchesKey`, `Key`, `truncateToWidth`, `visibleWidth` |
+| `@gsd/pi-ai` | `StringEnum` (required for string enums), `Type` re-export |
+| `@gsd/pi-tui` | `Text`, `Box`, `Container`, `Spacer`, `Markdown`, `SelectList`, `Input`, `matchesKey`, `Key`, `truncateToWidth`, `visibleWidth` |
 | Node.js built-ins | `node:fs`, `node:path`, `node:child_process`, etc. |
 
 </essential_principles>
@@ -65,6 +65,9 @@ All domain knowledge in `references/`:
 **Capabilities:** custom-tools.md, custom-commands.md, custom-ui.md, custom-rendering.md
 **Patterns:** state-management.md, system-prompt-modification.md, compaction-session-control.md
 **Infrastructure:** model-provider-management.md, remote-execution-overrides.md, packaging-distribution.md, mode-behavior.md
+**Spec:** `docs/extension-sdk/manifest-spec.md` — manifest format, tiers, validation
+**Testing:** `docs/extension-sdk/testing.md` — mock patterns, test conventions
+**SDK:** `docs/extension-sdk/` — the authoritative GSD-2 extension guide
 **Gotchas:** key-rules-gotchas.md
 </reference_index>
 
@@ -78,6 +81,7 @@ All domain knowledge in `references/`:
 
 <success_criteria>
 Extension is complete when:
+- `extension-manifest.json` exists with accurate `provides` listing all registered tools/commands/hooks/shortcuts
 - TypeScript compiles without errors (jiti handles this at runtime)
 - Extension loads on GSD startup or `/reload` without errors
 - Tools appear in the LLM's system prompt and are callable

package/dist/resources/skills/create-gsd-extension/references/custom-commands.md

@@ -19,7 +19,7 @@ pi.registerCommand("deploy", {
 Add tab-completion for command arguments:
 
 ```typescript
-import type { AutocompleteItem } from "@mariozechner/pi-tui";
+import type { AutocompleteItem } from "@gsd/pi-tui";
 
 pi.registerCommand("deploy", {
   description: "Deploy to an environment",