@thedevlabs-io/labd 0.5.0 → 0.6.0

package/dist/labd.js

@@ -433,6 +433,36 @@ var EXEC_TOOLS = ["run_command"];
 function isExecTool(name) {
   return EXEC_TOOLS.includes(name);
 }
+var AGENT_TOOLS = ["spawn_agent"];
+function isAgentTool(name) {
+  return AGENT_TOOLS.includes(name);
+}
+var MAX_SUBAGENTS = 3;
+var SUBAGENT_REPORT_CHARS = 8e3;
+function subAgentCapabilities(parent) {
+  return parent.filter((c) => !isAgentTool(c));
+}
+function subAgentConversationId(parentId, callId) {
+  return parentId ? `${parentId}~helper~${callId}` : void 0;
+}
+function subAgentBrief(task) {
+  return `You are working as a helper for labd, the assistant the learner is talking to. It has handed you one piece of a larger job and is waiting on your report. The learner is the same person, in the same project, under the same rules: the same tools, the same approvals, and the same things you will not do.
+
+Your task:
+
+${task.trim()}
+
+How to work:
+- You start with none of the parent conversation, so the task above is all you know about it. If it is not enough to act on, say what is missing in your report rather than guessing at the intent.
+- Do the task, and only the task. The parent decides what happens next, so do not widen the job, and do not ask the learner questions - your report goes to the parent, not to them.
+- If a write or command you need is declined, do not look for another way round it. Stop and say so.
+- End with a report the parent can act on without redoing your work: what you found or changed, file by file and with line numbers where they matter, and anything you could not finish and why. Keep it tight. Leave out how you went about it.`;
+}
+function subAgentReport(text) {
+  const clean = text.trim() || "The helper finished without a report.";
+  return clean.length <= SUBAGENT_REPORT_CHARS ? clean : `${clean.slice(0, SUBAGENT_REPORT_CHARS)}
+... the helper's report was longer than this and was trimmed.`;
+}
 var AGENT_MODES = ["ask", "auto", "agent"];
 var DEFAULT_AGENT_MODE = "auto";
 function toAgentMode(raw) {
@@ -1319,6 +1349,154 @@ function trim(output) {
   ].join("");
 }
 
+// packages/core/src/calls.ts
+var TOOL_OUTPUT_KEPT = 8e3;
+function keepOutput(text) {
+  const clean = text.replace(/\s+$/, "");
+  return clean.length <= TOOL_OUTPUT_KEPT ? clean : `${clean.slice(0, TOOL_OUTPUT_KEPT)}
+\u2026 trimmed here.`;
+}
+async function executeCall(call, env) {
+  let preview;
+  if (isWriteTool(call.name) || isExecTool(call.name)) {
+    try {
+      preview = previewTool(call, env.toolCtx);
+      env.step({ status: "running", preview });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      env.step({ status: "error", detail: message });
+      return { id: call.id, content: message, isError: true };
+    }
+  } else {
+    env.step({ status: "running" });
+  }
+  if (needsApproval(env.mode, call)) {
+    env.step({ status: "awaiting", preview });
+    const ok = env.approve ? await env.approve(call, preview) : false;
+    if (env.signal.aborted) return "aborted";
+    if (!ok) {
+      env.step({ status: "skipped", preview });
+      return {
+        id: call.id,
+        content: env.approve ? "The learner declined this, so nothing was done. Do not retry it. Explain what you would have done and why, and let them decide what to do next." : "This needed the learner to approve it and labd is running unattended, so nothing was done. Say what you would have done; do not try another way round it."
+      };
+    }
+  }
+  if (env.signal.aborted) return "aborted";
+  try {
+    const content = await runTool(call, env.toolCtx);
+    if (isWriteTool(call.name)) {
+      const input = call.input;
+      env.wrote(String(input.path ?? input.from ?? ""));
+    }
+    if (isExecTool(call.name)) env.ran(String(call.input.command ?? ""));
+    env.step({ status: isWriteTool(call.name) ? "applied" : "done", preview, output: keepOutput(content) });
+    return { id: call.id, content };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    env.step({ status: "error", preview, detail: message });
+    return { id: call.id, content: message, isError: true };
+  }
+}
+
+// packages/core/src/helper.ts
+var STALL_ROUNDS = 3;
+var LABEL_MAX = 80;
+function helperLabel(call) {
+  const description = call.input.description;
+  const text = typeof description === "string" ? description.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim() : "";
+  return text ? text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}\u2026` : text : "helper";
+}
+async function runHelper(call, env) {
+  const task = call.input.task;
+  if (typeof task !== "string" || !task.trim()) {
+    return { id: call.id, content: "spawn_agent needs a `task`: the complete brief for the helper.", isError: true };
+  }
+  const label2 = helperLabel(call);
+  const helper = { id: call.id, label: label2 };
+  const ask = env.approve;
+  const capabilities = subAgentCapabilities(env.capabilities);
+  const conversationId = subAgentConversationId(env.sessionId, call.id);
+  let wire = [{ role: "user", text: subAgentBrief(task) }];
+  let report = "";
+  const asked = /* @__PURE__ */ new Set();
+  let stalled = 0;
+  for (; ; ) {
+    let text = "";
+    const calls = [];
+    let needTools = false;
+    let failure = null;
+    const stream = env.client.stream(
+      {
+        protocol: PROTOCOL_VERSION,
+        messages: wire,
+        context: buildContext(env.root),
+        capabilities,
+        ...conversationId ? { conversationId } : {},
+        ...env.effort ? { effort: env.effort } : {}
+      },
+      env.signal
+    );
+    for await (const event of stream) {
+      if (env.signal.aborted) break;
+      if (event.type === "text") text += event.text;
+      else if (event.type === "tool_call") calls.push(event.call);
+      else if (event.type === "need_tools") needTools = true;
+      else if (event.type === "error") failure = event.message;
+    }
+    if (env.signal.aborted) return "aborted";
+    if (failure) {
+      const sofar = report ? `
+
+What it had reported before that:
+${subAgentReport(report)}` : "";
+      return { id: call.id, content: `The helper stopped: ${failure}${sofar}`, isError: true };
+    }
+    wire = [...wire, { role: "assistant", text, ...calls.length ? { toolCalls: calls } : {} }];
+    if (text.trim()) report = text;
+    if (!needTools || !calls.length) break;
+    const fresh = calls.some((c) => {
+      if (isWriteTool(c.name) || isExecTool(c.name)) return true;
+      const key = `${c.name}:${JSON.stringify(c.input)}`;
+      if (asked.has(key)) return false;
+      asked.add(key);
+      return true;
+    });
+    stalled = fresh ? 0 : stalled + 1;
+    if (stalled >= STALL_ROUNDS) {
+      report = `${report}
+
+(The helper kept asking for what it had already read, so it was stopped.)`.trim();
+      break;
+    }
+    const results = [];
+    for (const c of calls) {
+      if (env.signal.aborted) return "aborted";
+      if (isAgentTool(c.name)) {
+        results.push({ id: c.id, content: "A helper cannot start helpers of its own. Do this part yourself.", isError: true });
+        continue;
+      }
+      const outcome = await executeCall(c, {
+        mode: env.mode(),
+        // Routed to this call's row: two helpers can run commands at once.
+        toolCtx: { ...env.toolCtx, onCommandOutput: (line) => env.toolCtx.onCommandOutput?.(line, `${call.id}/${c.id}`) },
+        signal: env.signal,
+        approve: ask ? (pending, preview) => ask(pending, preview, label2) : void 0,
+        step: (s) => env.step({ ...s, call: c, helper }),
+        wrote: env.wrote,
+        ran: env.ran
+      });
+      if (outcome === "aborted") {
+        env.step({ call: c, helper, status: "skipped", detail: "Stopped." });
+        return "aborted";
+      }
+      results.push(outcome);
+    }
+    wire = [...wire, { role: "tool", results }];
+  }
+  return { id: call.id, content: subAgentReport(report) };
+}
+
 // packages/core/src/agent.ts
 var CLI_CAPABILITIES = [
   "read_file",
@@ -1328,18 +1506,15 @@ var CLI_CAPABILITIES = [
   "create_file",
   "move_file",
   "delete_file",
-  "run_command"
+  "run_command",
+  // Helpers run here, in this process, on the same rules - see helper.ts.
+  "spawn_agent"
 ];
-var TOOL_OUTPUT_KEPT = 8e3;
-function keepOutput(text) {
-  const clean = text.replace(/\s+$/, "");
-  return clean.length <= TOOL_OUTPUT_KEPT ? clean : `${clean.slice(0, TOOL_OUTPUT_KEPT)}
-\u2026 trimmed here.`;
-}
-var STALL_ROUNDS = 3;
+var STALL_ROUNDS2 = 3;
 var COMPACT_AT = 75;
 async function runTurn(question, opts) {
-  const { session, client, ui, mode } = opts;
+  const { session, client, ui } = opts;
+  const modeNow = () => opts.currentMode?.() ?? opts.mode;
   const turnId = randomUUID2();
   const controller = new AbortController();
   opts.signal?.addEventListener("abort", () => controller.abort(), { once: true });
@@ -1348,10 +1523,17 @@ async function runTurn(question, opts) {
     checkpoints: opts.checkpoints,
     turn: { sessionId: session.id, turnId },
     commandTimeoutMs: opts.commandTimeoutMs ?? 12e4,
-    onCommandOutput: (line) => ui.commandOutput?.(line)
+    onCommandOutput: (line2, key) => ui.commandOutput?.(line2, key)
   };
   session.add({ kind: "user", text: question, ...opts.attachments?.length ? { attachments: opts.attachments.map((a) => ({ path: a.path })) } : {} }, turnId);
   const result = { text: "", turnId, wrote: [], ran: [], aborted: false };
+  const ask = ui.approve;
+  let line = Promise.resolve();
+  const approve = ask ? (call, preview, helper) => {
+    const answer = line.then(() => controller.signal.aborted ? false : ask(call, preview, helper));
+    line = answer.catch(() => void 0);
+    return answer;
+  } : void 0;
   const asked = /* @__PURE__ */ new Set();
   let stalled = 0;
   for (let round = 0; ; round++) {
@@ -1430,20 +1612,79 @@ async function runTurn(question, opts) {
       return true;
     });
     stalled = fresh ? 0 : stalled + 1;
-    if (stalled >= STALL_ROUNDS) {
+    if (stalled >= STALL_ROUNDS2) {
       ui.error(
         `labd asked for the same things ${stalled} rounds running, so it stopped rather than keep going round. Tell it which file to start in, or ask for a narrower piece of this.`
       );
       session.add({ kind: "tool", results: calls.map((c) => stopped(c, "error", "Stopped: labd was repeating itself.")) }, turnId);
       return result;
     }
-    const results = [];
-    for (const call of calls) {
-      if (controller.signal.aborted) {
-        results.push(stopped(call));
-        continue;
+    const results = new Array(calls.length);
+    const working = [];
+    try {
+      let helpers = 0;
+      calls.forEach((call, at2) => {
+        if (!isAgentTool(call.name)) return;
+        const label2 = helperLabel(call);
+        if (helpers++ >= MAX_SUBAGENTS) {
+          const why = `Only ${MAX_SUBAGENTS} helpers can run at once, so this one was not started. Do it yourself, or start it once the others have reported.`;
+          ui.tool({ call, status: "error", detail: why });
+          results[at2] = { id: call.id, content: why, isError: true };
+          return;
+        }
+        ui.tool({ call, status: "running", detail: label2 });
+        working.push(
+          runHelper(call, {
+            client,
+            root: opts.root,
+            mode: modeNow,
+            effort: opts.effort,
+            capabilities: CLI_CAPABILITIES,
+            sessionId: session.id,
+            toolCtx,
+            signal: controller.signal,
+            approve,
+            step: (step) => ui.tool(step),
+            wrote: (path) => result.wrote.push(path),
+            ran: (command) => result.ran.push(command)
+          }).catch((err) => ({
+            id: call.id,
+            content: `The helper failed: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true
+          })).then((outcome) => {
+            if (outcome === "aborted") {
+              results[at2] = stopped(call);
+              return;
+            }
+            results[at2] = outcome;
+            ui.tool({ call, status: outcome.isError ? "error" : "done", detail: label2, output: keepOutput(outcome.content) });
+          })
+        );
+      });
+      for (const [at2, call] of calls.entries()) {
+        if (isAgentTool(call.name)) continue;
+        if (controller.signal.aborted) {
+          results[at2] = stopped(call);
+          continue;
+        }
+        const outcome = await executeCall(call, {
+          mode: modeNow(),
+          // Output names its row, so it cannot land in a helper's command
+          // running at the same moment.
+          toolCtx: { ...toolCtx, onCommandOutput: (line2) => ui.commandOutput?.(line2, call.id) },
+          signal: controller.signal,
+          approve,
+          step: (step) => ui.tool({ ...step, call }),
+          wrote: (path) => result.wrote.push(path),
+          ran: (command) => result.ran.push(command)
+        });
+        results[at2] = outcome === "aborted" ? stopped(call) : outcome;
       }
-      results.push(await runOne(call));
+      await Promise.all(working);
+    } catch (err) {
+      controller.abort();
+      await Promise.allSettled(working);
+      throw err;
     }
     session.add({ kind: "tool", results }, turnId);
     if (controller.signal.aborted) {
@@ -1455,52 +1696,6 @@ async function runTurn(question, opts) {
     ui.tool({ call, status, detail: why });
     return { id: call.id, content: why, isError: true };
   }
-  async function runOne(call) {
-    let preview;
-    if (isWriteTool(call.name) || isExecTool(call.name)) {
-      try {
-        preview = previewTool(call, toolCtx);
-        ui.tool({ call, status: "running", preview });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        ui.tool({ call, status: "error", detail: message });
-        return { id: call.id, content: message, isError: true };
-      }
-    } else {
-      ui.tool({ call, status: "running" });
-    }
-    if (needsApproval(mode, call)) {
-      ui.tool({ call, status: "awaiting", preview });
-      const ok = ui.approve ? await ui.approve(call, preview) : false;
-      if (controller.signal.aborted) return stopped(call);
-      if (!ok) {
-        ui.tool({ call, status: "skipped", preview });
-        return {
-          id: call.id,
-          content: ui.approve ? "The learner declined this, so nothing was done. Do not retry it. Explain what you would have done and why, and let them decide what to do next." : "This needed the learner to approve it and labd is running unattended, so nothing was done. Say what you would have done; do not try another way round it."
-        };
-      }
-    }
-    try {
-      const content = await runTool(call, toolCtx);
-      if (isWriteTool(call.name)) {
-        const input = call.input;
-        result.wrote.push(String(input.path ?? input.from ?? ""));
-      }
-      if (isExecTool(call.name)) result.ran.push(String(call.input.command ?? ""));
-      ui.tool({
-        call,
-        status: isWriteTool(call.name) ? "applied" : "done",
-        preview,
-        output: keepOutput(content)
-      });
-      return { id: call.id, content };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      ui.tool({ call, status: "error", preview, detail: message });
-      return { id: call.id, content: message, isError: true };
-    }
-  }
 }
 async function compact(opts) {
   const controller = new AbortController();
@@ -1898,9 +2093,16 @@ function setColor(value) {
   on = value;
 }
 var wrap = (open, close = "0") => (text) => on ? `${ESC}[${open}m${text}${ESC}[${close}m` : text;
+function lightBackground() {
+  const bg = Number(process.env.COLORFGBG?.split(";").at(-1));
+  return bg === 7 || bg === 15;
+}
 var paint = {
-  /** labd's accent. 214 is the nearest xterm cube entry to the brand orange. */
-  accent: wrap("38;5;214"),
+  /**
+   * labd's accent. 214 is the nearest xterm cube entry to the brand orange.
+   * Closes the foreground only, so it can sit inside a `band` without ending it.
+   */
+  accent: wrap("38;5;214", "39"),
   bold: wrap("1", "22"),
   dim: wrap("2", "22"),
   muted: wrap("90"),
@@ -1912,6 +2114,11 @@ var paint = {
   /** For the one place a background is worth it: the cursor cell in the box. */
   invert: wrap("7", "27")
 };
+function band(text, visible, width) {
+  if (!on) return text;
+  const bg = lightBackground() ? "48;5;254" : "48;5;236";
+  return `${ESC}[${bg}m${text}${" ".repeat(Math.max(0, width - visible))}${ESC}[49m`;
+}
 function stripColor(text) {
   return text.replace(new RegExp(`${ESC}\\[[0-9;]*m`, "g"), "");
 }
@@ -2073,7 +2280,8 @@ var LABELS = {
   create_file: "Create",
   move_file: "Move",
   delete_file: "Delete",
-  run_command: "Run"
+  run_command: "Run",
+  spawn_agent: "Helper"
 };
 function approvalCard(preview, call, mode, width) {
   const out = [""];
@@ -3203,6 +3411,17 @@ var Transcript = class {
     this.entries.push(entry);
     return entry;
   }
+  /**
+   * Move a block to the bottom. For an approval card, which must stay the last
+   * thing on screen while it waits: a helper that keeps working adds rows below
+   * it, and a card pushed up past the fold is one approved without being read.
+   */
+  toEnd(entry) {
+    const at2 = this.entries.indexOf(entry);
+    if (at2 === -1 || at2 === this.entries.length - 1) return;
+    this.entries.splice(at2, 1);
+    this.entries.push(entry);
+  }
   /** Say a block changed, so its cached lines are dropped on the next render. */
   touch(entry) {
     entry.version++;
@@ -3281,7 +3500,10 @@ function renderBlock(block, width) {
   switch (block.kind) {
     case "user":
       return block.text.split("\n").flatMap(
-        (line, i) => wrapPlain(line, inner - 2).map((piece, j) => i === 0 && j === 0 ? `${paint.accent(">")} ${piece}` : `  ${piece}`)
+        (line, i) => wrapPlain(line, inner - 2).map((piece, j) => {
+          const text = i === 0 && j === 0 ? `${paint.accent(">")} ${piece}` : `  ${piece}`;
+          return band(text, visibleWidth(text), inner);
+        })
       );
     case "assistant":
       return [];
@@ -3295,7 +3517,10 @@ function renderBlock(block, width) {
       return out;
     }
     case "approval": {
-      const out = approvalCard(block.preview, block.call, block.mode, inner);
+      const out = [
+        ...block.helper ? [`  ${paint.accent("from a helper:")} ${paint.muted(block.helper)}`] : [],
+        ...approvalCard(block.preview, block.call, block.mode, inner)
+      ];
       out.push(
         block.answer === null ? `  ${paint.yellow("y")} ${paint.muted("to allow  \xB7")} ${paint.yellow("n")} ${paint.muted("or esc to decline")}` : `  ${block.answer === "allowed" ? paint.green("allowed") : paint.muted("declined")}`
       );
@@ -4469,11 +4694,18 @@ function fileTag(line) {
   return { at: at2, partial };
 }
 function label(step) {
-  return `${step.call.name.replace(/_/g, " ")} ${detail(step)}`;
+  if (step.call.name === "spawn_agent") return `working with a helper: ${detail(step)}`;
+  const own = `${step.call.name.replace(/_/g, " ")} ${detail(step)}`;
+  return step.helper ? `${step.helper.label}: ${own}` : own;
+}
+function stepKey(step) {
+  return step.helper ? `${step.helper.id}/${step.call.id}` : step.call.id;
 }
 function detail(step) {
   const input = step.call.input;
-  return String(input.why ?? input.path ?? input.from ?? input.query ?? "");
+  if (step.call.name === "spawn_agent") return String(input.description ?? "helper");
+  const own = String(input.why ?? input.path ?? input.from ?? input.query ?? "");
+  return step.helper ? `\u21B3 ${step.helper.label} \xB7 ${own}` : own;
 }
 function verbatim(call) {
   const i = call.input;
@@ -4489,6 +4721,10 @@ function verbatim(call) {
       return `${str("from")} \u2192 ${str("to")}`;
     case "list_dir":
       return str("path") || "/";
+    // The whole brief: what the helper was actually told is what a learner
+    // wants when its report surprises them.
+    case "spawn_agent":
+      return str("task");
     default:
       return str("path");
   }
@@ -4580,6 +4816,8 @@ async function runInteractive(runtime) {
       abort = new AbortController();
       const markdown = new MarkdownStream(renderer.contentWidth);
       let opened = false;
+      let held = null;
+      const say = (line) => held ? held.push(line) : renderer.print(line);
       const ui = {
         text(chunk) {
           const ready = markdown.push(chunk);
@@ -4601,7 +4839,7 @@ async function runInteractive(runtime) {
             }
           }
           if (step.status === "running" || step.status === "awaiting") {
-            startSpinner(label(step));
+            if (!held) startSpinner(label(step));
             return;
           }
           for (const line of toolBlock(
@@ -4611,19 +4849,27 @@ async function runInteractive(runtime) {
             { input: verbatim(step.call), output: step.output ?? step.detail },
             renderer.contentWidth
           )) {
-            renderer.print(line);
+            say(line);
           }
         },
-        async approve(call, preview) {
+        async approve(call, preview, helper) {
           stopSpinner();
+          if (helper) renderer.print(`  ${paint.accent("from a helper:")} ${paint.muted(helper)}`);
           for (const line of approvalCard(preview, call, state.mode, renderer.contentWidth)) {
             renderer.print(line);
           }
           const verb = call.name === "run_command" ? "run this command" : "apply this change";
-          const answer = await prompt.read(`${verb}? [y/N]`);
-          const ok = answer.kind === "line" && /^y(es)?$/i.test(answer.text.trim());
-          renderer.print(`  ${ok ? paint.green("allowed") : paint.muted("declined")}`);
-          return ok;
+          held = [];
+          try {
+            const answer = await prompt.read(`${verb}? [y/N]`);
+            const ok = answer.kind === "line" && /^y(es)?$/i.test(answer.text.trim());
+            renderer.print(`  ${ok ? paint.green("allowed") : paint.muted("declined")}`);
+            return ok;
+          } finally {
+            const waiting = held;
+            held = null;
+            for (const line of waiting) renderer.print(line);
+          }
         },
         error(message) {
           stopSpinner();
@@ -4634,7 +4880,7 @@ async function runInteractive(runtime) {
           if (info2.credits) state.credits = info2.credits;
         },
         commandOutput(line) {
-          renderer.print(paint.dim(`  | ${line.replace(/\n/g, "\n  | ")}`));
+          say(paint.dim(`  | ${line.replace(/\n/g, "\n  | ")}`));
         }
       };
       startSpinner("thinking");
@@ -4817,6 +5063,14 @@ async function runScreen(runtime, opts) {
   const history = new History();
   const state = {
     mode: runtime.settings.mode,
+    /**
+     * The mode the running turn is held to, when shift+tab has moved `mode` up
+     * to `agent` mid-answer. Going up does not apply until the next question -
+     * a habit keypress must not let the very next command run unasked - while
+     * going down applies at once, being the safe direction. Null when the turn
+     * simply follows `mode`.
+     */
+    heldMode: null,
     effort: runtime.settings.effort,
     context: null,
     credits: null,
@@ -4952,7 +5206,8 @@ async function runScreen(runtime, opts) {
       `${paint.muted(basename5(runtime.root))}${runtime.branch ? `  ${paint.muted(runtime.branch)}` : ""}`,
       paint.dim(`session ${session}`)
     ].join(paint.dim("  \xB7  "));
-    const mode = state.mode === "agent" ? paint.red(paint.bold("agent")) : state.mode === "auto" ? paint.accent("auto") : paint.muted("ask");
+    const shown = state.mode === "agent" ? paint.red(paint.bold("agent")) : state.mode === "auto" ? paint.accent("auto") : paint.muted("ask");
+    const mode = state.heldMode ? `${shown}${paint.dim(" (next question)")}` : shown;
     const right = `${mode}${state.effort ? paint.dim(` \xB7 think ${state.effort}`) : ""} `;
     return spread(` ${left}`, right, width);
   }
@@ -4966,7 +5221,7 @@ async function runScreen(runtime, opts) {
     else if (state.popup) left = d("\u2191\u2193 move \xB7 tab/enter accept \xB7 esc close");
     else {
       const described = describe(editor.currentLine, runtime);
-      left = described.hint ? described.hint : d("enter send \xB7 shift+enter newline \xB7 / commands \xB7 @ files \xB7 pgup/pgdn scroll \xB7 ctrl+c stop \xB7 ctrl+d quit");
+      left = described.hint ? described.hint : d("enter send \xB7 shift+tab mode \xB7 / commands \xB7 @ files \xB7 pgup/pgdn scroll \xB7 ctrl+c stop \xB7 ctrl+d quit");
     }
     const bits = [];
     if (state.context) {
@@ -5050,6 +5305,7 @@ async function runScreen(runtime, opts) {
       if (key.sequence === "n" || key.sequence === "N" || key.name === "escape") return answerApproval(false);
       return;
     }
+    if (key.name === "tab" && key.shift) return cycleMode();
     if (key.ctrl && key.name === "d") {
       if (editor.isEmpty) quit();
       return;
@@ -5127,6 +5383,25 @@ async function runScreen(runtime, opts) {
     state.ctrlCAt = now;
     notice("press ctrl+c again to quit");
   }
+  function effectiveMode() {
+    return state.heldMode ?? state.mode;
+  }
+  function cycleMode() {
+    const previous = effectiveMode();
+    const next = AGENT_MODES[(AGENT_MODES.indexOf(state.mode) + 1) % AGENT_MODES.length];
+    state.mode = next;
+    const running = state.abort !== null;
+    state.heldMode = next === "agent" && running ? previous : null;
+    notice(`${next}: ${MODE_CAPTION[next]}`, 4e3);
+    if (next === "agent") {
+      note(
+        `  ${paint.red(paint.bold("agent"))} ${paint.muted(
+          running ? `- from your next question. This answer stays on ${previous}.` : "- commands now run without asking, and cannot be put back."
+        )}
+  ${paint.muted("For this session only. shift+tab again to leave it.")}`
+      );
+    }
+  }
   function answerApproval(ok) {
     const approval = state.approval;
     if (!approval) return;
@@ -5241,7 +5516,10 @@ async function runScreen(runtime, opts) {
     });
     if (outcome.farewell) state.farewell = outcome.farewell;
     if (outcome.exit) return quit();
-    if (outcome.mode) state.mode = outcome.mode;
+    if (outcome.mode) {
+      state.mode = outcome.mode;
+      state.heldMode = null;
+    }
     if (outcome.effort !== void 0) state.effort = outcome.effort;
     schedule();
   }
@@ -5254,6 +5532,7 @@ async function runScreen(runtime, opts) {
       ["shift+enter, ctrl+j, or a trailing \\", "new line"],
       ["/ and @", "commands and files, with a list"],
       ["tab", "complete"],
+      ["shift+tab", "next mode: ask, auto, agent"],
       ["pgup / pgdn, wheel", "scroll the transcript"],
       ["home / end", "top / bottom (with an empty box)"],
       ["esc", "close a list or dialog; jump back to the bottom"],
@@ -5336,6 +5615,7 @@ async function runScreen(runtime, opts) {
     }
   }
   async function ask(input) {
+    state.heldMode = null;
     transcript.add({ kind: "user", text: input });
     state.asked = true;
     state.answer = null;
@@ -5372,7 +5652,8 @@ async function runScreen(runtime, opts) {
           }
         }
         closeAnswer();
-        let entry = state.toolBlocks.get(step.call.id);
+        const key = stepKey(step);
+        let entry = state.toolBlocks.get(key);
         if (!entry) {
           entry = transcript.add({
             kind: "tool",
@@ -5382,7 +5663,11 @@ async function runScreen(runtime, opts) {
             input: verbatim(step.call) || void 0,
             live: []
           });
-          state.toolBlocks.set(step.call.id, entry);
+          state.toolBlocks.set(key, entry);
+          if (state.approval) {
+            transcript.toEnd(state.approval.entry);
+            if (viewport.follow) viewport.end();
+          }
         }
         entry.block.status = step.status;
         if (step.status !== "running" && step.status !== "awaiting") {
@@ -5393,10 +5678,10 @@ async function runScreen(runtime, opts) {
         if (step.status === "running" || step.status === "awaiting") setBusy(label(step));
         schedule();
       },
-      approve(call, preview) {
+      approve(call, preview, helper) {
         setBusy(null);
         closeAnswer();
-        const entry = transcript.add({ kind: "approval", call, preview, mode: state.mode, answer: null });
+        const entry = transcript.add({ kind: "approval", call, preview, helper, mode: effectiveMode(), answer: null });
         viewport.end();
         return new Promise((resolve2) => {
           state.approval = { entry, resolve: resolve2 };
@@ -5413,11 +5698,8 @@ async function runScreen(runtime, opts) {
         if (info2.credits) state.credits = info2.credits;
         schedule();
       },
-      commandOutput(line) {
-        let target;
-        for (const entry of state.toolBlocks.values()) {
-          if (entry.block.name === "run_command" && entry.block.status === "running") target = entry;
-        }
+      commandOutput(line, key) {
+        const target = key ? state.toolBlocks.get(key) : void 0;
         if (!target) return;
         target.block.live.push(...line.replace(/\n$/, "").split("\n"));
         transcript.touch(target);
@@ -5431,6 +5713,7 @@ async function runScreen(runtime, opts) {
         client: runtime.client,
         root: runtime.root,
         mode: state.mode,
+        currentMode: effectiveMode,
         checkpoints: runtime.checkpoints,
         effort: state.effort,
         attachments,
@@ -5453,6 +5736,7 @@ async function runScreen(runtime, opts) {
       transcript.add({ kind: "error", text: err instanceof Error ? err.message : String(err) });
     } finally {
       if (state.abort === abort) state.abort = null;
+      state.heldMode = null;
       if (state.approval) answerApproval(false);
       setBusy(null);
     }
@@ -5637,6 +5921,7 @@ async function runPrint(runtime, opts) {
         emit({
           type: "tool",
           name: step.call.name,
+          ...step.helper ? { helper: step.helper } : {},
           status: step.status,
           input: step.call.input,
           detail: step.detail,
@@ -5644,7 +5929,8 @@ async function runPrint(runtime, opts) {
           output: step.output
         });
       } else if (step.status !== "running") {
-        toStderr(`${paint.dim(`${step.call.name}: ${step.status}${step.detail ? ` - ${step.detail}` : ""}`)}
+        const who = step.helper ? `${step.helper.label} > ` : "";
+        toStderr(`${paint.dim(`${who}${step.call.name}: ${step.status}${step.detail ? ` - ${step.detail}` : ""}`)}
 `);
       }
       if (step.status === "skipped") declined = true;
@@ -5803,6 +6089,8 @@ async function runRpc(runtime) {
       tool(step) {
         notify("labd/tool", {
           name: step.call.name,
+          // Which helper made the call, when one did: its spawn_agent call id and name.
+          ...step.helper ? { helper: step.helper } : {},
           status: step.status,
           input: step.call.input,
           detail: step.detail,
@@ -5816,8 +6104,8 @@ async function runRpc(runtime) {
       done(info2) {
         notify("labd/done", info2);
       },
-      commandOutput(line) {
-        notify("labd/command_output", { line });
+      commandOutput(line, key) {
+        notify("labd/command_output", { line, ...key ? { key } : {} });
       },
       /**
        * Ask the host. A host that never answers gets a refusal after a timeout
@@ -5825,7 +6113,7 @@ async function runRpc(runtime) {
        * alternative is writing to someone's files because their integration was
        * asleep.
        */
-      approve(call, preview) {
+      approve(call, preview, helper) {
         return new Promise((resolve2) => {
           if (closed) return resolve2(false);
           const id = nextId++;
@@ -5836,7 +6124,7 @@ async function runRpc(runtime) {
             clearTimeout(timer);
             resolve2(approved);
           });
-          out({ jsonrpc: "2.0", id, method: "labd/approve", params: { call, preview } });
+          out({ jsonrpc: "2.0", id, method: "labd/approve", params: { call, preview, ...helper ? { helper } : {} } });
         });
       }
     };
@@ -5866,7 +6154,7 @@ async function runRpc(runtime) {
 }
 
 // packages/cli/src/index.ts
-var VERSION = true ? "0.5.0" : "0.0.0-dev";
+var VERSION = true ? "0.6.0" : "0.0.0-dev";
 async function main(argv) {
   const args = parse(argv);
   if (args.color !== void 0) setColor(args.color);