@bubblebrain-ai/bubble 0.0.21 → 0.0.23

package/dist/tools/agent-lifecycle.d.ts

@@ -1,6 +1,32 @@
-import type { ToolRegistryEntry } from "../types.js";
-export declare function createSpawnAgentTool(): ToolRegistryEntry;
+import type { AgentProfile } from "../agent/profiles.js";
+import type { ApprovalController } from "../approval/types.js";
+import type { ToolRegistryEntry, ToolResult } from "../types.js";
+export interface AgentLifecycleToolOptions {
+    /** Working directory used for profile discovery in tool descriptions. */
+    cwd?: string;
+    /** Trust gate for project-local .bubble/agents profiles (design §10.2). */
+    approval?: ApprovalController;
+}
+/**
+ * Session-scoped trust decisions for project profiles, keyed by file path +
+ * content hash so an edited file re-prompts (design §10.2). Shared across the
+ * lifecycle tools created by one factory call.
+ */
+declare class ProjectProfileTrust {
+    private readonly approval?;
+    private readonly approved;
+    constructor(approval?: ApprovalController | undefined);
+    /** Returns undefined when trusted, else a blocked ToolResult. */
+    ensureTrusted(profile: AgentProfile): Promise<ToolResult | undefined>;
+}
+export declare function createSpawnAgentTool(options?: AgentLifecycleToolOptions, sharedTrust?: ProjectProfileTrust): ToolRegistryEntry;
 export declare function createWaitAgentTool(): ToolRegistryEntry;
 export declare function createSendInputTool(): ToolRegistryEntry;
 export declare function createCloseAgentTool(): ToolRegistryEntry;
-export declare function createAgentLifecycleTools(): ToolRegistryEntry[];
+export declare function createListAgentsTool(): ToolRegistryEntry;
+/** Items bound for one agent_team call (design §1.2). */
+export declare const AGENT_TEAM_MIN_ITEMS = 2;
+export declare const AGENT_TEAM_MAX_ITEMS = 32;
+export declare function createAgentTeamTool(options?: AgentLifecycleToolOptions, sharedTrust?: ProjectProfileTrust): ToolRegistryEntry;
+export declare function createAgentLifecycleTools(options?: AgentLifecycleToolOptions): ToolRegistryEntry[];
+export {};

package/dist/tools/agent-lifecycle.js

@@ -1,21 +1,122 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
 import { formatSubagentRoute } from "../agent/subagent-route-format.js";
-export function createSpawnAgentTool() {
+/**
+ * Session-scoped trust decisions for project profiles, keyed by file path +
+ * content hash so an edited file re-prompts (design §10.2). Shared across the
+ * lifecycle tools created by one factory call.
+ */
+class ProjectProfileTrust {
+    approval;
+    approved = new Set();
+    constructor(approval) {
+        this.approval = approval;
+    }
+    /** Returns undefined when trusted, else a blocked ToolResult. */
+    async ensureTrusted(profile) {
+        if (profile.source !== "project")
+            return undefined;
+        const filePath = profile.filePath ?? "<unknown>";
+        let content;
+        try {
+            content = profile.filePath ? readFileSync(profile.filePath, "utf8") : profile.prompt;
+        }
+        catch {
+            content = profile.prompt;
+        }
+        const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        const key = `${filePath}:${contentHash}`;
+        if (this.approved.has(key))
+            return undefined;
+        if (!this.approval) {
+            return {
+                content: [
+                    `Blocked: subagent profile "${profile.name}" comes from project-local .bubble/agents and needs the user's approval,`,
+                    "but no approval flow is available in this session. Use a built-in or user-level profile instead.",
+                ].join("\n"),
+                isError: true,
+                status: "blocked",
+            };
+        }
+        const decision = await this.approval.request({
+            type: "agent_profile",
+            name: profile.name,
+            path: filePath,
+            contentHash,
+            promptPreview: profile.prompt.split("\n").slice(0, 6).join("\n").slice(0, 600),
+        });
+        if (decision.action === "approve") {
+            this.approved.add(key);
+            return undefined;
+        }
+        const feedback = decision.feedback?.trim();
+        return {
+            content: [
+                `Blocked: the user declined to trust project agent profile "${profile.name}".`,
+                feedback ? `User feedback: ${feedback}` : "Use a built-in or user-level profile instead.",
+            ].join("\n"),
+            isError: true,
+            status: "blocked",
+        };
+    }
+}
+const PROFILE_DESCRIPTION_TTL_MS = 5_000;
+/**
+ * Custom profile descriptions must reach the model or the whole custom-profile
+ * system is unreachable (design §10.1): the agent_type description is built
+ * from live profile discovery, refreshed with a short TTL so file edits are
+ * picked up on the next turn.
+ */
+function createProfileLister(cwd) {
+    let cachedAt = 0;
+    let cached = "";
+    return () => {
+        if (!cwd)
+            return "";
+        const now = Date.now();
+        if (now - cachedAt < PROFILE_DESCRIPTION_TTL_MS && cached)
+            return cached;
+        cachedAt = now;
+        try {
+            const { profiles } = discoverAgentProfiles(cwd, "both");
+            const lines = profiles
+                .filter((profile) => !profile.name.startsWith("builtin:"))
+                .map((profile) => {
+                const tag = profile.source === "project" ? " [project: requires user approval on first use]" : "";
+                return `- ${profile.name}${tag} — ${truncateText(profile.description, 120)}`;
+            });
+            cached = lines.length > 0 ? ` Available profiles:\n${lines.join("\n")}` : "";
+        }
+        catch {
+            cached = "";
+        }
+        return cached;
+    };
+}
+export function createSpawnAgentTool(options = {}, sharedTrust) {
+    const trust = sharedTrust ?? new ProjectProfileTrust(options.approval);
+    const listProfiles = createProfileLister(options.cwd);
+    const baseDescription = [
+        "Start a child subagent in the background and return its agent_id plus random nickname.",
+        "The child has an independent thread; call wait_agent later to collect its result.",
+        "Proactively delegate multi-file investigations whose intermediate steps would be noise in the main conversation.",
+        "Do the work yourself when it takes only a couple of tool calls or needs conversation context — unless the user explicitly asks for a subagent, in which case spawn one.",
+        "The child starts with zero context: write the task as a self-contained work order — state the goal, include known file paths or commands, and never make it rediscover knowledge you already hold.",
+        "After spawning, do not duplicate the same delegated work locally; either wait for the child or do clearly non-overlapping work.",
+        "A child may start as queued when concurrency slots are busy; it starts automatically, no action needed.",
+    ].join(" ");
     return {
         name: "spawn_agent",
         readOnly: true,
         effect: "read",
-        description: [
-            "Start a child subagent in the background and return its agent_id plus random nickname.",
-            "Use this for Codex-style delegation. The child has an independent thread; call wait_agent later to collect its result.",
-            "When the user asks to use a subagent, spawn first with a clear task instead of doing the delegated investigation yourself.",
-            "After spawning, do not duplicate the same delegated work locally; either wait for the child or do clearly non-overlapping work.",
-            "agent_type defaults to default. Built-in types include default, explorer, and worker.",
-        ].join(" "),
+        get description() {
+            return baseDescription + listProfiles();
+        },
         parameters: {
             type: "object",
             properties: {
-                agent_type: { type: "string", description: "Subagent profile or role name. Defaults to default." },
+                agent_type: { type: "string", description: "Subagent profile or role name. Defaults to default. Built-in types include default, explorer, and worker; see the tool description for custom profiles." },
                 agent: { type: "string", description: "Alias for agent_type." },
                 category: { type: "string", description: "Optional semantic category for model/thinking routing, such as quick, deep, explore, review, frontend, or writing." },
                 message: { type: "string", description: "Initial task for the subagent." },
@@ -24,11 +125,7 @@ export function createSpawnAgentTool() {
                 agentScope: {
                     type: "string",
                     enum: ["user", "project", "both"],
-                    description: "Which profile locations to load. Defaults to user profiles plus built-ins.",
-                },
-                allowProjectAgents: {
-                    type: "boolean",
-                    description: "Required to run profiles loaded from project-local .bubble/agents.",
+                    description: "Which profile locations to load. Defaults to built-ins plus user and project profiles; project profiles need the user's one-time approval.",
                 },
                 approval: {
                     type: "string",
@@ -47,12 +144,15 @@ export function createSpawnAgentTool() {
                 return { content: "Error: spawn_agent requires message or task.", isError: true };
             }
             const profileName = stringArg(args.agent_type) ?? stringArg(args.agent) ?? "default";
-            const resolved = resolveProfile(ctx.cwd, profileName, parseScope(args.agentScope), args.allowProjectAgents === true);
+            const resolved = resolveProfile(ctx.cwd, profileName, parseScope(args.agentScope));
             if ("error" in resolved)
                 return resolved.error;
-            if (resolved.profile.mode !== "readonly") {
-                return unsupportedProfile(resolved.profile);
-            }
+            const modeBlock = unsupportedProfile(resolved.profile);
+            if (modeBlock)
+                return modeBlock;
+            const trustBlock = await trust.ensureTrusted(resolved.profile);
+            if (trustBlock)
+                return trustBlock;
             try {
                 const snapshot = await ctx.agent.spawnSubAgent(message, ctx.cwd, {
                     profile: resolved.profile,
@@ -67,7 +167,7 @@ export function createSpawnAgentTool() {
                     `agent_id: ${snapshot.agentId}`,
                     `status: ${snapshot.status}`,
                     ...formatRouteLines(snapshot),
-                    `next: call wait_agent for ${snapshot.agentId} before reporting this subagent's current status or final result`,
+                    ...spawnNextSteps(snapshot),
                     "counting: this spawn result creates one unique subagent; later wait_agent results for the same agent_id are updates, not additional subagents",
                 ]);
             }
@@ -84,7 +184,7 @@ export function createWaitAgentTool() {
         effect: "read",
         description: [
             "Wait for one or more spawned subagents to reach a final status and return snapshots.",
-            "If the wait times out while children are still running, call wait_agent again with a longer timeout instead of redoing the same delegated work locally.",
+            "If the wait times out while children are still queued or running, call wait_agent again with a longer timeout instead of redoing the same delegated work locally.",
         ].join(" "),
         parameters: {
             type: "object",
@@ -119,7 +219,7 @@ export function createWaitAgentTool() {
                 if (snapshots.some((snapshot) => !isFinalSnapshotStatus(snapshot.status))) {
                     return formatLifecycleResult("wait_agent", snapshots, [
                         "wait_agent timed out before a delegated result was ready.",
-                        "The subagent is still running; call wait_agent again with a longer timeout instead of duplicating the same work locally.",
+                        ...waitTimeoutGuidance(snapshots),
                         "",
                         ...snapshots.flatMap((snapshot) => [...formatSnapshot(snapshot), ""]),
                     ]);
@@ -137,7 +237,7 @@ export function createSendInputTool() {
         name: "send_input",
         readOnly: true,
         effect: "read",
-        description: "Send a follow-up message to an existing subagent thread. If it is still running, pass interrupt:true to cancel and redirect it.",
+        description: "Send a follow-up message to an existing subagent thread. If it is still running, pass interrupt:true to cancel and redirect it. Restarting a finished child goes through the scheduler like any spawn.",
         parameters: {
             type: "object",
             properties: {
@@ -168,6 +268,7 @@ export function createSendInputTool() {
                     `Sent input to ${snapshot.nickname} (${snapshot.agentName})`,
                     `agent_id: ${snapshot.agentId}`,
                     `status: ${snapshot.status}`,
+                    ...(snapshot.status === "queued" ? [queuedStatusLine(snapshot)] : []),
                 ]);
             }
             catch (error) {
@@ -212,15 +313,196 @@ export function createCloseAgentTool() {
         },
     };
 }
-export function createAgentLifecycleTools() {
+export function createListAgentsTool() {
+    return {
+        name: "list_agents",
+        readOnly: true,
+        effect: "read",
+        description: "List this session's subagents with their current status. Use it to recall which children exist before spawning duplicates or narrating progress.",
+        parameters: {
+            type: "object",
+            properties: {
+                status_filter: {
+                    type: "array",
+                    description: "Only include these statuses (queued, running, completed, failed, blocked, cancelled, closed).",
+                    items: { type: "string" },
+                },
+                include_closed: { type: "boolean", description: "Include closed subagents. Defaults to false." },
+            },
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.listSubAgents) {
+                return toolRuntimeMissing("list_agents");
+            }
+            const filter = Array.isArray(args.status_filter)
+                ? new Set(args.status_filter.filter((item) => typeof item === "string"))
+                : undefined;
+            const includeClosed = args.include_closed === true;
+            const snapshots = ctx.agent.listSubAgents()
+                .filter((snapshot) => includeClosed || snapshot.status !== "closed")
+                .filter((snapshot) => !filter || filter.size === 0 || filter.has(snapshot.status));
+            if (snapshots.length === 0) {
+                return {
+                    content: "No subagents match. Spawn one with spawn_agent when delegation helps.",
+                    metadata: { kind: "subagent", mode: "lifecycle", subagents: [] },
+                };
+            }
+            const lines = [
+                `${snapshots.length} subagent${snapshots.length === 1 ? "" : "s"}:`,
+                ...snapshots.map((snapshot) => {
+                    const usage = snapshot.usage ? ` tokens=${snapshot.usage.totalTokens}` : "";
+                    const queued = snapshot.status === "queued" && snapshot.queuePosition !== undefined
+                        ? ` queue_position=${snapshot.queuePosition}`
+                        : "";
+                    return `- ${snapshot.nickname} (${formatSnapshotRole(snapshot)}) agent_id=${snapshot.agentId} status=${snapshot.status}${queued}${usage} task=${truncateText(snapshot.task, 80)}`;
+                }),
+            ];
+            return {
+                content: lines.join("\n"),
+                metadata: {
+                    kind: "subagent",
+                    mode: "lifecycle",
+                    subagents: snapshots.map(snapshotToMetadata),
+                },
+            };
+        },
+    };
+}
+/** Items bound for one agent_team call (design §1.2). */
+export const AGENT_TEAM_MIN_ITEMS = 2;
+export const AGENT_TEAM_MAX_ITEMS = 32;
+export function createAgentTeamTool(options = {}, sharedTrust) {
+    const trust = sharedTrust ?? new ProjectProfileTrust(options.approval);
+    return {
+        name: "agent_team",
+        readOnly: true,
+        effect: "read",
+        description: [
+            "Run the same task template over many items as parallel subagents (homogeneous map fan-out).",
+            "Proactively use this when a task naturally splits into the same read-only operation over several independent items.",
+            "Each item becomes one child with its own agent_id; the call blocks until every member reaches a final state and returns results in item order.",
+            "Failed members can be resumed individually with send_input afterwards.",
+            `Use ${AGENT_TEAM_MIN_ITEMS}-${AGENT_TEAM_MAX_ITEMS} items. agent_team must be the ONLY tool call in your response; run other tools or further teams after it returns.`,
+            "Scoping rule: split items so members never overlap or conflict with each other.",
+        ].join(" "),
+        parameters: {
+            type: "object",
+            properties: {
+                description: { type: "string", description: "Short (3-5 word) description of the team, shown in the UI." },
+                agent_type: { type: "string", description: "Subagent profile for every member. Defaults to default." },
+                category: { type: "string", description: "Optional semantic category for model/thinking routing." },
+                prompt_template: { type: "string", description: "Task template applied to each item. Must contain the literal placeholder {{item}}." },
+                items: {
+                    type: "array",
+                    description: `Items to fan out over (${AGENT_TEAM_MIN_ITEMS}-${AGENT_TEAM_MAX_ITEMS} unique strings); each becomes one subagent.`,
+                    items: { type: "string" },
+                },
+            },
+            required: ["description", "prompt_template", "items"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.runAgentTeam) {
+                return toolRuntimeMissing("agent_team");
+            }
+            const template = stringArg(args.prompt_template);
+            if (!template) {
+                return { content: "Error: agent_team requires prompt_template.", isError: true };
+            }
+            if (!template.includes("{{item}}")) {
+                return {
+                    content: "Error: prompt_template must contain the literal placeholder {{item}} — it is replaced with each item. Example: \"Review {{item}} for risks.\"",
+                    isError: true,
+                };
+            }
+            const rawItems = Array.isArray(args.items)
+                ? args.items.filter((item) => typeof item === "string" && !!item.trim()).map((item) => item.trim())
+                : [];
+            const items = [...new Set(rawItems)];
+            if (items.length < AGENT_TEAM_MIN_ITEMS) {
+                return {
+                    content: `Error: agent_team needs at least ${AGENT_TEAM_MIN_ITEMS} unique items after deduplication (got ${items.length}). For a single task use spawn_agent instead.`,
+                    isError: true,
+                };
+            }
+            if (items.length > AGENT_TEAM_MAX_ITEMS) {
+                return {
+                    content: `Error: agent_team accepts at most ${AGENT_TEAM_MAX_ITEMS} items (got ${items.length}). Split the work into sequential teams.`,
+                    isError: true,
+                };
+            }
+            const profileName = stringArg(args.agent_type) ?? "default";
+            const resolved = resolveProfile(ctx.cwd, profileName, "both");
+            if ("error" in resolved)
+                return resolved.error;
+            const modeBlock = unsupportedProfile(resolved.profile);
+            if (modeBlock)
+                return modeBlock;
+            const trustBlock = await trust.ensureTrusted(resolved.profile);
+            if (trustBlock)
+                return trustBlock;
+            try {
+                const snapshots = await ctx.agent.runAgentTeam(ctx.cwd, {
+                    profile: resolved.profile,
+                    category: stringArg(args.category),
+                    promptTemplate: template,
+                    items,
+                    parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
+                    emitUpdate: ctx.emitUpdate,
+                    abortSignal: ctx.abortSignal,
+                });
+                const counts = teamStatusCounts(snapshots);
+                const lines = [
+                    `agent_team "${stringArg(args.description) ?? "team"}": ${snapshots.length} members — ${counts}`,
+                    "Failed or cancelled members can be resumed individually with send_input (see per-member guidance below).",
+                    "",
+                    ...snapshots.flatMap((snapshot, index) => [
+                        `### item ${index + 1}: ${truncateText(items[index] ?? "", 100)}`,
+                        ...formatSnapshot(snapshot),
+                        "",
+                    ]),
+                ];
+                return {
+                    content: lines.join("\n").trim(),
+                    status: snapshots.every((snapshot) => snapshot.status === "completed")
+                        ? "success"
+                        : snapshots.some((snapshot) => snapshot.status === "completed")
+                            ? "partial"
+                            : "blocked",
+                    isError: snapshots.length > 0 && snapshots.every((snapshot) => snapshot.status !== "completed"),
+                    metadata: {
+                        kind: "subagent",
+                        mode: "team",
+                        subagents: snapshots.map(snapshotToMetadata),
+                    },
+                };
+            }
+            catch (error) {
+                return toolError("agent_team", error);
+            }
+        },
+    };
+}
+function teamStatusCounts(snapshots) {
+    const counts = new Map();
+    for (const snapshot of snapshots) {
+        counts.set(snapshot.status, (counts.get(snapshot.status) ?? 0) + 1);
+    }
+    return [...counts.entries()].map(([status, count]) => `${status} ${count}`).join(" / ");
+}
+export function createAgentLifecycleTools(options = {}) {
+    const trust = new ProjectProfileTrust(options.approval);
     return [
-        createSpawnAgentTool(),
+        createSpawnAgentTool(options, trust),
         createWaitAgentTool(),
         createSendInputTool(),
         createCloseAgentTool(),
+        createListAgentsTool(),
+        createAgentTeamTool(options, trust),
     ];
 }
-function resolveProfile(cwd, name, scope, allowProjectAgents) {
+function resolveProfile(cwd, name, scope) {
     const discovered = discoverAgentProfiles(cwd, scope);
     const profile = findAgentProfile(discovered.profiles, name);
     if (!profile) {
@@ -232,20 +514,38 @@ function resolveProfile(cwd, name, scope, allowProjectAgents) {
             },
         };
     }
-    if (profile.source === "project" && !allowProjectAgents) {
-        return {
-            error: {
-                content: [
-                    `Blocked: subagent profile "${profile.name}" was loaded from project-local .bubble/agents.`,
-                    "Pass allowProjectAgents: true only when you trust this repository's agent profile prompts.",
-                ].join("\n"),
-                isError: true,
-                status: "blocked",
-            },
-        };
-    }
     return { profile };
 }
+function spawnNextSteps(snapshot) {
+    if (snapshot.status === "queued" && snapshot.queuePosition !== undefined && snapshot.queuePosition > 0) {
+        return [
+            queuedStatusLine(snapshot),
+            "next: continue other non-overlapping work, then call wait_agent to collect the result",
+        ];
+    }
+    return [
+        `next: call wait_agent for ${snapshot.agentId} before reporting this subagent's current status or final result`,
+    ];
+}
+function queuedStatusLine(snapshot) {
+    const behind = snapshot.queuePosition !== undefined && snapshot.queuePosition > 1
+        ? ` behind ${snapshot.queuePosition - 1} child${snapshot.queuePosition - 1 === 1 ? "" : "ren"}`
+        : "";
+    return `queued: waiting for a concurrency slot${behind}; it starts automatically — no action needed`;
+}
+function waitTimeoutGuidance(snapshots) {
+    const lines = [];
+    const queued = snapshots.filter((snapshot) => snapshot.status === "queued");
+    const running = snapshots.filter((snapshot) => snapshot.status === "running");
+    if (queued.length > 0) {
+        lines.push(`${queued.length} child${queued.length === 1 ? " is" : "ren are"} queued for a concurrency slot and will start automatically.`);
+    }
+    if (running.length > 0) {
+        lines.push(`${running.length} child${running.length === 1 ? " is" : "ren are"} still running.`);
+    }
+    lines.push("Call wait_agent again with a longer timeout instead of duplicating the same work locally.");
+    return lines;
+}
 function formatLifecycleResult(toolName, snapshots, header) {
     const lines = header ?? [`${toolName}: ${snapshots.length} subagent${snapshots.length === 1 ? "" : "s"}`];
     if (!header)
@@ -267,7 +567,7 @@ function formatLifecycleResult(toolName, snapshots, header) {
     };
 }
 function lifecycleStatus(toolName, snapshots) {
-    if (toolName === "spawn_agent" || toolName === "send_input" || toolName === "close_agent") {
+    if (toolName === "spawn_agent" || toolName === "send_input" || toolName === "close_agent" || toolName === "list_agents") {
         return "success";
     }
     if (snapshots.some((snapshot) => !isFinalSnapshotStatus(snapshot.status))) {
@@ -294,20 +594,66 @@ function formatSnapshot(snapshot) {
     }
     lines.push(...formatRouteLines(snapshot));
     lines.push(`task: ${snapshot.task}`);
+    if (snapshot.status === "queued") {
+        lines.push(queuedStatusLine(snapshot));
+    }
     if (snapshot.summary) {
         lines.push("", "Summary:", snapshot.summary);
     }
     else if (snapshot.status === "completed") {
         lines.push("", "Summary: (no final text summary was produced)");
     }
+    if (snapshot.worktree && isFinalSnapshotStatus(snapshot.status)) {
+        if (snapshot.worktree.changed) {
+            lines.push("", `Worktree with changes: ${snapshot.worktree.path}`, "Review the diff there and apply / cherry-pick / discard; the parent working tree was never touched.", ...(snapshot.worktree.diffStat ? ["Diff stat:", snapshot.worktree.diffStat] : []));
+        }
+        else {
+            lines.push("", "Worktree: no changes were left behind (removed automatically).");
+        }
+    }
     if (snapshot.toolNotes.length > 0) {
         lines.push("", "Recent tool notes:", ...snapshot.toolNotes.slice(-8).map((note) => `- ${note}`));
     }
     if (snapshot.error) {
         lines.push("", `Error: ${snapshot.error}`);
     }
+    lines.push(...finalGuidanceLines(snapshot));
     return lines;
 }
+/**
+ * Per-reason guidance (design §3.1): a resume hint is rendered iff the
+ * runtime judged the run resumable. Wait timeouts are not final states and
+ * never reach this function with a finalReason.
+ */
+function finalGuidanceLines(snapshot) {
+    if (!isFinalSnapshotStatus(snapshot.status) || snapshot.status === "completed" || snapshot.status === "closed") {
+        return [];
+    }
+    switch (snapshot.finalReason) {
+        case "rate_limited_exhausted":
+            return [
+                "",
+                resumeLine(snapshot.agentId),
+                "note: the provider was rate limited; prefer resuming later or running fewer children at once",
+            ];
+        case "failed_transient":
+        case "cancelled_interrupt":
+        case "cancelled_user":
+        case "cancelled_parent_abort":
+            return ["", resumeLine(snapshot.agentId)];
+        case "cancelled_budget":
+            return ["", "budget exhausted — do not resume this child; integrate what it already reported and narrow the task if more is needed"];
+        case "blocked":
+            return ["", "blocked: re-spawn with an adjusted profile or approval setting — resuming as-is would hit the same block"];
+        case "failed_fatal":
+            return [];
+        default:
+            return snapshot.resumable ? ["", resumeLine(snapshot.agentId)] : [];
+    }
+}
+function resumeLine(agentId) {
+    return `resume: call send_input with agent_id ${agentId} to continue this child with its context intact`;
+}
 function formatSnapshotRole(snapshot) {
     return [snapshot.agentName, snapshot.category ? `/${snapshot.category}` : ""].join("") || "default";
 }
@@ -321,6 +667,8 @@ function snapshotToMetadata(snapshot) {
         agentName: snapshot.agentName,
         nickname: snapshot.nickname,
         status: snapshot.status === "closed" ? "cancelled" : snapshot.status,
+        finalReason: snapshot.finalReason,
+        resumable: snapshot.resumable,
         profileSource: snapshot.profileSource,
         category: snapshot.category,
         route: snapshot.route,
@@ -332,14 +680,16 @@ function snapshotToMetadata(snapshot) {
     };
 }
 function unsupportedProfile(profile) {
+    if (profile.mode === "readonly" || profile.mode === "write_worktree")
+        return undefined;
     return {
-        content: `Error: subagent profile "${profile.name}" uses mode "${profile.mode}", but this runtime only supports readonly lifecycle subagents.`,
+        content: `Error: subagent profile "${profile.name}" uses mode "${profile.mode}", which is not supported. Use "readonly" for investigation or "write_worktree" for isolated write work.`,
         isError: true,
         status: "blocked",
     };
 }
 function parseScope(value) {
-    return value === "project" || value === "both" ? value : "user";
+    return value === "project" || value === "user" ? value : "both";
 }
 function parseApproval(value) {
     return value === "fail" || value === "disabled" ? value : undefined;
@@ -359,6 +709,10 @@ function normalizeAgentIds(value, single) {
 function stringArg(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function truncateText(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 3)}...`;
+}
 function snapshotFallbackId() {
     return `spawn_${Date.now().toString(36)}`;
 }

package/dist/tools/child-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-child tool factory for write_worktree subagents (design doc §8).
+ *
+ * Parent tools close over the parent cwd at creation, so a write child needs
+ * fresh instances bound to its worktree — with their own FileStateTracker —
+ * plus a worktree-scoped approval policy: file operations are runtime-checked
+ * to stay under the worktree root (the tools' own workspace fence does this
+ * structurally), bash auto-approves inside the worktree when the command
+ * passes a deny-list of escaping operations, and everything else fails fast.
+ */
+import type { ApprovalController, ApprovalDecision, ApprovalRequest } from "../approval/types.js";
+import type { PermissionCheckResult } from "../permissions/types.js";
+import type { ToolRegistryEntry } from "../types.js";
+export declare function isPathInsideWorktree(worktreeRoot: string, candidate: string): boolean;
+/**
+ * Approval policy for a worktree child: containment is enforced by code
+ * (path checks, deny-list), never by prompt text. There is no interactive
+ * fallback — anything outside the policy fails fast (design §11).
+ */
+export declare class WorktreeApprovalController implements ApprovalController {
+    private readonly worktreeRoot;
+    constructor(worktreeRoot: string);
+    request(req: ApprovalRequest): Promise<ApprovalDecision>;
+    checkRules(): PermissionCheckResult;
+}
+/**
+ * Builds the write child's toolset bound to its worktree: fresh instances
+ * with their own FileStateTracker and the worktree approval policy. A
+ * profile's tools list can narrow the set but never widen it.
+ */
+export declare function createWorktreeChildTools(worktreeCwd: string, include?: string[]): ToolRegistryEntry[];