agent-from-zero 0.31.0 → 0.32.1

package/dist/loop.js

@@ -1,5 +1,4 @@
 import chalk from "chalk"; // terminal colors for status lines
-import ora from "ora"; // the "thinking..." spinner while waiting for the first token
 import { toolDefinitions, dispatch, snapshotFileState, restoreFileState, isReadOnlyTool } from "./tools.js"; // the tool manuals + the executor + file-state isolation
 import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
@@ -13,7 +12,7 @@ import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / Pos
 import { recordUsage } from "./cost.js"; // meter token usage from the stream
 import { mark, thinkingWord, spinnerText } from "./ui.js"; // centralized terminal styling (markers, spinner)
 import { recordToolCall, recordReasoning } from "./tui.js"; // folded tool-call trace (Ctrl+T) + the model's hidden thinking (Ctrl+R)
-import { MarkdownStream } from "./markdown.js"; // render the streamed answer as terminal markdown
+import { STDOUT_OUTPUT } from "./output.js"; // where the loop's screen output goes (stdout by default, Ink REPL passes its own)
 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
@@ -36,6 +35,11 @@ export var TerminateReason;
     TerminateReason["FatalApiError"] = "fatal_api_error";
     TerminateReason["UserInterrupt"] = "user_interrupt";
 })(TerminateReason || (TerminateReason = {}));
+// Resolve the output sink for a loop: the caller's sink, or stdout (the old
+// behaviour) when none was passed. Centralised so every site reads the same way.
+function sink(opts) {
+    return opts.output ?? STDOUT_OUTPUT;
+}
 // Which model should a delegated sub-agent run on? The configured sub-agent
 // model if set and non-blank, otherwise the same model as the orchestrator.
 // Pulled out as a pure function so the tiering rule is testable on its own.
@@ -51,6 +55,7 @@ const taskTool = {
         description: `Delegate one self-contained subtask to a sub-agent that works in a FRESH context.
 The sub-agent has the same tools (except task) but knows NOTHING about this conversation — put every detail it needs into the description.
 Use it for exploration that would flood your context: reading many files, broad searches, summarizing a directory.
+The sub-agent runs ASYNC — it returns a handle immediately and you are notified when it finishes. Do NOT wait idly: continue working or wait for its result.
 The sub-agent's report is INPUT MATERIAL, not verified truth — re-check key claims yourself before acting on them.
 On error: a failed sub-agent returns [sub-agent failed: reason] — retry with a clearer description, or do the work yourself.`,
         parameters: {
@@ -273,37 +278,94 @@ function toolsFor(opts) {
     // 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) {
-    emit("agent_subagent_spawn"); // delegation is worth counting
-    const subModel = subAgentModelFor(opts); // the tier this delegated work runs on
-    // Show the delegation, and the model when it differs from the orchestrator's —
-    // the tiering should be visible, not a silent surprise on the bill.
+const pendingSubAgents = new Map();
+let subAgentSeq = 0;
+// Collect finished sub-agent results (like pendingNotifications for background
+// tasks). Each result surfaces exactly once (the `notified` flag).
+function pendingSubAgentResults() {
+    const done = [];
+    for (const sa of pendingSubAgents.values()) {
+        if (sa.result === null || sa.notified)
+            continue;
+        sa.notified = true;
+        done.push(`<subagent_notification>\n  <id>${sa.id}</id>\n  <task>${sa.description.slice(0, 200)}</task>\n  <result>\n${sa.result}\n  </result>\n</subagent_notification>`);
+    }
+    if (!done.length)
+        return "";
+    return `A sub-agent you delegated work to has finished. Read its report carefully — it is INPUT MATERIAL, not verified truth. Verify key claims yourself, then continue.\n\n${done.join("\n\n")}`;
+}
+// Inject finished sub-agent results into the conversation, like
+// injectBackgroundNotifications. Returns true if something was injected.
+function injectSubAgentResults(messages, opts) {
+    if (opts.subAgent)
+        return false; // notifications belong to the top-level conversation
+    const note = pendingSubAgentResults();
+    if (!note)
+        return false;
+    messages.push({ role: "user", content: note });
+    if (!opts.quiet)
+        sink(opts).note(mark.subAgentDone);
+    return true;
+}
+// Start a sub-agent WITHOUT awaiting — returns a handle immediately. The
+// sub-agent's result will be injected as a notification when it finishes.
+function spawnSubAgent(description, opts) {
+    emit("agent_subagent_spawn");
+    const subModel = subAgentModelFor(opts);
+    const id = `sa_${++subAgentSeq}`;
     if (!opts.quiet)
-        console.log(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
-    await runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // lifecycle hook (observational)
+        sink(opts).note(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : ""));
+    runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // fire-and-forget (observational)
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
-    try {
-        const subMessages = [
-            { role: "system", content: SUB_AGENT_PROMPT }, // its own, smaller constitution
-            { role: "user", content: description }, // the task is its entire world
-        ];
-        const result = await runLoop(subMessages, { ...opts, subAgent: true, model: subModel }); // recurse as a sub-agent, on its own tier
-        if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
-            // The framing matters: the parent must treat this as material to verify,
-            // not as conclusions to copy — the most common multi-agent failure mode.
-            return `Sub-agent report (INPUT MATERIAL — verify key claims before acting on them):\n${result.finalText}`;
+    const sa = { id, description, done: Promise.resolve(), result: null, notified: false };
+    sa.done = (async () => {
+        try {
+            const subMessages = [
+                { role: "system", content: SUB_AGENT_PROMPT },
+                { role: "user", content: description },
+            ];
+            const result = await runLoop(subMessages, { ...opts, subAgent: true, model: subModel });
+            if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
+                sa.result = `Sub-agent report (INPUT MATERIAL — verify key claims before acting on them):\n${result.finalText}`;
+            }
+            else {
+                sa.result = `[sub-agent failed: ${result.reason}]`;
+            }
         }
-        return `[sub-agent failed: ${result.reason}]`; // any non-Done ending, compressed to one line
-    }
-    finally {
-        restoreFileState(snapshot); // the parent's read-before-edit state, exactly as it was
-        await runHooks("SubagentStop", { description: description.slice(0, 200) }); // lifecycle hook (observational)
-        if (!opts.quiet)
-            console.log(mark.subAgentDone); // close the bracket
+        catch (err) {
+            sa.result = `[sub-agent crashed: ${err.message}]`;
+        }
+        finally {
+            restoreFileState(snapshot);
+            await runHooks("SubagentStop", { description: description.slice(0, 200) });
+        }
+    })();
+    pendingSubAgents.set(id, sa);
+    return `Sub-agent started (${id}): "${description.slice(0, 100)}". Continue working — you'll be notified when it finishes. Do NOT wait idly; keep working on other parts of the task, or wait for the notification.`;
+}
+// True if any sub-agent is still running.
+function hasRunningSubAgents() {
+    return [...pendingSubAgents.values()].some((sa) => sa.result === null);
+}
+// Kill every still-running sub-agent. Called on session exit.
+export function killAllSubAgents() {
+    for (const sa of pendingSubAgents.values()) {
+        if (sa.result === null)
+            sa.result = "[sub-agent killed: session exited]";
     }
 }
+// Snapshot of current sub-agents for the UI (Ink app shows a list below the
+// input box, like Claude Code's agent list). Newest first.
+export function listSubAgents() {
+    return [...pendingSubAgents.values()]
+        .reverse()
+        .map((sa) => ({
+        id: sa.id,
+        description: sa.description.slice(0, 80),
+        status: sa.result === null ? "running" : sa.result.startsWith("[sub-agent failed") || sa.result.startsWith("[sub-agent crashed") || sa.result.startsWith("[sub-agent killed") ? "failed" : "done",
+        result: sa.result ?? undefined,
+    }));
+}
 // Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
 // Without jitter, every client that failed at the same second retries at the
 // same second — a thundering herd against an already-struggling server.
@@ -335,7 +397,7 @@ opts) {
     let reasoningShown = false; // have we printed the "thought for Ns" indicator yet?
     const spinner = opts.quiet
         ? null // the eval harness wants silence
-        : ora({ text: spinnerText(word, 0, !!opts.subAgent, opts.model), discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
+        : sink(opts).spinner(spinnerText(word, 0, !!opts.subAgent, opts.model)); // a fresh spinner from the sink (stdout → ora; Ink → React state)
     let lastEvent = Date.now(); // when did we last hear ANYTHING from the stream?
     let stallWarned = false; // only warn once per quiet stretch
     // The two-level watchdog, checked once per second:
@@ -345,8 +407,8 @@ opts) {
     const watchdog = setInterval(() => {
         // While the model is reasoning, prefix the spinner with 💭 so "it's thinking"
         // reads differently from "it's waiting on the first token".
-        if (spinner?.isSpinning)
-            spinner.text = (reasoningActive ? chalk.dim("💭 ") : "") + spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4));
+        if (spinner?.spinning)
+            spinner.set((reasoningActive ? chalk.dim("💭 ") : "") + spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4)));
         const quietMs = Date.now() - lastEvent; // ms since the last event
         if (quietMs > IDLE_TIMEOUT_MS) {
             emit("agent_watchdog_idle"); // record the cut — these should be rare
@@ -355,7 +417,7 @@ opts) {
         else if (quietMs > STALL_WARN_MS && !stallWarned) {
             stallWarned = true; // don't repeat the warning every second
             emit("agent_watchdog_stall"); // record the slowness — pattern-spotting data
-            console.log(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
+            sink(opts).note(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
         }
     }, 1000);
     try {
@@ -370,8 +432,7 @@ opts) {
         // 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 md = null; // renders the streamed answer as markdown, block by block
+        let ans = null; // renders the streamed answer (stdout: markdown block by block; Ink: React state) — non-null once the answer starts
         const calls = []; // tool calls under assembly, indexed by delta.index
         // The model has finished thinking and is about to say/do something. Close out
         // the spinner, stash the trace, and print a single one-line indicator with the
@@ -382,7 +443,7 @@ opts) {
                 return;
             reasoningShown = true;
             reasoningActive = false;
-            if (spinner?.isSpinning)
+            if (spinner?.spinning)
                 spinner.stop();
             if (opts.quiet || opts.subAgent)
                 return; // no UI for silent / nested runs
@@ -390,7 +451,7 @@ opts) {
             const secs = Math.round((Date.now() - startedAt) / 1000);
             const toks = Math.round(reasoningBuf.length / 4); // same ~chars/4 estimate as the spinner
             const tokStr = toks >= 1000 ? `${(toks / 1000).toFixed(1)}k` : `${toks}`;
-            process.stdout.write(chalk.dim(`💭 thought for ${secs}s (~${tokStr} tokens) · Ctrl+R to view`) + "\n");
+            sink(opts).reasoning(chalk.dim(`💭 thought for ${secs}s (~${tokStr} tokens) · Ctrl+R to view`));
         };
         for await (const chunk of stream) {
             lastEvent = Date.now(); // feed the watchdog
@@ -414,27 +475,24 @@ opts) {
             if (delta.content) {
                 flushReasoning(); // thinking is over — show the one-line indicator first
                 streamedChars += delta.content.length; // count the answer toward the live token estimate
-                if (spinner?.isSpinning)
+                if (spinner?.spinning)
                     spinner.stop(); // first token: replace the spinner with real output
                 if (!opts.quiet && !opts.subAgent) {
                     // Only the top-level agent streams to the screen — a sub-agent's
-                    // inner monologue would be mistaken for the answer.
-                    if (!printedPrefix) {
-                        // 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;
-                    }
-                    md.push(delta.content); // hand the token to the renderer (it decides when to paint)
+                    // inner monologue would be mistaken for the answer. The sink decides
+                    // how to paint: the stdout sink buffers a markdown block (paragraph /
+                    // heading / list / table) and flushes it whole — live, but no raw
+                    // `##`/`|---|`; the Ink sink accumulates into React state.
+                    if (!ans)
+                        ans = sink(opts).answer(); // first token: start the answer renderer
+                    ans.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)
             }
             if (delta.tool_calls?.length)
                 flushReasoning(); // thinking is over — indicator before the tool logs (which print after we return)
             for (const tc of delta.tool_calls ?? []) {
-                if (spinner?.isSpinning)
+                if (spinner?.spinning)
                     spinner.stop(); // tool call starting — spinner served its purpose
                 const slot = (calls[tc.index] ??= { id: "", name: "", args: "" }); // create the slot on first fragment
                 if (tc.id)
@@ -446,15 +504,13 @@ opts) {
             }
         }
         flushReasoning(); // a reasoning-only turn (no content, no tools) still records + indicates
-        if (md)
-            md.end(); // flush the final (un-terminated) block through the renderer
-        if (printedPrefix)
-            process.stdout.write("\n"); // end the streamed line cleanly
+        if (ans)
+            ans.end(); // flush the final (un-terminated) block + end the line cleanly (the sink owns the trailing newline)
         return { content, toolCalls: calls.filter(Boolean) }; // sparse array → dense
     }
     finally {
         clearInterval(watchdog); // always stop the timer
-        if (spinner?.isSpinning)
+        if (spinner?.spinning)
             spinner.stop(); // and never leave a zombie spinner
     }
 }
@@ -487,13 +543,13 @@ async function runOneCall(call, opts) {
     if (!opts.quiet && v.decision !== "deny" && (call.name === "write_file" || call.name === "edit_file")) {
         const preview = previewChange(call.name, call.args);
         if (preview)
-            console.log(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
+            sink(opts).note(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
     }
     let content; // what goes back to the model as the tool result
     if (v.decision === "deny") {
         emit("agent_tool_denied", { tool: call.name }); // hard blocks, per tool
         if (!opts.quiet)
-            console.log(mark.denied(v.reason)); // tell the user we blocked it
+            sink(opts).note(mark.denied(v.reason)); // tell the user we blocked it
         content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
     }
     else if (v.decision === "ask") {
@@ -510,14 +566,14 @@ async function runOneCall(call, opts) {
             if (cmd && (await opts.judge.classify(cmd)) === "allow") {
                 autoAllowed = true;
                 if (!opts.quiet)
-                    console.log(mark.judge); // visible — the user can see the judge worked
+                    sink(opts).note(mark.judge); // visible — the user can see the judge worked
             }
         }
         const ok = autoAllowed || (await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`, call.name)); // judge-allowed, or pause and ask the human
         if (!ok)
             emit("agent_tool_declined", { tool: call.name }); // the human said no — that is signal
         if (!ok && !opts.quiet)
-            console.log(mark.declined); // make the refusal visible
+            sink(opts).note(mark.declined); // make the refusal visible
         content = ok
             ? await runWithHooks(call, opts) // approved — run it (PreToolUse can still block)
             : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
@@ -528,7 +584,7 @@ async function runOneCall(call, opts) {
     // 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()));
+        sink(opts).note(renderTodos(getTodos()));
     }
     return { id: call.id, content }; // paired by id for the API
 }
@@ -546,7 +602,7 @@ async function runWithHooks(call, opts) {
     if (pre.block) {
         emit("agent_hook_block", { event: "PreToolUse", tool: call.name }); // a hook said no
         if (!opts.quiet)
-            console.log(mark.hookBlock("PreToolUse")); // make it visible
+            sink(opts).note(mark.hookBlock("PreToolUse")); // make it visible
         return `[hook] A PreToolUse hook blocked this call: ${pre.feedback}. Treat this as a hard boundary — adjust your approach.`;
     }
     // A PreToolUse hook may REWRITE the arguments (e.g. add a commit trailer). The
@@ -556,7 +612,7 @@ async function runWithHooks(call, opts) {
         try {
             JSON.parse(pre.rewrite); // must be valid JSON args
             if (!opts.quiet)
-                console.log(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
+                sink(opts).note(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
             call = { ...call, args: pre.rewrite };
         }
         catch {
@@ -615,7 +671,7 @@ async function execute(call, opts) {
     }
     if (!description)
         return "[error] task requires a non-empty description argument.";
-    return runSubAgent(description, opts); // spawn the worker
+    return spawnSubAgent(description, opts); // spawn the worker (async — returns immediately; result injected later)
 }
 // The sender's mailbox name: a teammate sends as itself, everyone else as "lead".
 const senderName = (opts) => opts.teammate?.name ?? LEAD;
@@ -744,7 +800,7 @@ async function runCreateTask(call, opts) {
         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)}`));
+        sink(opts).note(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) {
@@ -781,7 +837,7 @@ async function runCompleteTask(call, opts) {
     if (!res.ok)
         return `[error] ${res.error}`;
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} completed ${taskId}`));
+        sink(opts).note(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.`;
 }
@@ -817,7 +873,7 @@ async function runSpawnTeammate(call, opts) {
     const done = runTeammate(name, role, task, opts);
     registerTeammate(name, role, done);
     if (!opts.quiet)
-        console.log(mark.teammateStart(name, role));
+        sink(opts).note(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
@@ -847,7 +903,7 @@ async function runTeammate(name, role, task, opts) {
             subAgent: true,
             teammate: { name },
             maxRounds: TEAMMATE_MAX_ROUNDS,
-            confirm: teammateConfirm(name),
+            confirm: teammateConfirm(name, sink(opts)),
             askUser: undefined, // teammates have no line to the human
         });
         // How it ended decides what the lead hears. A shutdown handshake gets a
@@ -861,7 +917,7 @@ async function runTeammate(name, role, task, opts) {
             sendMessage(name, LEAD, summary, "result");
         finishTeammate(name, result.reason === TerminateReason.Done);
         if (!opts.quiet)
-            console.log(mark.teammateDone(name, result.reason === TerminateReason.Done));
+            sink(opts).note(mark.teammateDone(name, result.reason === TerminateReason.Done));
     }
     catch (err) {
         // A teammate must never take the whole process down. Report the failure to
@@ -885,11 +941,11 @@ const SHUTDOWN_GRACE_MS = 30_000; // how long the lead waits for teammates to ex
 // 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) {
+function teammateConfirm(name, output) {
     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)`));
+            output.note(chalk.yellow(`  ⎿ [${name}] declined ${toolName ?? "an action"} (teammates can't prompt you; do it yourself or allowlist it)`));
         return ok;
     };
 }
@@ -925,7 +981,7 @@ compaction) {
     try {
         if (!opts.subAgent)
             await runHooks("PreCompact", {}); // lifecycle hook (top-level only; hooks are the human's project policy)
-        await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
+        await compactHistory(messages, opts.client, opts.model, opts.signal, (s) => sink(opts).note(s)); // do the actual work — narration through the sink (so it doesn't corrupt an Ink live region)
         compaction.count++; // one more successful compaction this query
         compaction.failures = 0; // success resets the failure streak
         emit("agent_compaction_ok"); // worth counting — frequent compaction means tasks are too big
@@ -956,7 +1012,7 @@ function injectBackgroundNotifications(messages, opts) {
     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));
+        sink(opts).note(mark.bgNote(count));
     return true;
 }
 // Consume this agent's mailbox into its conversation, ROUTING protocol messages
@@ -1005,7 +1061,7 @@ function consumeInbox(messages, opts) {
     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));
+        sink(opts).note(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
@@ -1041,7 +1097,7 @@ async function continueForTeam(messages, opts) {
                 // 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)}`));
+                    sink(opts).note(chalk.magenta(`  ⎿ [${me}] claimed ${claimed.id}: ${claimed.subject.slice(0, 50)}`));
                 setTeammateState(me, "active");
                 return true;
             }
@@ -1069,7 +1125,7 @@ async function shutdownTeam(opts) {
     if (!running.length)
         return;
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ disbanding team — shutting down ${running.length} teammate(s)`));
+        sink(opts).note(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);
@@ -1152,7 +1208,7 @@ opts) {
                 if (attempts.total >= MAX_RETRIES)
                     return { reason: TerminateReason.RetryBudgetExhausted, detail: `${e.kind}: ${e.message}` };
                 const wait = backoffMs(attempts.consecutive); // how long to back off this time
-                console.log(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
+                sink(opts).note(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
                 await interruptibleSleep(wait, opts.isInterrupted); // wait, but stay responsive to Ctrl+C
                 continue; // retry the same round
             }
@@ -1187,17 +1243,19 @@ opts) {
                     if (stop.block) {
                         emit("agent_hook_block", { event: "Stop" }); // the agent was sent back to work
                         if (!opts.quiet)
-                            console.log(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
+                            sink(opts).note(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
                         messages.push({ role: "user", content: `[Stop hook] You are not finished: ${stop.feedback}` }); // inject the instruction
                         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.
+                // A background task (or sub-agent) 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 notifies
+                // once, so this adds at most one round per finished job — never infinite.
                 if (injectBackgroundNotifications(messages, opts))
                     break; // exit the inner while → advance the round counter
+                if (injectSubAgentResults(messages, opts))
+                    break;
                 // 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
@@ -1235,13 +1293,16 @@ opts) {
             // Fold this round's tool calls into ONE tally line instead of one line per
             // call (the per-call announcements were recorded for Ctrl+T in runOneCall).
             if (!opts.quiet && out.toolCalls.length) {
-                console.log(agentIndent(opts) + mark.toolTally(out.toolCalls.map((c) => c.name)) + chalk.dim(" · Ctrl+T"));
+                sink(opts).note(agentIndent(opts) + mark.toolTally(out.toolCalls.map((c) => c.name)) + chalk.dim(" · Ctrl+T"));
             }
             // 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);
+            // Sub-agent results (async task delegation): same pattern — a finished
+            // sub-agent's report is injected here so the model can react next round.
+            injectSubAgentResults(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
@@ -1255,7 +1316,7 @@ opts) {
                 if (nag) {
                     messages.push({ role: "user", content: nag });
                     if (!opts.quiet)
-                        console.log(chalk.dim("  ⎿ plan reminder injected"));
+                        sink(opts).note(chalk.dim("  ⎿ plan reminder injected"));
                 }
             }
             break; // round complete, move to the next one

package/dist/output.js

@@ -0,0 +1,50 @@
+import ora from "ora"; // the "thinking…" spinner the default sink drives
+import { MarkdownStream } from "./markdown.js"; // the default sink renders the streamed answer as terminal markdown
+import { mark } from "./ui.js"; // the ⏺ answer marker, kept consistent with the rest of the UI
+// ---- the default sink: stdout, identical to the pre-sink behaviour -----------
+class StdoutSpinner {
+    s;
+    constructor(text) {
+        // discardStdin:false — ora would otherwise swallow Ctrl+C while spinning.
+        this.s = ora({ text, discardStdin: false }).start();
+    }
+    set(text) {
+        if (this.s.isSpinning)
+            this.s.text = text;
+    }
+    stop() {
+        if (this.s.isSpinning)
+            this.s.stop();
+    }
+    get spinning() {
+        return this.s.isSpinning;
+    }
+}
+// The sink the readline REPL (and every non-Ink caller) gets when it passes no
+// `output`. Each method is the exact line the loop used to run inline.
+export const STDOUT_OUTPUT = {
+    spinner: (text) => new StdoutSpinner(text),
+    reasoning: (line) => process.stdout.write(line + "\n"),
+    answer: () => {
+        // Lazily build the MarkdownStream on the first token (so a tool-only or
+        // empty turn prints nothing), then end with a single trailing newline —
+        // exactly the old `if (printedPrefix) process.stdout.write("\n")`.
+        let md = null;
+        let printed = false;
+        return {
+            push(token) {
+                if (!md)
+                    md = new MarkdownStream((s) => process.stdout.write(s), { firstPrefix: "\n" + mark.answer, indent: "  " });
+                printed = true;
+                md.push(token);
+            },
+            end() {
+                if (md)
+                    md.end();
+                if (printed)
+                    process.stdout.write("\n");
+            },
+        };
+    },
+    note: (line) => console.log(line),
+};

package/dist/tui.js

@@ -107,6 +107,18 @@ export function revealToolCalls() {
     process.stdout.write(toolCallLog.join("\n") + "\n");
     return true;
 }
+// Ink variants of the two reveals: RETURN the formatted block (or null) instead
+// of writing to stdout, so the Ink REPL can commit it as a note in its tree.
+export function getReasoning() {
+    if (!reasoningTrace.length)
+        return null;
+    return chalk.dim("💭 model's thinking:\n") + chalk.dim(reasoningTrace.join("\n\n— — —\n\n").replace(/^/gm, "  "));
+}
+export function getToolCalls() {
+    if (!toolCallLog.length)
+        return null;
+    return chalk.dim(`tool calls this turn (${toolCallLog.length}):\n`) + toolCallLog.join("\n");
+}
 // ---- cleanup -----------------------------------------------------------------
 // Called on exit. Nothing fancy to restore now (we no longer hijack the bottom
 // of the screen), but keep the hook so callers don't have to change if that

package/dist/ui.js

@@ -1,4 +1,5 @@
 import chalk from "chalk"; // the one place color lives
+import { displayWidth } from "./editor.js"; // CJK-/ANSI-aware width, to pad the sent-message bar to the full row
 // The app's visual theme, in one place. Before this, emoji and colors were
 // sprinkled across agent.ts and loop.ts — no coherent look, and impossible to
 // restyle without hunting. This module owns "what the tool looks like": the
@@ -22,14 +23,27 @@ function box(lines) {
     });
     return [top, ...body, bottom].join("\n");
 }
+// The llama — our mascot. Drawn in ASCII so it renders in any terminal.
+// Each line is styled with a warm alpaca-wool tone (ansi256 #215, a sandy gold).
+const LLAMA = [
+    "                    ╱▔▔╲   ╱▔▔╲",
+    "                   ╱    ╲_╱    ╲",
+    "                  ╭──────────────╮",
+    "                  │   ◉      ◉   │",
+    "                  │      ⏝      │",
+    "                  ╰──────┬──────╯",
+    "                         │",
+].join("\n");
 // The welcome banner, shown once at startup.
 export function banner(version, model, host) {
-    return box([
+    const art = chalk.ansi256(215)(LLAMA);
+    const info = box([
         { text: `mini-agent  v${version}`, style: chalk.bold.cyan },
         { text: `${model}  ·  ${host}`, style: chalk.dim },
         { text: "" },
         { text: "/help  commands     @file  attach     Esc  interrupt     Ctrl+C  quit", style: chalk.dim },
     ]);
+    return art + "\n" + info;
 }
 // The input prompt. A styled chevron, not a bare ">". Plan mode (Day 20) gets a
 // distinct marker so you always know writes are blocked.
@@ -124,11 +138,18 @@ export function inputRule() {
 export function framedPrompt(planMode) {
     return planMode ? chalk.yellow.bold("⏸ plan ❯ ") : chalk.cyan.bold("❯ ");
 }
-// How a SUBMITTED message is echoed into the scrollback once you hit Enter: a
-// distinct, muted "> …" line (not the bright ❯ prompt) so each turn reads like a
-// sent chat message scrolling up, leaving the input box empty below.
+// How a SUBMITTED message is echoed into the scrollback once you hit Enter:
+// a "> …" line on a full-width highlight BAR (like Claude Code), so each turn
+// reads as a distinct sent message scrolling up — not just faint text. The line
+// is padded to the terminal width so the background spans the whole row; if the
+// message is longer than the row it just wraps (the tail line won't be padded,
+// a minor cosmetic). Colors fall back gracefully when the terminal lacks 256.
 export function sentMessage(text) {
-    return chalk.dim("> " + text);
+    const cols = Math.max(20, process.stdout.columns || 80);
+    const content = "> " + text;
+    const w = displayWidth(content);
+    const padded = w < cols ? content + " ".repeat(cols - w) : content; // fill the row when it fits
+    return chalk.bgAnsi256(237).ansi256(252)(padded); // light-grey text on a subtle dark-grey bar
 }
 // ---- the selection menu -----------------------------------------------------
 // Render a numbered list of options with one highlighted. The interactive part