agent-from-zero 0.27.0 → 0.28.0

package/dist/loop.js

@@ -5,12 +5,17 @@ import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
 import { previewChange } from "./diff.js"; // show the diff before a write so approval is informed
 import { estimateHistoryTokens, compactHistory, COMPACT_AT, MAX_COMPACTIONS_PER_QUERY, MAX_COMPACT_FAILURES } from "./context.js"; // context management
-import { SUB_AGENT_PROMPT } from "./prompt.js"; // the sub-agent's own constitution
+import { SUB_AGENT_PROMPT, TEAMMATE_PROMPT } from "./prompt.js"; // the sub-agent + teammate constitutions
+import { LEAD, MAX_TEAMMATES, sendMessage, sendProtocol, readInbox, inboxCount, registerTeammate, finishTeammate, teammateExists, teammateCount, createRequest, resolveResponse, setTeammateState, anyTeammateBusy, runningTeammates, markShutdown, shutdownRequestId, resetTeam } from "./team.js"; // agent teams (Day 38) + team protocols (Day 39): mailboxes, registry, request/response contracts
+import { createTask, claimTask, completeTask, claimNextAvailable, boardSummary, resetBoard } from "./board.js"; // the shared task board (Day 40): autonomous work claiming
 import { emit } from "./telemetry.js"; // local-only event log (no-op unless the CLI armed it)
 import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / PostToolUse / Stop)
 import { recordUsage } from "./cost.js"; // meter token usage from the stream
 import { mark, thinkingWord, spinnerText } from "./ui.js"; // centralized terminal styling (markers, spinner)
 import { printToolSummary } from "./tui.js"; // collapsible tool output
+import { MarkdownStream } from "./markdown.js"; // render the streamed answer as terminal markdown
+import { todoNag, getTodos, renderTodos } from "./todos.js"; // the agent's plan: show it on screen + nag when it goes stale
+import { pendingNotifications } from "./background.js"; // background tasks (Day 37): surface finished jobs as a turn
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
 export const MAX_RATE_LIMIT_RETRIES = 3; // 429s get their own, much smaller budget
 export const MAX_CONSECUTIVE_FAILURES = 3; // the circuit breaker
@@ -87,6 +92,187 @@ If the user cancels, you'll be told — then proceed with your best judgment or
         },
     },
 };
+// The spawn_teammate tool (Day 38): the Lead's handle on a PERSISTENT worker.
+// Unlike `task` (one-shot, returns once), a teammate runs concurrently and keeps
+// talking — it messages the lead as it works and is reachable via send_message.
+// Defined here (not tools.ts) because running it needs the loop itself.
+const spawnTeammateTool = {
+    type: "function",
+    function: {
+        name: "spawn_teammate",
+        description: `Spawn a PERSISTENT teammate that works in parallel with you and the rest of the team. Use this for a large task with distinct streams of work that need to coordinate as they go (e.g. one teammate on the API, one on the database) — not for a quick lookup (use task) or a single linear job (do it yourself).
+The teammate runs concurrently in a fresh context with read/write/search/bash tools. It can message you and other teammates at any time, and you'll receive its result when it finishes. You can run a few at once.
+Give it a short unique name and a one-line role, and a complete self-contained task (it knows nothing about this conversation). After spawning, keep coordinating: you'll get its messages in your inbox; reply with send_message.`,
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "A short, unique name for the teammate (e.g. 'api', 'db', 'tests')" },
+                role: { type: "string", description: "One line describing its specialty/responsibility" },
+                task: { type: "string", description: "The complete, self-contained task for the teammate to carry out" },
+            },
+            required: ["name", "role", "task"],
+        },
+    },
+};
+// The send_message tool (Day 38): drop a message in another agent's mailbox.
+// Available to the Lead AND to teammates — it is how a team coordinates.
+const sendMessageTool = {
+    type: "function",
+    function: {
+        name: "send_message",
+        description: `Send a message to another agent on the team (a teammate by name, or "lead"). The message lands in their inbox and they see it on their next round. Use it to share findings, hand off work, ask a specific question, or report progress to the lead. Returns once delivered; it does NOT wait for a reply — keep working, and their response will arrive in your inbox.`,
+        parameters: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: 'Recipient agent name, or "lead" for the coordinator' },
+                content: { type: "string", description: "The message text" },
+            },
+            required: ["to", "content"],
+        },
+    },
+};
+// The team protocol tools (Day 39). Both sides of each contract are a tool:
+// the lead asks for shutdown / reviews a plan; a teammate submits a plan. Each
+// carries a request_id so the answer can be correlated to the ask.
+const requestShutdownTool = {
+    type: "function",
+    function: {
+        name: "request_shutdown",
+        description: `Ask a teammate to shut down GRACEFULLY. It finishes what it's mid-way through, confirms, and exits cleanly — far better than abandoning it (which can leave a half-written file). Use it when a teammate's part is done, or when you're wrapping up the whole task. You'll get a shutdown confirmation back. (When you finish, any teammates still up are shut down for you automatically.)`,
+        parameters: {
+            type: "object",
+            properties: {
+                teammate: { type: "string", description: "Name of the teammate to shut down" },
+                reason: { type: "string", description: "Optional short reason, shown to the teammate" },
+            },
+            required: ["teammate"],
+        },
+    },
+};
+const requestPlanTool = {
+    type: "function",
+    function: {
+        name: "request_plan",
+        description: `Tell a teammate to submit a PLAN (via submit_plan) and wait for your approval BEFORE it carries out a risky or far-reaching change (e.g. an auth refactor, a schema migration). Use this when you want to pre-authorize high-stakes work instead of reviewing the damage after. The teammate will send you a plan_approval_request; approve or reject it with review_plan.`,
+        parameters: {
+            type: "object",
+            properties: {
+                teammate: { type: "string", description: "Name of the teammate" },
+                task: { type: "string", description: "The risky work it must plan before doing" },
+            },
+            required: ["teammate", "task"],
+        },
+    },
+};
+const reviewPlanTool = {
+    type: "function",
+    function: {
+        name: "review_plan",
+        description: `Approve or reject a plan a teammate submitted for approval. You'll have received a plan_approval_request with a request_id — pass that id and your decision. On approval the teammate proceeds; on rejection it revises and may submit again. Always include a brief reason on a rejection so it can fix the plan.`,
+        parameters: {
+            type: "object",
+            properties: {
+                request_id: { type: "string", description: "The request_id from the plan_approval_request" },
+                decision: { type: "string", enum: ["approve", "reject"], description: "approve | reject" },
+                reason: { type: "string", description: "Short reason (required-in-spirit on a rejection)" },
+            },
+            required: ["request_id", "decision"],
+        },
+    },
+};
+const submitPlanTool = {
+    type: "function",
+    function: {
+        name: "submit_plan",
+        description: `Submit a PLAN to the lead and wait for approval BEFORE carrying out a risky or far-reaching change. Use it whenever you're about to do something high-stakes (refactor auth, migrate a schema, delete/rewrite many files) — propose first, act after. After you call this, STOP and wait: the lead's approval (or rejection) will arrive in your inbox. Do not start the work until it's approved.`,
+        parameters: {
+            type: "object",
+            properties: {
+                plan: { type: "string", description: "The concise, ordered plan you intend to carry out" },
+            },
+            required: ["plan"],
+        },
+    },
+};
+// The task board tools (Day 40). The board is how teammates find work without
+// the lead handing it out: create tasks, see the board, claim a ready one, mark
+// it done. claim/complete are loop-level (not registry tools) because they need
+// to know WHO is calling — the claimer's identity is the agent name, which only
+// the loop has.
+const createTaskTool = {
+    type: "function",
+    function: {
+        name: "create_task",
+        description: `Add a task to the shared board for a teammate to pick up. Use it to break a big job into independent, claimable pieces. A task can declare blockedBy (ids of tasks that must finish first), so you can lay out a dependency order (e.g. schema → routes → tests) and teammates will respect it. Returns the new task id.`,
+        parameters: {
+            type: "object",
+            properties: {
+                subject: { type: "string", description: "Short one-line title of the task" },
+                description: { type: "string", description: "The full, self-contained instruction for whoever claims it" },
+                blockedBy: { type: "array", items: { type: "string" }, description: "Tasks that must be completed before this one can start — by task id or by their subject (optional)" },
+            },
+            required: ["subject"],
+        },
+    },
+};
+const listTasksTool = {
+    type: "function",
+    function: {
+        name: "list_tasks",
+        description: `Show the shared task board: every task with its status (pending / in_progress / completed), owner, and dependencies. Use it to see what's left, what's claimed, and what's ready to start.`,
+        parameters: { type: "object", properties: {}, required: [] },
+    },
+};
+const claimTaskTool = {
+    type: "function",
+    function: {
+        name: "claim_task",
+        description: `Claim a pending, unblocked task from the board as your own — it becomes in_progress and owned by you. Claim BEFORE you start working it. If the claim fails (someone beat you to it, or it's still blocked), pick another task or wait. When you're done, call complete_task. (You usually don't need to call this by hand: while idle you are offered ready work automatically.)`,
+        parameters: {
+            type: "object",
+            properties: { task_id: { type: "string", description: "The id of the task to claim" } },
+            required: ["task_id"],
+        },
+    },
+};
+const completeTaskTool = {
+    type: "function",
+    function: {
+        name: "complete_task",
+        description: `Mark a task you own as completed. This may unblock downstream tasks (you'll be told which). Only call it once the work is actually done and verified.`,
+        parameters: {
+            type: "object",
+            properties: { task_id: { type: "string", description: "The id of the task to complete" } },
+            required: ["task_id"],
+        },
+    },
+};
+// Which tool manuals does THIS agent get? One place so the three agent kinds
+// stay clearly distinct:
+//   - Lead / top-level: everything, plus task, ask_user, and the team tools
+//     (spawn + message + the protocol tools it drives: shutdown / plan review).
+//   - Teammate: a focused worker set + send_message + submit_plan; NO task, NO
+//     spawn_teammate (nested spawning is forbidden), NO ask_user (can't reach
+//     the human), and none of the planning/background extras.
+//   - Plain sub-agent (task): all built-ins except todo_write (unchanged).
+const TEAMMATE_TOOLS = new Set(["read_file", "write_file", "edit_file", "search", "run_bash"]); // the teammate's focused kit
+function toolsFor(opts) {
+    const builtins = toolDefinitions();
+    if (opts.teammate) {
+        // A teammate works the board: it can add tasks it discovers, see the board,
+        // claim ready work, and complete what it owns.
+        const kit = builtins.filter((t) => t.type === "function" && TEAMMATE_TOOLS.has(t.function.name));
+        return [...kit, sendMessageTool, submitPlanTool, createTaskTool, listTasksTool, claimTaskTool, completeTaskTool];
+    }
+    if (opts.subAgent) {
+        // Sub-agents don't get todo_write: the plan is the top-level agent's, and a
+        // sub-agent writing to the shared list would clobber it mid-task.
+        return builtins.filter((t) => !(t.type === "function" && t.function.name === "todo_write"));
+    }
+    // The Lead can do everything: orchestration, the protocols, and authoring +
+    // watching the board (it lays out tasks; teammates pull from it).
+    return [...builtins, taskTool, askUserTool, spawnTeammateTool, sendMessageTool, requestShutdownTool, requestPlanTool, reviewPlanTool, createTaskTool, listTasksTool];
+}
 // Run one sub-agent: a fresh conversation, same tools minus task, same
 // permission gate, and the parent's file read-state protected by a snapshot.
 async function runSubAgent(description, opts) {
@@ -172,10 +358,14 @@ opts) {
         // Nested spawning means orphan processes and debugging hell.
         // include_usage adds a final chunk carrying token counts — that is how we
         // meter cost without a second (counting) request.
-        { model: opts.model, messages, tools: opts.subAgent ? toolDefinitions() : [...toolDefinitions(), taskTool, askUserTool], stream: true, stream_options: { include_usage: true } }, { signal });
+        // The tool manual depends on the agent kind (Lead / teammate / sub-agent)
+        // — see toolsFor(). This is also where nested spawning is prevented: a
+        // teammate's manual simply omits spawn_teammate and task.
+        { model: opts.model, messages, tools: toolsFor(opts), stream: true, stream_options: { include_usage: true } }, { signal });
         let content = ""; // accumulated answer text
         let printedPrefix = false; // have we printed the answer prefix yet?
         let printedThinking = false; // have we started printing the reasoning trace yet?
+        let md = null; // renders the streamed answer as markdown, block by block
         const calls = []; // tool calls under assembly, indexed by delta.index
         for await (const chunk of stream) {
             lastEvent = Date.now(); // feed the watchdog
@@ -212,10 +402,14 @@ opts) {
                     if (printedThinking && !printedPrefix)
                         process.stdout.write("\n"); // end the thinking block before the answer
                     if (!printedPrefix) {
-                        process.stdout.write("\n" + mark.answer); // prefix once (⏺), then stream raw
+                        // Stream the answer through the markdown renderer: it buffers a block
+                        // (paragraph / heading / list / table) and prints it formatted the
+                        // moment that block completes — still live, but no raw `##`/`|---|`.
+                        // The ⏺ marker leads the first line; wrapped lines align under it.
+                        md = new MarkdownStream((s) => process.stdout.write(s), { firstPrefix: "\n" + mark.answer, indent: "  " });
                         printedPrefix = true;
                     }
-                    process.stdout.write(delta.content); // print the token immediately — this IS the streaming UX
+                    md.push(delta.content); // hand the token to the renderer (it decides when to paint)
                 }
                 content += delta.content; // always keep it for the history (the answer only, never the reasoning)
             }
@@ -231,6 +425,8 @@ opts) {
                     slot.args += tc.function.arguments; // arguments stream in fragments — concatenate
             }
         }
+        if (md)
+            md.end(); // flush the final (un-terminated) block through the renderer
         if (printedPrefix)
             process.stdout.write("\n"); // end the streamed line cleanly
         return { content, toolCalls: calls.filter(Boolean) }; // sparse array → dense
@@ -246,7 +442,7 @@ opts) {
 // calls (allow/deny only, never "ask") are safe to run via this from inside a
 // Promise.all batch; calls that can prompt must be awaited one at a time.
 async function runOneCall(call, opts) {
-    const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
+    const indent = opts.teammate ? chalk.magenta(`  ⎿ [${opts.teammate.name}] `) : opts.subAgent ? chalk.blue("  ⎿ ") : ""; // teammate activity is tagged by name; plain sub-agent is nested in blue
     if (!opts.quiet) {
         // Compact one-line summary — long args are hidden behind Tab.
         const summary = indent + mark.tool(call.name, call.args.length > 60 ? call.args.slice(0, 57) + "..." : call.args);
@@ -300,6 +496,11 @@ async function runOneCall(call, opts) {
     else {
         content = await runWithHooks(call, opts); // allow — run it (PreToolUse can still block)
     }
+    // todo_write's whole point is the VISIBLE plan: the model got a one-line tally,
+    // the human gets the rendered checklist (quiet runs — eval/sub-agents — stay silent).
+    if (call.name === "todo_write" && !opts.quiet && !content.startsWith("[error]")) {
+        console.log(renderTodos(getTodos()));
+    }
     return { id: call.id, content }; // paired by id for the API
 }
 // Run an approved tool call, surrounded by the user's lifecycle hooks.
@@ -349,6 +550,29 @@ async function execute(call, opts) {
     // tool registry. It presents a form and feeds the selections back to the model.
     if (call.name === "ask_user")
         return runAskUser(call, opts);
+    // The team tools (Day 38/39) are loop-level like task: they need the loop and
+    // the shared mailbox + protocol state, not the tool registry.
+    if (call.name === "send_message")
+        return runSendMessage(call, opts);
+    if (call.name === "spawn_teammate")
+        return runSpawnTeammate(call, opts);
+    if (call.name === "request_shutdown")
+        return runRequestShutdown(call, opts);
+    if (call.name === "request_plan")
+        return runRequestPlan(call, opts);
+    if (call.name === "review_plan")
+        return runReviewPlan(call, opts);
+    if (call.name === "submit_plan")
+        return runSubmitPlan(call, opts);
+    // The task board tools (Day 40) — claim/complete need the caller's identity.
+    if (call.name === "create_task")
+        return runCreateTask(call, opts);
+    if (call.name === "list_tasks")
+        return runListTasks(call, opts);
+    if (call.name === "claim_task")
+        return runClaimTask(call, opts);
+    if (call.name === "complete_task")
+        return runCompleteTask(call, opts);
     if (call.name !== "task")
         return dispatch(call.name, call.args, opts.signal); // ordinary tools go through the registry (signal lets Ctrl+C kill run_bash)
     if (opts.subAgent)
@@ -364,6 +588,282 @@ async function execute(call, opts) {
         return "[error] task requires a non-empty description argument.";
     return runSubAgent(description, opts); // spawn the worker
 }
+// The sender's mailbox name: a teammate sends as itself, everyone else as "lead".
+const senderName = (opts) => opts.teammate?.name ?? LEAD;
+// send_message: deliver one message to another agent's inbox. Available to the
+// Lead and to teammates. Pure coordination — it never blocks on a reply.
+async function runSendMessage(call, opts) {
+    let to = "", content = "";
+    try {
+        const a = JSON.parse(call.args);
+        to = (a.to ?? "").trim();
+        content = a.content ?? "";
+    }
+    catch {
+        /* fall through */
+    }
+    if (!to || !content.trim())
+        return "[error] send_message needs a non-empty 'to' and 'content'.";
+    const from = senderName(opts);
+    if (to === from)
+        return "[error] You cannot message yourself.";
+    // A teammate can only reach the lead or another teammate; the lead can reach
+    // any teammate. We don't hard-check the recipient exists (it may be spawning) —
+    // an undeliverable message just sits in a file no one reads, which is harmless.
+    sendMessage(from, to, content);
+    return `Message delivered to ${to}'s inbox.`;
+}
+// request_shutdown (lead → teammate): open a shutdown contract. We stamp the
+// teammate with the request_id (it replies with that id and exits) AND send the
+// request message so it shows up in the teammate's inbox and conversation.
+async function runRequestShutdown(call, opts) {
+    if (opts.teammate || opts.subAgent)
+        return "[error] Only the lead can request a shutdown.";
+    let teammate = "", reason = "";
+    try {
+        const a = JSON.parse(call.args);
+        teammate = (a.teammate ?? "").trim();
+        reason = a.reason ?? "";
+    }
+    catch { /* fall through */ }
+    if (!teammate)
+        return "[error] request_shutdown needs a 'teammate' name.";
+    if (!teammateExists(teammate))
+        return `[error] No teammate named "${teammate}".`;
+    if (shutdownRequestId(teammate))
+        return `Shutdown already requested for "${teammate}" — waiting for it to confirm and exit.`;
+    const requestId = createRequest("shutdown", LEAD, teammate, reason || "task complete");
+    markShutdown(teammate, requestId);
+    sendProtocol(LEAD, teammate, "shutdown_request", requestId, reason || "Your part is done — please wrap up and exit.");
+    return `Requested shutdown of "${teammate}" (${requestId}). It will finish up, confirm, and exit; you'll get the confirmation in your inbox.`;
+}
+// request_plan (lead → teammate): ask the teammate to plan-before-acting. This
+// is a directive message; the teammate answers it by calling submit_plan, which
+// opens the actual plan_approval contract.
+async function runRequestPlan(call, opts) {
+    if (opts.teammate || opts.subAgent)
+        return "[error] Only the lead can request a plan.";
+    let teammate = "", task = "";
+    try {
+        const a = JSON.parse(call.args);
+        teammate = (a.teammate ?? "").trim();
+        task = a.task ?? "";
+    }
+    catch { /* fall through */ }
+    if (!teammate || !task.trim())
+        return "[error] request_plan needs a 'teammate' and a 'task'.";
+    if (!teammateExists(teammate))
+        return `[error] No teammate named "${teammate}".`;
+    sendMessage(LEAD, teammate, `Before doing this, call submit_plan with your plan and WAIT for my approval — do not start until approved:\n${task}`);
+    return `Asked "${teammate}" to submit a plan before doing: ${task.slice(0, 80)}. Approve/reject it with review_plan when it arrives.`;
+}
+// review_plan (lead): the answer half of the plan_approval contract. Correlate
+// to the request via match_response (resolveResponse), then send the decision
+// back to the teammate that submitted it.
+async function runReviewPlan(call, opts) {
+    if (opts.teammate || opts.subAgent)
+        return "[error] Only the lead can review a plan.";
+    let requestId = "", decision = "", reason = "";
+    try {
+        const a = JSON.parse(call.args);
+        requestId = (a.request_id ?? "").trim();
+        decision = (a.decision ?? "").trim();
+        reason = a.reason ?? "";
+    }
+    catch { /* fall through */ }
+    if (!requestId || (decision !== "approve" && decision !== "reject"))
+        return '[error] review_plan needs a request_id and decision "approve" or "reject".';
+    const approved = decision === "approve";
+    const res = resolveResponse(requestId, "plan_approval", approved); // match_response: validates kind + state
+    if (!res.ok)
+        return `[error] ${res.error}`;
+    sendProtocol(LEAD, res.state.from, "plan_approval_response", requestId, reason || (approved ? "approved" : "rejected"), approved ? "approved" : "rejected");
+    return `Plan ${approved ? "approved" : "rejected"} (${requestId}); told ${res.state.from}.`;
+}
+// submit_plan (teammate → lead): open a plan_approval contract and STOP. The
+// teammate idles after this until the lead's decision lands in its inbox.
+async function runSubmitPlan(call, opts) {
+    if (!opts.teammate)
+        return "[error] Only a teammate can submit a plan (the lead reviews them).";
+    let plan = "";
+    try {
+        plan = JSON.parse(call.args).plan ?? "";
+    }
+    catch { /* fall through */ }
+    if (!plan.trim())
+        return "[error] submit_plan needs a non-empty 'plan'.";
+    const requestId = createRequest("plan_approval", opts.teammate.name, LEAD, plan);
+    sendProtocol(opts.teammate.name, LEAD, "plan_approval_request", requestId, plan);
+    return `Plan submitted to the lead for approval (${requestId}). STOP here and wait — the lead's decision will arrive in your inbox. Do NOT start the work until it is approved.`;
+}
+// ---- The task board tools (Day 40) ------------------------------------------
+// The claimer's identity is the calling agent's name — the lead or a teammate.
+const boardActor = (opts) => opts.teammate?.name ?? LEAD;
+async function runCreateTask(call, opts) {
+    if (opts.subAgent && !opts.teammate)
+        return "[error] Only team agents use the task board."; // plain sub-agents have no board
+    let subject = "", description = "", blockedBy = [];
+    try {
+        const a = JSON.parse(call.args);
+        subject = (a.subject ?? "").trim();
+        description = a.description ?? "";
+        if (Array.isArray(a.blockedBy))
+            blockedBy = a.blockedBy.filter((x) => typeof x === "string");
+    }
+    catch { /* fall through */ }
+    if (!subject)
+        return "[error] create_task needs a 'subject'.";
+    const task = createTask(subject, description, blockedBy);
+    if (!opts.quiet)
+        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} created ${task.id}: ${subject.slice(0, 50)}`));
+    return `Created ${task.id}: "${subject}"${blockedBy.length ? ` (blockedBy: ${blockedBy.join(", ")})` : ""}. It's on the board for a teammate to claim.`;
+}
+async function runListTasks(_call, opts) {
+    if (opts.subAgent && !opts.teammate)
+        return "[error] Only team agents use the task board.";
+    return `Task board:\n${boardSummary()}`;
+}
+async function runClaimTask(call, opts) {
+    if (opts.subAgent && !opts.teammate)
+        return "[error] Only team agents use the task board.";
+    let taskId = "";
+    try {
+        taskId = JSON.parse(call.args).task_id?.trim() ?? "";
+    }
+    catch { /* fall through */ }
+    if (!taskId)
+        return "[error] claim_task needs a 'task_id'.";
+    const res = claimTask(taskId, boardActor(opts));
+    if (!res.ok)
+        return `[error] ${res.error} Pick another task or check list_tasks.`;
+    return `Claimed ${res.task.id}: "${res.task.subject}". It's yours and in_progress. Do it, then call complete_task("${res.task.id}").\n${res.task.description}`;
+}
+async function runCompleteTask(call, opts) {
+    if (opts.subAgent && !opts.teammate)
+        return "[error] Only team agents use the task board.";
+    let taskId = "";
+    try {
+        taskId = JSON.parse(call.args).task_id?.trim() ?? "";
+    }
+    catch { /* fall through */ }
+    if (!taskId)
+        return "[error] complete_task needs a 'task_id'.";
+    const res = completeTask(taskId, boardActor(opts));
+    if (!res.ok)
+        return `[error] ${res.error}`;
+    if (!opts.quiet)
+        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} completed ${taskId}`));
+    const unblocked = res.unblocked?.length ? ` Unblocked: ${res.unblocked.join(", ")}.` : "";
+    return `Completed ${taskId}.${unblocked} Claim the next ready task, or idle until the lead shuts you down.`;
+}
+// spawn_teammate: start a persistent worker that runs concurrently. Top-level
+// only — a teammate calling this is the nested-spawn case (its manual omits the
+// tool, but we guard anyway). Returns IMMEDIATELY; the teammate's loop runs in
+// the background and reports back through the lead's inbox.
+async function runSpawnTeammate(call, opts) {
+    if (opts.subAgent || opts.teammate)
+        return "[error] Only the lead can spawn teammates — teammates cannot spawn teammates. Do the work yourself or message the lead.";
+    let name = "", role = "", task = "";
+    try {
+        const a = JSON.parse(call.args);
+        name = (a.name ?? "").trim();
+        role = (a.role ?? "").trim();
+        task = a.task ?? "";
+    }
+    catch {
+        /* fall through */
+    }
+    if (!name || !role || !task.trim())
+        return "[error] spawn_teammate needs a non-empty name, role, and task.";
+    if (name === LEAD)
+        return `[error] "${LEAD}" is reserved for the coordinator — pick another name.`;
+    if (teammateExists(name))
+        return `[error] A teammate named "${name}" already exists — pick a unique name or message the existing one.`;
+    if (teammateCount() >= MAX_TEAMMATES)
+        return `[error] The team is full (${MAX_TEAMMATES} teammates max). Wait for one to finish, or do the work yourself.`;
+    // Kick off the teammate's loop WITHOUT awaiting it — that is what makes it
+    // concurrent. It progresses whenever the event loop is free (e.g. while the
+    // lead awaits its own API stream). We keep the promise so the lead and
+    // shutdown know when it has ended.
+    const done = runTeammate(name, role, task, opts);
+    registerTeammate(name, role, done);
+    if (!opts.quiet)
+        console.log(mark.teammateStart(name, role));
+    return `Teammate "${name}" (${role}) spawned and is now working in parallel. It will message you (as "lead") with progress and its final result. Reply with send_message; keep coordinating the rest of the team. Do not wait idly — continue your own work.`;
+}
+// Run one teammate to completion: a fresh conversation seeded with its task, a
+// focused toolset, its own mailbox, and a hard round cap. On any ending it sends
+// a `result` message back to the lead — so the lead always learns the outcome,
+// success or failure. The teammate's file read-state is isolated by snapshot,
+// exactly like a sub-agent (it reads things the lead's conversation never saw).
+async function runTeammate(name, role, task, opts) {
+    emit("agent_teammate_spawn");
+    await runHooks("SubagentStart", { description: `teammate ${name}: ${role}`.slice(0, 200), model: opts.model });
+    const snapshot = snapshotFileState();
+    const system = TEAMMATE_PROMPT.replace("{name}", name).replace("{role}", role);
+    try {
+        const messages = [
+            { role: "system", content: system },
+            { role: "user", content: task }, // its first instruction; more arrive via the inbox
+        ];
+        // A teammate is a sub-agent (quiet streaming, no hooks, isolated) PLUS team
+        // wiring: a name, its inbox, a non-interactive permission policy (it cannot
+        // prompt the human, so writes auto-proceed but risky bash is declined — see
+        // teammateConfirm; deny ALWAYS still wins), and a runaway backstop. Day 39:
+        // it is no longer bounded by a low round cap — it idle-waits for work and
+        // exits on the shutdown handshake (continueForTeam); maxRounds is only a
+        // generous guard against an active loop that never stops calling tools.
+        const result = await runLoop(messages, {
+            ...opts,
+            subAgent: true,
+            teammate: { name },
+            maxRounds: TEAMMATE_MAX_ROUNDS,
+            confirm: teammateConfirm(name),
+            askUser: undefined, // teammates have no line to the human
+        });
+        // How it ended decides what the lead hears. A shutdown handshake gets a
+        // shutdown_response(approved) carrying the request_id; anything else is a
+        // plain result. Either way the lead always learns the outcome.
+        const summary = result.reason === TerminateReason.Done && result.finalText?.trim() ? result.finalText.trim() : `[ended: ${result.reason}]`;
+        const sd = shutdownRequestId(name);
+        if (sd)
+            sendProtocol(name, LEAD, "shutdown_response", sd, summary || "shut down", "approved");
+        else
+            sendMessage(name, LEAD, summary, "result");
+        finishTeammate(name, result.reason === TerminateReason.Done);
+        if (!opts.quiet)
+            console.log(mark.teammateDone(name, result.reason === TerminateReason.Done));
+    }
+    catch (err) {
+        // A teammate must never take the whole process down. Report the failure to
+        // the lead and mark it failed.
+        sendMessage(name, LEAD, `[teammate crashed: ${err.message}]`, "result");
+        finishTeammate(name, false);
+    }
+    finally {
+        restoreFileState(snapshot);
+        await runHooks("SubagentStop", { description: `teammate ${name}` });
+    }
+}
+const TEAMMATE_MAX_ROUNDS = 30; // runaway backstop for an active teammate (not the lifecycle — idle-wait + shutdown handshake end it normally)
+const TEAM_POLL_MS = 250; // how often an idle agent polls its inbox while waiting
+const TEAMMATE_MAX_IDLE_MS = 60_000; // an abandoned teammate self-exits after this long with nothing to do (the lead normally shuts it down first)
+const SHUTDOWN_GRACE_MS = 30_000; // how long the lead waits for teammates to exit cleanly when it disbands the team
+// A teammate's permission policy. It cannot stop and ask the human, so: file
+// writes/edits auto-proceed (that is the teammate's job, and they are reversible
+// via /undo and reviewable via /diff), but anything else the gate rated "ask"
+// (unrecognized or dangerous bash) is DECLINED rather than run unattended. Hard
+// DENY rules (the no-fly zone) are enforced by the gate before confirm is ever
+// called, so they always hold. Production Claude Code instead "bubbles" the
+// request up to the lead and on to the human — omitted here, like the reference.
+function teammateConfirm(name) {
+    return async (_question, toolName) => {
+        const ok = toolName === "write_file" || toolName === "edit_file";
+        if (!ok)
+            console.log(chalk.yellow(`  ⎿ [${name}] declined ${toolName ?? "an action"} (teammates can't prompt you; do it yourself or allowlist it)`));
+        return ok;
+    };
+}
 // Present the ask_user form and turn the selections into a tool result. The
 // model called this to get a decision; we give it clean question→answer pairs.
 async function runAskUser(call, opts) {
@@ -410,6 +910,152 @@ compaction) {
         return false;
     }
 }
+// Surface any FINISHED background tasks (Day 37) as a user turn, so the model
+// sees the result of work it kicked off earlier. Mirrors the tutorial reference,
+// adapted to the OpenAI wire protocol: tool results are their own role:"tool"
+// messages, so a notification can't ride inside them — it follows as a user
+// message instead (exactly how the todo nag and Stop hook already inject turns).
+// Top-level only: a sub-agent has no separate turn loop to inject into, and the
+// notification belongs to the agent that started the job. Returns true if it
+// injected something. Each finished task notifies exactly once (background.ts).
+function injectBackgroundNotifications(messages, opts) {
+    if (opts.subAgent)
+        return false; // notifications belong to the top-level conversation
+    const note = pendingNotifications(); // "" unless a task finished since we last checked
+    if (!note)
+        return false;
+    const count = (note.match(/<task_notification>/g) ?? []).length; // for the one-line on-screen mark
+    messages.push({ role: "user", content: note }); // the model reacts to it on the next round
+    if (!opts.quiet)
+        console.log(mark.bgNote(count));
+    return true;
+}
+// Consume this agent's mailbox into its conversation, ROUTING protocol messages
+// (Day 39) as it goes — the reference's consume_lead_inbox + dispatch_message in
+// one pass. The lead reads "lead"; a teammate reads its own name. The read is
+// consumptive (team.ts), so each message is handled exactly once. Protocol
+// messages update state (correlate responses via match_response, flag a shutdown)
+// AND get a plain-language line so the model can react; plain chat is passed
+// through. Returns whether anything was injected. (Plan-approval is a handshake,
+// not a hard gate: the teammate is TOLD to wait and does — execution gating by
+// permission mode is what production Claude Code adds; omitted here, per s16.)
+function consumeInbox(messages, opts) {
+    if (opts.subAgent && !opts.teammate)
+        return false; // a plain sub-agent is not on the team
+    const me = opts.teammate?.name ?? LEAD;
+    const msgs = readInbox(me);
+    if (!msgs.length)
+        return false;
+    const lines = [];
+    for (const m of msgs) {
+        switch (m.kind) {
+            case "shutdown_request": // (teammate side) the lead asked us to shut down
+                markShutdown(me, m.requestId ?? "");
+                lines.push(`[lead] SHUTDOWN REQUESTED (${m.requestId}): ${m.content}. Finish any in-progress write, then you will exit cleanly.`);
+                break;
+            case "shutdown_response": // (lead side) a teammate confirmed it shut down
+                if (m.requestId)
+                    resolveResponse(m.requestId, "shutdown", m.status === "approved");
+                finishTeammate(m.from, true);
+                lines.push(`[${m.from}] confirmed shutdown (${m.requestId}) and has exited.`);
+                break;
+            case "plan_approval_request": // (lead side) a teammate wants approval before risky work
+                lines.push(`[${m.from}] PLAN APPROVAL REQUESTED (${m.requestId}). Review it, then call review_plan with this id. Plan:\n${m.content}`);
+                break;
+            case "plan_approval_response": { // (teammate side) the lead decided on our plan
+                if (m.requestId)
+                    resolveResponse(m.requestId, "plan_approval", m.status === "approved");
+                const ok = m.status === "approved";
+                lines.push(`[lead] plan ${ok ? "APPROVED" : "REJECTED"} (${m.requestId})${m.content ? `: ${m.content}` : ""}. ${ok ? "Proceed with the plan now." : "Revise it and submit_plan again."}`);
+                break;
+            }
+            default: // plain chat / a teammate's result
+                lines.push(`[message from ${m.from}${m.type === "result" ? " · RESULT" : ""}] ${m.content}`);
+        }
+    }
+    const header = opts.teammate ? "Messages from your team — read and act on them:" : "Team inbox — react to these (RESULT = that teammate finished a part):";
+    messages.push({ role: "user", content: `${header}\n\n${lines.join("\n\n")}` });
+    if (!opts.quiet)
+        console.log(opts.teammate ? chalk.dim(`  ⎿ [${me}] received ${msgs.length} message(s)`) : mark.inbox(msgs.length));
+    return true;
+}
+// At a stop-point (no tool calls), decide whether the TEAM keeps this agent's
+// conversation alive (Day 38/39).
+//   - A teammate now IDLE-LOOPS instead of exiting: it processes its inbox, and
+//     if there's nothing to do it waits (yielding the event loop) for new work —
+//     bounded, so an abandoned teammate self-exits instead of hanging forever. It
+//     leaves only on the shutdown handshake (its request_id is set) or that
+//     backstop. While waiting it marks itself "idle" so the lead can tell the
+//     team is quiescent.
+//   - The lead waits while any teammate is actively working, then drains its
+//     inbox. When the team has gone quiet and nothing is waiting, it returns
+//     false → the lead finishes (and disbands the team, see runLoop).
+async function continueForTeam(messages, opts) {
+    if (opts.teammate) {
+        const me = opts.teammate.name;
+        let waited = 0;
+        while (true) {
+            const injected = consumeInbox(messages, opts); // INBOX FIRST (priority) — route protocol + plain; may set the shutdown flag
+            if (shutdownRequestId(me))
+                return false; // shutdown handshake → exit (runTeammate sends the response)
+            if (injected) {
+                setTeammateState(me, "active");
+                return true;
+            } // a direct message arrived → run a round
+            // s17 autonomy: nothing in the inbox — pull ready work off the shared board
+            // yourself. claimNextAvailable atomically claims the next pending+unblocked
+            // task; the claim is what makes this safe with several teammates scanning.
+            const claimed = claimNextAvailable(me);
+            if (claimed) {
+                // The claimed task becomes a fresh WORK instruction. The leading identity
+                // line also re-anchors the persona if the history was compacted (the
+                // reference's identity-reinjection, folded into the work hand-off).
+                messages.push({ role: "user", content: `You are ${me}. You claimed task ${claimed.id} from the board: "${claimed.subject}".\n${claimed.description}\nWhen it is done and verified, call complete_task("${claimed.id}") — then you'll be offered the next ready task.` });
+                if (!opts.quiet)
+                    console.log(chalk.magenta(`  ⎿ [${me}] claimed ${claimed.id}: ${claimed.subject.slice(0, 50)}`));
+                setTeammateState(me, "active");
+                return true;
+            }
+            setTeammateState(me, "idle"); // inbox empty AND no claimable work — wait
+            if (opts.isInterrupted() || waited >= TEAMMATE_MAX_IDLE_MS)
+                return false; // abandoned → self-exit backstop
+            await interruptibleSleep(TEAM_POLL_MS, opts.isInterrupted);
+            waited += TEAM_POLL_MS;
+        }
+    }
+    if (opts.subAgent)
+        return false; // a plain sub-agent has no team
+    // The lead: wait for the team to act rather than spinning or ending early.
+    while (inboxCount(LEAD) === 0 && anyTeammateBusy() && !opts.isInterrupted()) {
+        await interruptibleSleep(TEAM_POLL_MS, opts.isInterrupted); // yield to the teammates; they message us when they have something
+    }
+    return consumeInbox(messages, opts); // process whatever is waiting; false if the team is quiescent (→ the lead may finish)
+}
+// The lead finished its work but teammates may still be idling. Disband the team
+// GRACEFULLY (Day 39): open a shutdown contract with each, let them confirm and
+// exit (bounded by a grace window so a wedged teammate can't hang the prompt),
+// then drain the lead's inbox of their confirmations and clear the team.
+async function shutdownTeam(opts) {
+    const running = runningTeammates();
+    if (!running.length)
+        return;
+    if (!opts.quiet)
+        console.log(chalk.magenta(`  ⎿ disbanding team — shutting down ${running.length} teammate(s)`));
+    for (const name of running) {
+        const id = createRequest("shutdown", LEAD, name, "task complete");
+        markShutdown(name, id);
+        sendProtocol(LEAD, name, "shutdown_request", id, "The task is complete — wrap up and exit.");
+    }
+    // Yield the event loop so the teammates wake, confirm, and exit — but never
+    // block the human forever on a stuck one.
+    const start = Date.now();
+    while (runningTeammates().length && Date.now() - start < SHUTDOWN_GRACE_MS && !opts.isInterrupted()) {
+        await interruptibleSleep(TEAM_POLL_MS, opts.isInterrupted);
+    }
+    readInbox(LEAD); // drop the shutdown confirmations the lead won't read
+    resetTeam(); // clear the registry + protocol state; the next task starts with a fresh team
+    resetBoard(); // and a fresh task board — its work is done with this team
+}
 // The agent main loop, as a state machine: every iteration either continues
 // for a named reason or terminates for a named reason — nothing implicit.
 export async function runLoop(messages, // conversation history (mutated in place)
@@ -417,7 +1063,14 @@ opts) {
     // The loop's mutable state: budgets and counters, rewritten every iteration.
     const attempts = { total: 0, rateLimited: 0, consecutive: 0 };
     const compaction = { count: 0, failures: 0 }; // compaction score card for this query
+    let lastText = null; // most recent assistant text — what we return if a round cap (teammates) stops us mid-flight
     for (let round = 1;; round++) {
+        // A bounded loop (teammates, Day 38) stops cleanly at its round cap with
+        // whatever it last said, so a team can never run away. Unset maxRounds keeps
+        // the usual unbounded-with-safeguards loop for the lead and the user's agent.
+        if (opts.maxRounds && round > opts.maxRounds) {
+            return { reason: TerminateReason.Done, finalText: lastText ?? `(reached the ${opts.maxRounds}-round limit)` };
+        }
         // One round = one successful model call + its tool results.
         // The inner loop retries the model call until it succeeds or a budget dies.
         while (true) {
@@ -492,6 +1145,8 @@ opts) {
                     ? { tool_calls: out.toolCalls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })) }
                     : {}), // omit the field entirely when there were no calls
             });
+            if (out.content)
+                lastText = out.content; // remember the latest answer text — the round-cap path returns it
             if (!out.toolCalls.length) {
                 // The model wants to stop. A Stop hook gets the last word: if it exits
                 // 2, the agent is NOT done — its stderr becomes a new instruction and
@@ -508,6 +1163,22 @@ opts) {
                         break; // exit the inner while → advance the round counter
                     }
                 }
+                // A background task may have finished in the very round the model decided
+                // to stop. Don't return with an unread result on the table: surface it and
+                // run one more round so the model can react. Each task notifies once, so
+                // this adds at most one round per finished task — never an infinite stop.
+                if (injectBackgroundNotifications(messages, opts))
+                    break; // exit the inner while → advance the round counter
+                // Agent teams (Day 38/39): the lead waits for teammate messages and
+                // reacts; a teammate idle-loops for new work and leaves only on the
+                // shutdown handshake (or its idle backstop). If there's something to
+                // process, run another round instead of stopping.
+                if (await continueForTeam(messages, opts))
+                    break; // exit the inner while → advance the round counter
+                // The lead is really finishing: disband any teammates still idling so
+                // they exit cleanly (Day 39) instead of being orphaned.
+                if (!opts.subAgent && !opts.teammate)
+                    await shutdownTeam(opts);
                 return { reason: TerminateReason.Done, finalText: out.content }; // no tool calls = final answer (already streamed to the screen)
             }
             // Execute the tool calls. Read-only calls (read_file/search) in a
@@ -532,6 +1203,27 @@ opts) {
                 const r = await runOneCall(out.toolCalls[i++], opts);
                 messages.push({ role: "tool", tool_call_id: r.id, content: r.content });
             }
+            // Background tasks (Day 37): if a job the model started has finished, slip
+            // its <task_notification> in here, right after this round's tool results —
+            // the model sees the outcome on the next round without ever having blocked
+            // on it. Tasks that are still running stay silent until they finish.
+            injectBackgroundNotifications(messages, opts);
+            // Agent teams (Day 38/39): drain any messages that arrived during this
+            // round (results, hand-offs, protocol requests/responses) so the agent
+            // reacts to them next round. A shutdown_request seen here just flags the
+            // teammate; it acts on it at the next stop-point (continueForTeam).
+            consumeInbox(messages, opts);
+            // The nag: if there's an unfinished plan the model has stopped touching for
+            // a few rounds, slip in a reminder so the list doesn't go stale and
+            // meaningless. Top-level only — a sub-agent has no plan of its own.
+            if (!opts.subAgent) {
+                const nag = todoNag();
+                if (nag) {
+                    messages.push({ role: "user", content: nag });
+                    if (!opts.quiet)
+                        console.log(chalk.dim("  ⎿ plan reminder injected"));
+                }
+            }
             break; // round complete, move to the next one
         }
     }