@yagni-app/code-staging 0.0.0 → 0.1.0-staging.1004.1

package/dist/extension/spool.js

@@ -0,0 +1,266 @@
+/**
+ * Durable write-spool for the judgment-capture tools (spec §4, R4 write half).
+ *
+ * `record_decision` and `record_engineering_context` are metered writes that
+ * must never be blindly retried (invariant §0.8) — but losing a captured
+ * decision because the laptop lost Wi-Fi is worse. The backend now dedups on
+ * an `idempotencyKey` (§2), so the safe shape is:
+ *
+ *  - every logical write carries a generated idempotencyKey,
+ *  - a transport failure or 5xx appends `{endpoint, body, idempotencyKey, ts}`
+ *    to `~/.yagni-code/spool/pending.ndjson` (dir 0700, file 0600,
+ *    torn-line-tolerant — the same self-healing NDJSON pattern as
+ *    pipeline/checkpoint.ts),
+ *  - the spool is flushed at session_start and after any successful write,
+ *    replaying with the SAME idempotencyKey (the server replays the stored
+ *    response, so a duplicate flush is harmless),
+ *  - entries older than 14 days are dropped with an honest notice (stale
+ *    judgment silently landing weeks later would be worse than losing it).
+ *
+ * Everything here is FAIL-SOFT: a spool problem must never break a tool call
+ * or session start. Eval mode never reaches this module (the capture tools are
+ * not registered there).
+ */
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+import { codeStateHome } from "./stateHome.js";
+/** Spooled entries older than this are dropped at flush (with a notice). */
+export const MAX_SPOOL_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * Test seam mirroring checkpoint.ts `_setCheckpointHomeForTest`: when set, the
+ * spool roots here instead of `~/.yagni-code`. Pass `null` to restore.
+ */
+let homeOverride = null;
+export function _setSpoolHomeForTest(dir) {
+    homeOverride = dir;
+}
+function spoolHome() {
+    return codeStateHome(homeOverride);
+}
+function spoolDir() {
+    return join(spoolHome(), "spool");
+}
+/** The on-disk pending file (exported so tests can inspect it directly). */
+export function spoolFile() {
+    return join(spoolDir(), "pending.ndjson");
+}
+/** Append one pending write. NEVER throws (fail-soft: memory loss beats a crash). */
+export function appendToSpool(entry) {
+    try {
+        mkdirSync(spoolDir(), { recursive: true, mode: 0o700 });
+        const file = spoolFile();
+        // Self-heal a torn previous write (crash mid-append): if the file ends
+        // mid-line, prefix a newline so OUR record lands on its own line instead of
+        // gluing onto the fragment and losing both (mirrors checkpoint.ts).
+        let prefix = "";
+        try {
+            const existing = readFileSync(file);
+            if (existing.length > 0 && existing[existing.length - 1] !== 0x0a)
+                prefix = "\n";
+        }
+        catch {
+            /* no file yet — nothing to heal */
+        }
+        appendFileSync(file, `${prefix}${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    }
+    catch {
+        /* fail-soft: a spool write must never break the tool call */
+    }
+}
+function isSpoolEntry(value) {
+    const e = value;
+    return (!!e &&
+        typeof e === "object" &&
+        typeof e.endpoint === "string" &&
+        e.endpoint.startsWith("/") &&
+        !!e.body &&
+        typeof e.body === "object" &&
+        typeof e.idempotencyKey === "string" &&
+        typeof e.ts === "number");
+}
+/** Load pending entries, dropping torn/garbage lines. Never throws. */
+export function loadSpool() {
+    try {
+        const raw = readFileSync(spoolFile(), "utf8");
+        const out = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (isSpoolEntry(obj))
+                    out.push(obj);
+            }
+            catch {
+                /* unparseable (torn final write) — drop this line, keep the rest */
+            }
+        }
+        return out;
+    }
+    catch {
+        return []; // missing/unreadable → nothing pending
+    }
+}
+/** Atomically rewrite the pending file with the surviving entries (0600). */
+function rewriteSpool(entries) {
+    try {
+        const file = spoolFile();
+        if (entries.length === 0) {
+            rmSync(file, { force: true });
+            return;
+        }
+        mkdirSync(spoolDir(), { recursive: true, mode: 0o700 });
+        const tmp = join(spoolDir(), `.pending-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`);
+        writeFileSync(tmp, entries.map((e) => JSON.stringify(e)).join("\n") + "\n", { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch {
+        /* fail-soft: worst case the next flush replays an already-deduped key */
+    }
+}
+const EMPTY_FLUSH = {
+    replayed: 0,
+    droppedExpired: 0,
+    droppedRejected: 0,
+    remaining: 0,
+    notices: [],
+};
+function plural(n) {
+    return n === 1 ? "" : "s";
+}
+let flushInFlight = null;
+/**
+ * Replay every pending write with its ORIGINAL idempotencyKey (server-side
+ * dedup makes a double replay a no-op). Serialized: concurrent flushes (a
+ * session_start racing a post-write flush) coalesce onto one pass.
+ *
+ * Per entry: expired (>14d) → dropped with a notice; 2xx → replayed; a
+ * permanent 4xx (not auth/rate) → dropped with a notice (the backend will
+ * never accept it); transport error, 5xx, 401/403/408/429 → kept, and the
+ * rest of the flush stops (the backend is unreachable or the token is bad —
+ * hammering the remaining entries would not help). Never throws.
+ */
+export function flushSpool(opts) {
+    if (!flushInFlight) {
+        flushInFlight = doFlush(opts)
+            .catch(() => EMPTY_FLUSH)
+            .finally(() => {
+            flushInFlight = null;
+        });
+    }
+    return flushInFlight;
+}
+/** Statuses that mean "try again later", not "the backend rejected this body". */
+const KEEP_STATUSES = new Set([401, 403, 408, 429]);
+async function doFlush(opts) {
+    const entries = loadSpool();
+    if (entries.length === 0)
+        return EMPTY_FLUSH;
+    const nowMs = (opts.now ?? Date.now)();
+    // Keys we have RESOLVED this pass (replayed OK, or permanently dropped). We do
+    // NOT rewrite from this stale snapshot — instead we re-read the current spool
+    // just before writing and drop only these resolved keys, so a write appended
+    // mid-flush (a tool that failed while we were replaying) is never clobbered.
+    const resolved = new Set();
+    let replayed = 0;
+    let droppedExpired = 0;
+    let droppedRejected = 0;
+    let stopped = false;
+    for (const entry of entries) {
+        if (nowMs - entry.ts > MAX_SPOOL_AGE_MS) {
+            droppedExpired += 1;
+            resolved.add(entry.idempotencyKey);
+            continue;
+        }
+        if (stopped)
+            continue;
+        try {
+            const res = await resilientFetch(`${opts.baseUrl}${entry.endpoint}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                // Replay verbatim; re-assert the key in case an old entry predates it.
+                body: JSON.stringify({ ...entry.body, idempotencyKey: entry.idempotencyKey }),
+            }, { fetchImpl: opts.fetchImpl, policy: METERED_POST_FETCH_POLICY });
+            if (res.ok) {
+                replayed += 1;
+                resolved.add(entry.idempotencyKey);
+            }
+            else if (res.status >= 500 || KEEP_STATUSES.has(res.status)) {
+                stopped = true;
+            }
+            else {
+                droppedRejected += 1;
+                resolved.add(entry.idempotencyKey);
+            }
+        }
+        catch {
+            stopped = true;
+        }
+    }
+    // Re-read + filter + rewrite are back-to-back synchronous calls with no await
+    // between them, so no append can interleave in that window (single-threaded).
+    // Everything not resolved this pass — kept entries AND any mid-flush append —
+    // survives. A re-appended duplicate of a replayed key is harmless (the server
+    // dedups on idempotencyKey; it just replays next pass).
+    const keep = loadSpool().filter((e) => !resolved.has(e.idempotencyKey));
+    rewriteSpool(keep);
+    const notices = [];
+    if (replayed > 0) {
+        notices.push(`Replayed ${replayed} locally spooled YAGNI record${plural(replayed)}.`);
+    }
+    if (droppedExpired > 0) {
+        notices.push(`Dropped ${droppedExpired} unsent YAGNI record${plural(droppedExpired)} older than 14 days from the local spool.`);
+    }
+    if (droppedRejected > 0) {
+        notices.push(`Discarded ${droppedRejected} spooled YAGNI record${plural(droppedRejected)} the backend rejected.`);
+    }
+    return { replayed, droppedExpired, droppedRejected, remaining: keep.length, notices };
+    // (keep.length reflects the post-rewrite spool, including any mid-flush append.)
+}
+/**
+ * POST one judgment write with its idempotencyKey; on transport failure or a
+ * 5xx, durably spool it for replay instead of losing it. A successful write
+ * also kicks a background flush (fail-soft, fire-and-forget) so earlier
+ * stranded entries drain as soon as the backend is healthy again.
+ */
+export async function sendOrSpool(opts, label, endpoint, body, idempotencyKey, signal) {
+    const posted = { ...body, idempotencyKey };
+    let res;
+    try {
+        res = await resilientFetch(`${opts.baseUrl}${endpoint}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+            },
+            body: JSON.stringify(posted),
+        }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        appendToSpool({ endpoint, body: posted, idempotencyKey, ts: (opts.now ?? Date.now)() });
+        return { kind: "spooled", reason };
+    }
+    if (res.ok) {
+        // Success proves the backend is reachable: drain anything stranded earlier.
+        void flushSpool(opts).catch(() => { });
+        let json = null;
+        try {
+            json = await res.json();
+        }
+        catch {
+            /* a 2xx with a non-JSON body still counts as recorded */
+        }
+        return { kind: "ok", json };
+    }
+    if (res.status >= 500) {
+        appendToSpool({ endpoint, body: posted, idempotencyKey, ts: (opts.now ?? Date.now)() });
+        return { kind: "spooled", reason: `the YAGNI backend returned HTTP ${res.status}` };
+    }
+    return { kind: "rejected", message: await friendlyFetchError(label, res) };
+}
+//# sourceMappingURL=spool.js.map

package/dist/extension/stateHome.d.ts

@@ -0,0 +1,2 @@
+export declare function codeStateHome(override: string | null, env?: NodeJS.ProcessEnv, userHome?: string): string;
+//# sourceMappingURL=stateHome.d.ts.map

package/dist/extension/stateHome.js

@@ -0,0 +1,6 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function codeStateHome(override, env = process.env, userHome = homedir()) {
+    return override ?? env.YAGNI_CODE_HOME ?? join(userHome, ".yagni-code");
+}
+//# sourceMappingURL=stateHome.js.map

package/dist/extension/subagents.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The general `subagent` tool — delegate a self-contained task to an agent
+ * with its own fresh context window, optionally in parallel.
+ *
+ * Reuses the /go pipeline's battle-tested child runner (`runStage`: NDJSON
+ * stream folding, output caps, abort escalation) through its `personaBody`
+ * seam, so a subagent is exactly a grounded pi child whose system prompt is
+ * the agent definition's body instead of a /go persona.
+ *
+ * Agent definitions are the Claude Code format — markdown with
+ * name/description/tools/model frontmatter — discovered from the repo's
+ * `.claude/agents/` and `.pi/agents/` plus the user's `~/.claude/agents/`
+ * (project beats user on a name collision). A built-in `general` agent is
+ * always available, so the tool works in a repo with no definitions at all.
+ * Claude model names map onto YAGNI tiers (opus→advanced, sonnet→standard,
+ * haiku→efficient); unknown models run on standard.
+ */
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { runStage } from "./pipeline/runner.js";
+import type { ModelTier, PipelineStage } from "./pipeline/types.js";
+export declare const SUBAGENT_TOOL_NAME = "subagent";
+export declare const GENERAL_AGENT_NAME = "general";
+export declare const MAX_PARALLEL_SUBAGENTS = 4;
+/**
+ * The default tool surface a subagent gets when its definition declares none:
+ * the full working set plus grounded answers, mirroring what a Claude Code
+ * subagent would inherit.
+ */
+export declare const DEFAULT_SUBAGENT_TOOLS: string[];
+export type SubagentSource = "project-claude" | "project-pi" | "user-claude" | "builtin";
+export interface SubagentDef {
+    name: string;
+    description: string;
+    tools?: string[];
+    model: ModelTier;
+    /** The agent's system prompt (the markdown body). */
+    body: string;
+    source: SubagentSource;
+}
+/** Claude Code model names → YAGNI tiers; YAGNI tiers pass through. */
+export declare function mapModelTier(model: string | undefined): ModelTier;
+/**
+ * Parse one Claude Code-format agent file. Returns null when the file has no
+ * description — the one field the tool cannot do without (the model picks
+ * agents by it).
+ */
+export declare function parseAgentMarkdown(content: string, fallbackName: string, source: SubagentSource): SubagentDef | null;
+export interface DiscoverDeps {
+    cwd: string;
+    homeDir?: string;
+}
+/**
+ * All available agents: built-in general, then user `~/.claude/agents`, then
+ * the repo's `.pi/agents` and `.claude/agents` — later wins on a name
+ * collision, so a project definition beats a user one beats the built-in.
+ */
+export declare function discoverSubagents(deps: DiscoverDeps): SubagentDef[];
+export declare function formatAgentList(agents: SubagentDef[]): string;
+/**
+ * A subagent invocation is a synthetic pipeline stage: the task rides in as
+ * `{ticket}` verbatim, and the agent's body replaces the /go persona through
+ * the runner's personaBody seam.
+ */
+export declare function buildSubagentStage(def: SubagentDef, task: string): {
+    stage: PipelineStage;
+    ctx: {
+        ticket: string;
+        grounded: boolean;
+    };
+};
+type SubagentParams = {
+    task?: string;
+    agent?: string;
+    tasks?: Array<{
+        task: string;
+        agent?: string;
+    }>;
+};
+export interface MakeSubagentToolDeps {
+    runStageImpl?: typeof runStage;
+    discover?: (deps: DiscoverDeps) => SubagentDef[];
+    homeDir?: string;
+}
+export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        task: Type.TOptional<Type.TString>;
+        agent: Type.TOptional<Type.TString>;
+        tasks: Type.TOptional<Type.TArray<Type.TObject<{
+            task: Type.TString;
+            agent: Type.TOptional<Type.TString>;
+        }>>>;
+    }>;
+    execute(_toolCallId: string, params: SubagentParams, signal?: AbortSignal, onUpdate?: (update: {
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: unknown;
+    }) => void, ctx?: ExtensionContext): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {};
+        isError: boolean;
+    } | {
+        isError?: boolean | undefined;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            tasks: {
+                agent: string;
+                task: string;
+                exitCode: number;
+                usage: import("./pipeline/types.js").StageUsage;
+                toolCalls: number;
+            }[];
+        };
+    }>;
+};
+export interface RegisterSubagentsDeps {
+    discover?: (deps: DiscoverDeps) => SubagentDef[];
+    homeDir?: string;
+}
+/** Wire the subagent tool and the /agents listing command. */
+export declare function registerSubagents(pi: ExtensionAPI, deps?: RegisterSubagentsDeps): void;
+export {};
+//# sourceMappingURL=subagents.d.ts.map

package/dist/extension/subagents.js

@@ -0,0 +1,281 @@
+/**
+ * The general `subagent` tool — delegate a self-contained task to an agent
+ * with its own fresh context window, optionally in parallel.
+ *
+ * Reuses the /go pipeline's battle-tested child runner (`runStage`: NDJSON
+ * stream folding, output caps, abort escalation) through its `personaBody`
+ * seam, so a subagent is exactly a grounded pi child whose system prompt is
+ * the agent definition's body instead of a /go persona.
+ *
+ * Agent definitions are the Claude Code format — markdown with
+ * name/description/tools/model frontmatter — discovered from the repo's
+ * `.claude/agents/` and `.pi/agents/` plus the user's `~/.claude/agents/`
+ * (project beats user on a name collision). A built-in `general` agent is
+ * always available, so the tool works in a repo with no definitions at all.
+ * Claude model names map onto YAGNI tiers (opus→advanced, sonnet→standard,
+ * haiku→efficient); unknown models run on standard.
+ */
+import * as fs from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { runStage } from "./pipeline/runner.js";
+export const SUBAGENT_TOOL_NAME = "subagent";
+export const GENERAL_AGENT_NAME = "general";
+export const MAX_PARALLEL_SUBAGENTS = 4;
+/**
+ * The default tool surface a subagent gets when its definition declares none:
+ * the full working set plus grounded answers, mirroring what a Claude Code
+ * subagent would inherit.
+ */
+export const DEFAULT_SUBAGENT_TOOLS = [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "ask_yagni",
+];
+const GENERAL_BODY = `You are a capable software-engineering subagent with a fresh context window. Complete the task you are given end to end, autonomously.
+
+You are grounded in how THIS company works: call ask_yagni before inferring a convention, an ownership rule, or anything organization-specific.
+
+Your final message is your report back to the driving agent, which has NOT seen what you read or did. Make it compressed and complete: what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
+const GENERAL_AGENT = {
+    name: GENERAL_AGENT_NAME,
+    description: "General-purpose agent for research, multi-file changes, and self-contained tasks.",
+    model: "standard",
+    body: GENERAL_BODY,
+    source: "builtin",
+};
+const TIER_VALUES = ["peak", "advanced", "standard", "efficient"];
+/** Claude Code model names → YAGNI tiers; YAGNI tiers pass through. */
+export function mapModelTier(model) {
+    if (!model)
+        return "standard";
+    const normalized = model.trim().toLowerCase();
+    if (TIER_VALUES.includes(normalized))
+        return normalized;
+    if (normalized.includes("opus"))
+        return "advanced";
+    if (normalized.includes("sonnet"))
+        return "standard";
+    if (normalized.includes("haiku"))
+        return "efficient";
+    return "standard";
+}
+/**
+ * Parse one Claude Code-format agent file. Returns null when the file has no
+ * description — the one field the tool cannot do without (the model picks
+ * agents by it).
+ */
+export function parseAgentMarkdown(content, fallbackName, source) {
+    const { frontmatter, body } = parseFrontmatter(content);
+    const description = frontmatter.description?.trim();
+    if (!description)
+        return null;
+    const tools = frontmatter.tools
+        ?.split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+    return {
+        name: (frontmatter.name?.trim() || fallbackName).toLowerCase(),
+        description,
+        tools: tools && tools.length > 0 ? tools : undefined,
+        model: mapModelTier(frontmatter.model),
+        body: body.trim() || GENERAL_BODY,
+        source,
+    };
+}
+function loadAgentsFromDir(dir, source) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const agents = [];
+    for (const entry of entries) {
+        if (!entry.name.endsWith(".md"))
+            continue;
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        try {
+            const content = fs.readFileSync(join(dir, entry.name), "utf8");
+            const def = parseAgentMarkdown(content, entry.name.replace(/\.md$/, ""), source);
+            if (def)
+                agents.push(def);
+        }
+        catch {
+            continue;
+        }
+    }
+    return agents;
+}
+/**
+ * All available agents: built-in general, then user `~/.claude/agents`, then
+ * the repo's `.pi/agents` and `.claude/agents` — later wins on a name
+ * collision, so a project definition beats a user one beats the built-in.
+ */
+export function discoverSubagents(deps) {
+    const home = deps.homeDir ?? homedir();
+    const layers = [
+        [GENERAL_AGENT],
+        loadAgentsFromDir(join(home, ".claude", "agents"), "user-claude"),
+        loadAgentsFromDir(join(deps.cwd, ".pi", "agents"), "project-pi"),
+        loadAgentsFromDir(join(deps.cwd, ".claude", "agents"), "project-claude"),
+    ];
+    const byName = new Map();
+    for (const layer of layers) {
+        for (const agent of layer)
+            byName.set(agent.name, agent);
+    }
+    return [...byName.values()];
+}
+const SOURCE_LABEL = {
+    builtin: "built-in",
+    "user-claude": "~/.claude/agents",
+    "project-pi": ".pi/agents",
+    "project-claude": ".claude/agents",
+};
+export function formatAgentList(agents) {
+    return agents
+        .map((a) => `${a.name} (${SOURCE_LABEL[a.source]}): ${a.description}`)
+        .join("\n");
+}
+/**
+ * A subagent invocation is a synthetic pipeline stage: the task rides in as
+ * `{ticket}` verbatim, and the agent's body replaces the /go persona through
+ * the runner's personaBody seam.
+ */
+export function buildSubagentStage(def, task) {
+    return {
+        stage: {
+            id: "implement",
+            agent: def.name,
+            model: def.model,
+            tools: def.tools ?? DEFAULT_SUBAGENT_TOOLS,
+            taskTemplate: "{ticket}",
+        },
+        ctx: { ticket: task, grounded: true },
+    };
+}
+const parameters = Type.Object({
+    task: Type.Optional(Type.String({
+        description: "The self-contained task. Include everything needed: the subagent shares none of your context.",
+    })),
+    agent: Type.Optional(Type.String({ description: "Agent name (see /agents). Defaults to general." })),
+    tasks: Type.Optional(Type.Array(Type.Object({
+        task: Type.String(),
+        agent: Type.Optional(Type.String()),
+    }), {
+        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}). Use INSTEAD of task.`,
+    })),
+});
+export function makeSubagentTool(deps = {}) {
+    const run = deps.runStageImpl ?? runStage;
+    const discover = deps.discover ?? discoverSubagents;
+    return {
+        name: SUBAGENT_TOOL_NAME,
+        label: "Subagent",
+        description: "Delegate a self-contained task to a subagent with its own fresh context window, and get back " +
+            "a compressed report. Use it for context-heavy exploration you don't need blow-by-blow, or to " +
+            "run independent tasks in parallel via `tasks`. The subagent shares NONE of your conversation: " +
+            "spell out the task completely. Agents come from this repo's .claude/agents and .pi/agents " +
+            "(list them with /agents); omit `agent` for the general-purpose one.",
+        promptSnippet: "subagent: delegate a self-contained task (or parallel tasks) to a fresh-context agent; returns its report.",
+        parameters,
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const fail = (text) => ({
+                content: [{ type: "text", text }],
+                details: {},
+                isError: true,
+            });
+            const requested = params.tasks && params.tasks.length > 0
+                ? params.tasks
+                : params.task
+                    ? [{ task: params.task, agent: params.agent }]
+                    : [];
+            if (requested.length === 0) {
+                return fail("Error: pass `task` (or a `tasks` array) describing what to do.");
+            }
+            if (requested.length > MAX_PARALLEL_SUBAGENTS) {
+                return fail(`Error: at most ${MAX_PARALLEL_SUBAGENTS} parallel tasks per call.`);
+            }
+            const cwd = ctx?.cwd ?? process.cwd();
+            const agents = discover({ cwd, homeDir: deps.homeDir });
+            const resolved = [];
+            for (const req of requested) {
+                const name = (req.agent ?? GENERAL_AGENT_NAME).toLowerCase();
+                const def = agents.find((a) => a.name === name);
+                if (!def) {
+                    return fail(`Error: unknown agent "${name}". Available agents:\n${formatAgentList(agents)}`);
+                }
+                resolved.push({ def, task: req.task });
+            }
+            onUpdate?.({
+                content: [
+                    {
+                        type: "text",
+                        text: resolved.length === 1
+                            ? `Running ${resolved[0].def.name} subagent…`
+                            : `Running ${resolved.length} subagents in parallel…`,
+                    },
+                ],
+                details: {},
+            });
+            const outcomes = await Promise.all(resolved.map(async ({ def, task }) => {
+                const { stage, ctx: stageCtx } = buildSubagentStage(def, task);
+                const result = await run(stage, stageCtx, {
+                    cwd,
+                    signal,
+                    personaBody: () => def.body,
+                });
+                return { agent: def.name, task, result };
+            }));
+            const allFailed = outcomes.every((o) => o.result.exitCode !== 0);
+            const sections = outcomes.map((o) => {
+                const output = o.result.finalOutput.trim();
+                const failedNote = o.result.exitCode !== 0
+                    ? `\n\n(subagent failed, exit ${o.result.exitCode}${o.result.stderr.trim() ? `: ${o.result.stderr.trim().slice(-500)}` : ""})`
+                    : "";
+                const bodyText = output || (o.result.exitCode === 0 ? "(no output)" : "");
+                return outcomes.length === 1
+                    ? `${bodyText}${failedNote}`
+                    : `## ${o.agent}: ${o.task}\n\n${bodyText}${failedNote}`;
+            });
+            return {
+                content: [{ type: "text", text: sections.join("\n\n") }],
+                details: {
+                    tasks: outcomes.map((o) => ({
+                        agent: o.agent,
+                        task: o.task,
+                        exitCode: o.result.exitCode,
+                        usage: o.result.usage,
+                        toolCalls: o.result.toolCalls,
+                    })),
+                },
+                ...(allFailed ? { isError: true } : {}),
+            };
+        },
+    };
+}
+/** Wire the subagent tool and the /agents listing command. */
+export function registerSubagents(pi, deps = {}) {
+    const discover = deps.discover ?? discoverSubagents;
+    pi.registerTool(makeSubagentTool(deps));
+    pi.registerCommand("agents", {
+        description: "List the subagents available in this repo (.claude/agents, .pi/agents).",
+        handler: async (_args, ctx) => {
+            if (!ctx.hasUI)
+                return;
+            const agents = discover({ cwd: ctx.cwd ?? process.cwd(), homeDir: deps.homeDir });
+            ctx.ui.notify(`Available subagents:\n${formatAgentList(agents)}`, "info");
+        },
+    });
+}
+//# sourceMappingURL=subagents.js.map