@saadnvd1/agent-os 0.3.521 → 0.3.523

package/components/Chat/BackgroundTasks.tsx

@@ -13,6 +13,7 @@ import {
   X,
 } from "lucide-react";
 import type { ChatItem } from "@/lib/chat/events";
+import { outputTail } from "@/lib/chat/background";
 import { formatElapsed } from "@/lib/chat/elapsed";
 import { cn } from "@/lib/utils";
 import { useNow } from "./useNow";
@@ -22,6 +23,8 @@ type Task = Extract<ChatItem, { kind: "task" }>;
 // Finished tasks stay listed this long, then the chip clears.
 const RECENT_MS = 5 * 60 * 1000;
 const POLL_MS = 2000;
+// Running tasks whose last line of output is followed while the tray is open.
+const TAILED = 5;
 
 function TaskIcon({ task }: { task: Task }) {
   if (task.status === "running")
@@ -49,16 +52,23 @@ function TaskRow({
   task,
   now,
   output,
+  tail,
+  highlight,
   onStop,
   onLoadOutput,
 }: {
   task: Task;
   now: number;
   output: string | null | undefined;
+  // Follows its output for the line under its name.
+  tail: boolean;
+  // Brought here from the call it came from.
+  highlight: boolean;
   onStop: () => void;
   onLoadOutput: (taskId: string) => void;
 }) {
-  const [open, setOpen] = useState(false);
+  const [open, setOpen] = useState(highlight);
+  const rowRef = useRef<HTMLDivElement>(null);
   const running = task.status === "running";
   const { taskId } = task;
   const outputRef = useRef<HTMLPreElement>(null);
@@ -69,18 +79,32 @@ function TaskRow({
     if (el) el.scrollTop = el.scrollHeight;
   }, [output]);
 
-  // While open, keep the output fresh for as long as the task runs.
   useEffect(() => {
-    if (!open) return;
+    if (!highlight) return;
+    setOpen(true);
+    rowRef.current?.scrollIntoView({ block: "nearest", behavior: "smooth" });
+  }, [highlight]);
+
+  // While open (or tailed), keep the output fresh for as long as it runs.
+  useEffect(() => {
+    if (!open && !(tail && running)) return;
     onLoadOutput(taskId);
     if (!running) return;
     const t = setInterval(() => onLoadOutput(taskId), POLL_MS);
     return () => clearInterval(t);
-  }, [open, running, taskId, onLoadOutput]);
+  }, [open, tail, running, taskId, onLoadOutput]);
 
   const took = formatElapsed((task.endedAt ?? now) - task.createdAt);
+  const line =
+    running && !open ? (outputTail(output) ?? task.lastToolName) : null;
   return (
-    <div className="rounded-lg">
+    <div
+      ref={rowRef}
+      className={cn(
+        "rounded-lg transition-colors duration-700",
+        highlight && "bg-foreground/[0.05]"
+      )}
+    >
       <div className="flex min-h-11 items-center gap-2 px-1.5 md:min-h-9">
         <button
           type="button"
@@ -113,6 +137,11 @@ function TaskRow({
           </button>
         )}
       </div>
+      {line && (
+        <p className="text-muted-foreground truncate pr-2 pb-1.5 pl-9 font-mono text-[11px]">
+          {line}
+        </p>
+      )}
       {open && (
         <div className="space-y-1 pb-2 pl-7">
           {task.summary && task.summary !== task.description && (
@@ -143,16 +172,24 @@ function TaskRow({
 export function BackgroundTasks({
   items,
   outputs,
+  reveal,
   onStop,
   onLoadOutput,
 }: {
   items: ChatItem[];
+  // A task to open the tray on, from the call that became it.
+  reveal?: { taskId: string; at: number } | null;
   outputs: Record<string, string | null>;
   onStop: (taskId: string) => void;
   onLoadOutput: (taskId: string) => void;
 }) {
   const [open, setOpen] = useState(false);
-  const tasks = items.filter((i): i is Task => i.kind === "task");
+  const [pulse, setPulse] = useState(false);
+  const [lit, setLit] = useState<string | null>(null);
+  // One still blocking its call isn't in the background yet.
+  const tasks = items.filter(
+    (i): i is Task => i.kind === "task" && i.backgrounded !== false
+  );
   const running = tasks.filter((t) => t.status === "running" && !t.ambient);
   const now = useNow(running.length > 0);
   const shown = tasks
@@ -162,6 +199,29 @@ export function BackgroundTasks({
         Number(b.status === "running") - Number(a.status === "running") ||
         b.createdAt - a.createdAt
     );
+  const failed = shown.filter((t) => t.status === "failed").length;
+
+  // A task arriving gives the chip one soft pulse.
+  const count = running.length;
+  const seen = useRef(count);
+  useEffect(() => {
+    const more = count > seen.current;
+    seen.current = count;
+    if (!more) return;
+    setPulse(true);
+    const t = setTimeout(() => setPulse(false), 700);
+    return () => clearTimeout(t);
+  }, [count]);
+
+  // Asked to show a task: open the tray on it for a moment.
+  useEffect(() => {
+    if (!reveal) return;
+    setOpen(true);
+    setLit(reveal.taskId);
+    const t = setTimeout(() => setLit(null), 1200);
+    return () => clearTimeout(t);
+  }, [reveal]);
+
   if (!shown.length) return null;
 
   return (
@@ -170,24 +230,30 @@ export function BackgroundTasks({
         type="button"
         onClick={() => setOpen(!open)}
         className={cn(
-          "text-muted-foreground hover:text-foreground hover:bg-foreground/[0.05] flex h-9 items-center gap-1.5 rounded-lg px-2 text-xs md:h-7",
-          running.length && "text-primary"
+          "text-muted-foreground hover:text-foreground hover:bg-foreground/[0.05] flex h-9 items-center gap-1.5 rounded-lg px-2 text-xs transition-colors duration-500 md:h-7",
+          running.length && "text-primary",
+          !running.length && failed > 0 && "text-destructive",
+          pulse && "bg-foreground/[0.08]"
         )}
       >
         <Layers className="h-3.5 w-3.5" />
         {running.length
           ? `${running.length} running in background`
-          : `${shown.length} background task${shown.length === 1 ? "" : "s"}`}
+          : failed
+            ? `${failed} failed in background`
+            : `${shown.length} finished in background`}
         <ChevronRight
           className={cn("h-3 w-3 transition-transform", open && "rotate-90")}
         />
       </button>
       {open && (
         <div className="bg-foreground/[0.025] mt-1 max-h-80 overflow-y-auto rounded-xl px-1 py-1">
-          {shown.map((t) => (
+          {shown.map((t, i) => (
             <TaskRow
               key={t.id}
               task={t}
+              tail={i < TAILED}
+              highlight={lit === t.taskId}
               now={now}
               output={outputs[t.taskId]}
               onStop={() => onStop(t.taskId)}

package/components/Chat/ChatPanel.tsx

@@ -42,6 +42,8 @@ import { useFreshStartQuery } from "@/data/fresh-start";
 import { QuoteButton } from "./QuoteButton";
 import { ToolBodies, ToolGroup } from "./Tools";
 import { RowState, RowStore } from "./rowState";
+import { Background, type BackgroundValue } from "./background";
+import { backgroundKey } from "@/lib/chat/background";
 import { FindBar } from "./FindBar";
 import { FIND_EVENT, isFindKey, useFind } from "./useFind";
 import { McpServers } from "./McpServers";
@@ -253,6 +255,9 @@ export function ChatPanel({
     undoPreview,
     clearUndo,
     stopTask,
+    canBackground,
+    backgroundTask,
+    movingToBackground,
     loadTaskOutput,
     taskOutputs,
     queue,
@@ -380,6 +385,54 @@ export function ChatPanel({
     }),
     [toolBodies, requestToolBody, pinToolBody, connected]
   );
+  // The calls that block the turn and can be moved to the background.
+  const [reveal, setReveal] = useState<{ taskId: string; at: number } | null>(
+    null
+  );
+  const foregroundTasks = useMemo(() => {
+    const byTool = new Map<string, Extract<ChatItem, { kind: "task" }>>();
+    const byId = new Map<string, Extract<ChatItem, { kind: "task" }>>();
+    for (const i of tasks)
+      if (i.kind === "task") {
+        byId.set(i.taskId, i);
+        if (i.toolUseId) byTool.set(i.toolUseId, i);
+      }
+    return { byTool, byId };
+  }, [tasks]);
+  const background = useMemo<BackgroundValue>(
+    () => ({
+      supported: canBackground,
+      taskOfTool: (id) => foregroundTasks.byTool.get(id),
+      taskById: (id) => foregroundTasks.byId.get(id),
+      moving: movingToBackground,
+      send: backgroundTask,
+      reveal: (taskId) => setReveal({ taskId, at: Date.now() }),
+    }),
+    [canBackground, foregroundTasks, movingToBackground, backgroundTask]
+  );
+  // Ctrl+B moves every call that blocks the turn, from anywhere in this panel.
+  const canMove = useMemo(
+    () =>
+      canBackground &&
+      [...foregroundTasks.byId.values()].some(
+        (t) => t.status === "running" && t.backgrounded === false
+      ),
+    [canBackground, foregroundTasks]
+  );
+  const moveRef = useRef({ canMove, backgroundTask });
+  useEffect(() => {
+    moveRef.current = { canMove, backgroundTask };
+  });
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) return;
+      if (!backgroundKey(e, moveRef.current.canMove)) return;
+      e.preventDefault();
+      moveRef.current.backgroundTask();
+    };
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, []);
   const itemsById = useMemo(
     () => new Map(items.map((i) => [i.id, i])),
     [items]
@@ -482,41 +535,43 @@ export function ChatPanel({
       {orchestratorOf && <OrchestratorBar workspaceId={orchestratorOf} />}
       <div ref={scrollRef} className="relative min-h-0 flex-1">
         <RowState.Provider value={rowState}>
-          <ToolBodies.Provider value={bodies}>
-            <div
-              // A new conversation starts over, scrolled to the end.
-              key={sessionId}
-              ref={listRef}
-              onScroll={onListScroll}
-              onCopy={onCopy}
-              className="h-full overflow-y-auto overscroll-y-contain"
-            >
-              <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 pt-5 pb-4">
-                {hasMore && (
-                  <div className="text-muted-foreground flex min-h-11 items-center justify-center text-xs">
-                    {loadingOlder ? (
-                      <Loader2 className="h-4 w-4 animate-spin" />
-                    ) : (
-                      <button
-                        type="button"
-                        onClick={loadOlder}
-                        className="hover:text-foreground min-h-11 px-3"
-                      >
-                        Show earlier messages
-                      </button>
-                    )}
-                  </div>
-                )}
-                <SetupCard sessionId={sessionId} />
-                {blocks.length === 0 && !queue.length && (
-                  <p className="text-muted-foreground py-16 text-center text-sm">
-                    Ask anything to start.
-                  </p>
-                )}
+          <Background.Provider value={background}>
+            <ToolBodies.Provider value={bodies}>
+              <div
+                // A new conversation starts over, scrolled to the end.
+                key={sessionId}
+                ref={listRef}
+                onScroll={onListScroll}
+                onCopy={onCopy}
+                className="h-full overflow-y-auto overscroll-y-contain"
+              >
+                <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 pt-5 pb-4">
+                  {hasMore && (
+                    <div className="text-muted-foreground flex min-h-11 items-center justify-center text-xs">
+                      {loadingOlder ? (
+                        <Loader2 className="h-4 w-4 animate-spin" />
+                      ) : (
+                        <button
+                          type="button"
+                          onClick={loadOlder}
+                          className="hover:text-foreground min-h-11 px-3"
+                        >
+                          Show earlier messages
+                        </button>
+                      )}
+                    </div>
+                  )}
+                  <SetupCard sessionId={sessionId} />
+                  {blocks.length === 0 && !queue.length && (
+                    <p className="text-muted-foreground py-16 text-center text-sm">
+                      Ask anything to start.
+                    </p>
+                  )}
+                </div>
+                <TimelineRows blocks={blocks} actions={actions} />
               </div>
-              <TimelineRows blocks={blocks} actions={actions} />
-            </div>
-          </ToolBodies.Provider>
+            </ToolBodies.Provider>
+          </Background.Provider>
         </RowState.Provider>
         {find.open && (
           <FindBar
@@ -551,6 +606,7 @@ export function ChatPanel({
         />
         <BackgroundTasks
           items={tasks}
+          reveal={reveal}
           outputs={taskOutputs}
           onStop={stopTask}
           onLoadOutput={loadTaskOutput}

package/components/Chat/Subagent.tsx

@@ -4,7 +4,8 @@ import { Bot, ChevronRight } from "lucide-react";
 import type { ToolItem } from "@/lib/chat/group";
 import { cn } from "@/lib/utils";
 import { Markdown } from "./Markdown";
-import { StatusIcon, useToolBody } from "./Tools";
+import { ToolIcon, useToolBody } from "./Tools";
+import { BackgroundButton, BackgroundState } from "./background";
 import { useRowState } from "./rowState";
 
 // Its report, loaded when the card opens if the page left it out.
@@ -23,26 +24,30 @@ export function SubagentCard({ item }: { item: ToolItem }) {
   };
   return (
     <div className="bg-foreground/[0.025] rounded-xl px-2 py-1">
-      <button
-        type="button"
-        onClick={() => setOpen(!open)}
-        className="flex min-h-10 w-full items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
-      >
-        <ChevronRight
-          className={cn(
-            "text-muted-foreground h-3 w-3 shrink-0 transition-transform",
-            open && "rotate-90"
+      <div className="flex items-center gap-1">
+        <button
+          type="button"
+          onClick={() => setOpen(!open)}
+          className="flex min-h-10 min-w-0 flex-1 items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
+        >
+          <ChevronRight
+            className={cn(
+              "text-muted-foreground h-3 w-3 shrink-0 transition-transform",
+              open && "rotate-90"
+            )}
+          />
+          <Bot className="text-primary h-3.5 w-3.5 shrink-0" />
+          <span className="min-w-0 flex-1 truncate">{item.title}</span>
+          {input.subagent_type && (
+            <span className="text-muted-foreground hidden font-mono sm:inline">
+              {input.subagent_type}
+            </span>
           )}
-        />
-        <Bot className="text-primary h-3.5 w-3.5 shrink-0" />
-        <span className="min-w-0 flex-1 truncate">{item.title}</span>
-        {input.subagent_type && (
-          <span className="text-muted-foreground hidden font-mono sm:inline">
-            {input.subagent_type}
-          </span>
-        )}
-        <StatusIcon status={item.status} />
-      </button>
+          {item.backgroundTaskId ? <BackgroundState tool={item} /> : null}
+          <ToolIcon tool={item} />
+        </button>
+        <BackgroundButton tool={item} />
+      </div>
       {open && (
         <div className="space-y-3 px-1.5 pt-1 pb-2 pl-7">
           {input.prompt && (

package/components/Chat/Tools.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { createContext, useContext, useEffect } from "react";
-import { Check, ChevronRight, Loader2, Square, X } from "lucide-react";
+import { Check, ChevronRight, Layers, Loader2, Square, X } from "lucide-react";
 import type { FileDiff, ToolBody } from "@/lib/chat/events";
 import type { ToolItem } from "@/lib/chat/group";
 import { lineDiff, shortPath, type DiffLine } from "@/lib/chat/diff";
@@ -9,6 +9,7 @@ import { needsBody } from "@/lib/chat/bodyCache";
 import { cn } from "@/lib/utils";
 import { formatElapsed } from "@/lib/chat/elapsed";
 import { Highlighted } from "./Code";
+import { BackgroundButton, BackgroundState, useBackground } from "./background";
 import { useNow } from "./useNow";
 import { useRowState } from "./rowState";
 
@@ -48,6 +49,18 @@ export function StatusIcon({ status }: { status: ToolItem["status"] }) {
   return <Check className="text-muted-foreground/70 h-3.5 w-3.5 shrink-0" />;
 }
 
+// The status of a call; one moved to the background and still running there
+// shows as handed off instead of done.
+export function ToolIcon({ tool }: { tool: ToolItem }) {
+  const bg = useBackground();
+  const task = tool.backgroundTaskId
+    ? bg.taskById(tool.backgroundTaskId)
+    : undefined;
+  if (tool.backgroundTaskId && (!task || task.status === "running"))
+    return <Layers className="text-muted-foreground h-3.5 w-3.5 shrink-0" />;
+  return <StatusIcon status={tool.status} />;
+}
+
 const TONE: Record<DiffLine["op"], string> = {
   " ": "text-muted-foreground",
   "-": "bg-red-500/10 text-red-700 dark:text-red-300",
@@ -139,17 +152,24 @@ function ToolRow({ tool }: { tool: ToolItem }) {
   );
   return (
     <div data-item={tool.id}>
-      <button
-        type="button"
-        onClick={() => setOpen(!open)}
-        className="hover:bg-foreground/[0.04] flex min-h-9 w-full items-center gap-2 rounded-lg px-1.5 text-left md:min-h-7"
-      >
-        <StatusIcon status={tool.status} />
-        <span className="min-w-0 flex-1 truncate font-mono text-xs">
-          {tool.title}
-        </span>
-        <Elapsed tool={tool} />
-      </button>
+      <div className="hover:bg-foreground/[0.04] flex items-center gap-1 rounded-lg pr-1">
+        <button
+          type="button"
+          onClick={() => setOpen(!open)}
+          className="flex min-h-9 min-w-0 flex-1 items-center gap-2 px-1.5 text-left md:min-h-7"
+        >
+          <ToolIcon tool={tool} />
+          <span className="min-w-0 flex-1 truncate font-mono text-xs">
+            {tool.title}
+          </span>
+          {tool.backgroundTaskId ? (
+            <BackgroundState tool={tool} />
+          ) : (
+            <Elapsed tool={tool} />
+          )}
+        </button>
+        <BackgroundButton tool={tool} />
+      </div>
       {open && <ToolDetail tool={tool} />}
     </div>
   );
@@ -161,39 +181,50 @@ export function ToolGroup({ tools }: { tools: ToolItem[] }) {
   const failed = tools.filter((t) => t.status === "error").length;
   const stopped = tools.filter((t) => t.status === "stopped").length;
   const edits = tools.filter((t) => t.diff || t.hasDiff).length;
+  const moved = tools.filter((t) => t.backgroundTaskId).length;
   const [open, setOpen] = useRowState(`steps:${tools[0].id}`, false);
   const latest =
     tools.findLast((t) => t.status === "running") ?? tools[tools.length - 1];
   return (
     <div className="bg-foreground/[0.025] rounded-xl px-2 py-1">
-      <button
-        type="button"
-        onClick={() => setOpen(!open)}
-        className="text-muted-foreground hover:text-foreground flex min-h-10 w-full items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
-      >
-        <ChevronRight
-          className={cn(
-            "h-3 w-3 shrink-0 transition-transform",
-            open && "rotate-90"
+      <div className="flex items-center gap-1">
+        <button
+          type="button"
+          onClick={() => setOpen(!open)}
+          className="text-muted-foreground hover:text-foreground flex min-h-10 min-w-0 flex-1 items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
+        >
+          <ChevronRight
+            className={cn(
+              "h-3 w-3 shrink-0 transition-transform",
+              open && "rotate-90"
+            )}
+          />
+          {running ? (
+            <Loader2 className="text-primary h-3.5 w-3.5 shrink-0 animate-spin" />
+          ) : null}
+          <span className="min-w-0 flex-1 truncate">
+            {running
+              ? latest.title
+              : `${tools.length} step${tools.length === 1 ? "" : "s"}`}
+            {!running &&
+              edits > 0 &&
+              ` · ${edits} edit${edits === 1 ? "" : "s"}`}
+          </span>
+          {running && <Elapsed tool={latest} />}
+          {failed > 0 && (
+            <span className="text-destructive">{failed} failed</span>
           )}
-        />
-        {running ? (
-          <Loader2 className="text-primary h-3.5 w-3.5 shrink-0 animate-spin" />
-        ) : null}
-        <span className="min-w-0 flex-1 truncate">
-          {running
-            ? latest.title
-            : `${tools.length} step${tools.length === 1 ? "" : "s"}`}
-          {!running && edits > 0 && ` · ${edits} edit${edits === 1 ? "" : "s"}`}
-        </span>
-        {running && <Elapsed tool={latest} />}
-        {failed > 0 && (
-          <span className="text-destructive">{failed} failed</span>
-        )}
-        {stopped > 0 && failed === 0 && (
-          <span className="text-muted-foreground/70">stopped</span>
-        )}
-      </button>
+          {stopped > 0 && failed === 0 && (
+            <span className="text-muted-foreground/70">stopped</span>
+          )}
+          {!running && moved > 0 && (
+            <span className="text-muted-foreground/70">
+              {moved} in background
+            </span>
+          )}
+        </button>
+        {running && <BackgroundButton tool={latest} />}
+      </div>
       {open && (
         <div className="pb-1">
           {tools.map((t) => (

package/components/Chat/background.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import { Check, ChevronRight, Layers, Loader2, X } from "lucide-react";
+import type { ChatItem } from "@/lib/chat/events";
+import type { ToolItem } from "@/lib/chat/group";
+import { backgroundable } from "@/lib/chat/background";
+import { formatElapsed } from "@/lib/chat/elapsed";
+import { cn } from "@/lib/utils";
+import { useNow } from "./useNow";
+
+type Task = Extract<ChatItem, { kind: "task" }>;
+
+export interface BackgroundValue {
+  // The agent can move a call to the background.
+  supported: boolean;
+  // The task a tool call started, by the call's id.
+  taskOfTool: (toolUseId: string) => Task | undefined;
+  taskById: (taskId: string) => Task | undefined;
+  // Calls asked to move and not yet answered ("all" for the shortcut).
+  moving: ReadonlySet<string>;
+  send: (toolUseId?: string) => void;
+  // Opens the tray on that task.
+  reveal: (taskId: string) => void;
+}
+
+const none: BackgroundValue = {
+  supported: false,
+  taskOfTool: () => undefined,
+  taskById: () => undefined,
+  moving: new Set(),
+  send: () => {},
+  reveal: () => {},
+};
+
+export const Background = createContext<BackgroundValue>(none);
+export const useBackground = () => useContext(Background);
+
+// Moves the call it sits on to the background. Only there while that can
+// work: after a few seconds of running, so quick commands never show it.
+export function BackgroundButton({ tool }: { tool: ToolItem }) {
+  const bg = useBackground();
+  const running = tool.status === "running";
+  const now = useNow(running && bg.supported);
+  if (!backgroundable(bg.supported, tool, bg.taskOfTool(tool.id), now))
+    return null;
+  const moving = bg.moving.has(tool.id) || bg.moving.has("all");
+  return (
+    <button
+      type="button"
+      disabled={moving}
+      onClick={(e) => {
+        e.stopPropagation();
+        bg.send(tool.id);
+      }}
+      title="Run in background (Ctrl+B)"
+      aria-label="Run in background"
+      className="text-muted-foreground hover:text-foreground hover:bg-foreground/[0.06] animate-in fade-in flex h-11 shrink-0 items-center gap-1.5 rounded-md px-2.5 text-xs duration-150 disabled:opacity-70 md:h-7 md:px-2"
+    >
+      {moving ? (
+        <Loader2 className="h-3.5 w-3.5 animate-spin" />
+      ) : (
+        <Layers className="h-3.5 w-3.5" />
+      )}
+      <span className="hidden sm:inline">
+        {moving ? "Moving…" : "Background"}
+      </span>
+    </button>
+  );
+}
+
+// Where a call that went to the background stands: running there (opens
+// the tray on it), or how it ended.
+export function BackgroundState({ tool }: { tool: ToolItem }) {
+  const bg = useBackground();
+  const task = tool.backgroundTaskId
+    ? bg.taskById(tool.backgroundTaskId)
+    : undefined;
+  const running = task?.status === "running";
+  const now = useNow(running);
+  if (!tool.backgroundTaskId) return null;
+  if (!task || running)
+    return (
+      <button
+        type="button"
+        onClick={(e) => {
+          e.stopPropagation();
+          bg.reveal(tool.backgroundTaskId!);
+        }}
+        className="text-muted-foreground hover:text-foreground flex shrink-0 items-center gap-1 text-[11px]"
+      >
+        in background
+        <ChevronRight className="h-3 w-3" />
+      </button>
+    );
+  const failed = task.status === "failed";
+  const took = formatElapsed((task.endedAt ?? now) - task.createdAt);
+  return (
+    <span
+      className={cn(
+        "text-muted-foreground flex shrink-0 items-center gap-1 text-[11px]",
+        failed && "text-destructive"
+      )}
+    >
+      {failed ? <X className="h-3 w-3" /> : <Check className="h-3 w-3" />}
+      {task.status === "stopped"
+        ? "stopped in background"
+        : failed
+          ? "failed in background"
+          : "ran in background"}
+      <span className="font-mono tabular-nums">· {took}</span>
+    </span>
+  );
+}

package/data/chat/useChat.ts

@@ -2,6 +2,7 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
 import { markRunning } from "../statuses/stream";
 import type {
   ApprovalDecision,
@@ -21,6 +22,7 @@ import type {
 } from "@/lib/chat/events";
 import type { SearchResult } from "@/lib/chat/find";
 import { addBody, touchBody } from "@/lib/chat/bodyCache";
+import { backgroundFailure } from "@/lib/chat/background";
 
 // The index of the item with `id`, searched from the end: what changes is
 // almost always the latest.
@@ -164,6 +166,12 @@ export function useChat(
   const [taskOutputs, setTaskOutputs] = useState<Record<string, string | null>>(
     {}
   );
+  const [canBackground, setCanBackground] = useState(false);
+  // The calls asked to move to the background and not yet answered
+  // ("all" for the shortcut).
+  const [movingToBackground, setMovingToBackground] = useState<
+    ReadonlySet<string>
+  >(new Set());
   const onUndoneRef = useRef(onUndone);
   useEffect(() => {
     onUndoneRef.current = onUndone;
@@ -245,8 +253,28 @@ export function useChat(
           setModelState(m.model);
           setAccessState(m.access);
           setPlanState(m.plan);
+          setCanBackground(!!m.background);
         } else if (m.type === "context") {
           setContext(m.context);
+        } else if (m.type === "background_result") {
+          const key = m.toolUseId ?? "all";
+          setMovingToBackground((prev) => {
+            if (!prev.has(key)) return prev;
+            const next = new Set(prev);
+            next.delete(key);
+            return next;
+          });
+          const all = itemsRef.current;
+          const tool = all.find((i) => i.id === m.toolUseId);
+          const task = all.find(
+            (i) => i.kind === "task" && i.toolUseId === m.toolUseId
+          );
+          const message = backgroundFailure(
+            m,
+            tool?.kind === "tool" ? tool : undefined,
+            task?.kind === "task" ? task : undefined
+          );
+          if (message) toast(message, { duration: 2500 });
         } else if (m.type === "task_output") {
           setTaskOutputs((prev) => ({ ...prev, [m.taskId]: m.text }));
         } else if (m.type === "undo_preview") {
@@ -389,6 +417,15 @@ export function useChat(
     wsRef.current?.send(JSON.stringify({ type: "stop_task", taskId }));
   }, []);
 
+  // One call (or, with none given, every call that blocks the turn) goes to
+  // the background; the answer comes back as a toast only if it failed.
+  const backgroundTask = useCallback((toolUseId?: string) => {
+    const key = toolUseId ?? "all";
+    if (!wsRef.current) return;
+    setMovingToBackground((prev) => new Set(prev).add(key));
+    wsRef.current.send(JSON.stringify({ type: "background_task", toolUseId }));
+  }, []);
+
   const queueEdit = useCallback((id: string, text: string) => {
     wsRef.current?.send(JSON.stringify({ type: "queue_edit", id, text }));
   }, []);
@@ -496,6 +533,9 @@ export function useChat(
     undoPreview,
     clearUndo: () => setUndoPreview(null),
     stopTask,
+    canBackground,
+    backgroundTask,
+    movingToBackground,
     loadTaskOutput,
     taskOutputs,
     queue,

package/lib/chat/activity.ts

@@ -48,7 +48,9 @@ export function track(live: Live, e: WorkerEvent): void {
       a.tools.set(e.item.id, { label: e.item.title, since: e.item.createdAt });
     else a.tools.delete(e.item.id);
   } else if (e.type === "item" && e.item.kind === "task" && !e.item.ambient) {
-    if (e.item.status === "running") a.tasks.add(e.item.taskId);
+    // One still blocking its tool call is counted as that tool.
+    if (e.item.status === "running" && e.item.backgrounded !== false)
+      a.tasks.add(e.item.taskId);
     else a.tasks.delete(e.item.taskId);
   }
 }
@@ -65,7 +67,7 @@ export function restoreActivity(sessionId: string, state: ChatState) {
       activity.tools.set(i.id, { label: i.title, since: i.createdAt });
   }
   for (const i of runningItems(sessionId, "task"))
-    if (!i.ambient) activity.tasks.add(i.taskId);
+    if (!i.ambient && i.backgrounded !== false) activity.tasks.add(i.taskId);
   return activity;
 }
 

package/lib/chat/background.ts

@@ -0,0 +1,77 @@
+import type { ChatItem } from "./events";
+
+type Tool = Extract<ChatItem, { kind: "tool" }>;
+type Task = Extract<ChatItem, { kind: "task" }>;
+
+// A call has to have run this long before it's offered: a quick command
+// never flashes the button.
+export const BACKGROUND_AFTER_MS = 3000;
+
+// Whether a running call can be moved to the background now: the agent can
+// do it, and the call is the one blocking its turn.
+export function backgroundable(
+  supported: boolean,
+  tool: Pick<Tool, "status" | "createdAt">,
+  task: Pick<Task, "status" | "backgrounded"> | undefined,
+  now: number
+): boolean {
+  return (
+    supported &&
+    tool.status === "running" &&
+    task?.status === "running" &&
+    task.backgrounded === false &&
+    now - tool.createdAt >= BACKGROUND_AFTER_MS
+  );
+}
+
+// Ctrl+B, nothing else held, and only while there is something to move;
+// otherwise the key is left to the page.
+export function backgroundKey(
+  e: {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+    repeat?: boolean;
+    isComposing?: boolean;
+  },
+  available: boolean
+): boolean {
+  return (
+    available &&
+    e.key.toLowerCase() === "b" &&
+    e.ctrlKey &&
+    !(e.metaKey || e.altKey || e.shiftKey || e.repeat || e.isComposing)
+  );
+}
+
+// Errors that mean the agent never got the request.
+const UNREACHED = new Set(["unsupported", "unavailable", "timeout"]);
+
+// What to tell the reader when moving a call didn't happen; null when it did.
+export function backgroundFailure(
+  result: { ok: boolean; error?: string },
+  tool: Pick<Tool, "status"> | undefined,
+  task: Pick<Task, "backgrounded"> | undefined
+): string | null {
+  if (result.ok) return null;
+  if (result.error) {
+    return UNREACHED.has(result.error) || /went away/.test(result.error)
+      ? "Couldn't reach the agent. Try again"
+      : "Background tasks are turned off for this session";
+  }
+  if (tool && tool.status !== "running") return "That step already finished";
+  if (task?.backgrounded) return "Already running in the background";
+  return "Nothing to move to the background yet";
+}
+
+// The last line of a task's output that says anything.
+export function outputTail(text: string | null | undefined): string | null {
+  const lines = text?.split("\n") ?? [];
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line) return line;
+  }
+  return null;
+}

package/lib/chat/driver.ts

@@ -82,6 +82,10 @@ export interface ChatConversation {
   setPlan(plan: boolean): Promise<void>;
   respond(id: string, answer: ApprovalDecision): void;
   stopTask(taskId: string): Promise<void>;
+  // Moves a blocking call (a Bash command or a subagent) to the background,
+  // the one with that tool_use id or every one when none is given. False
+  // when there was nothing to move.
+  backgroundTask?(toolUseId?: string): Promise<boolean>;
   // Puts files back as they were before a message (dryRun: only say what).
   undo(checkpoint: string, dryRun: boolean): Promise<UndoResult>;
   close(): void;
@@ -99,6 +103,8 @@ export interface ChatDriver {
   // as Claude does. Without it, a turn's end is that point: a message sent
   // mid-turn joins the turn or is run before it ends.
   atRest?: boolean;
+  // Can move a blocking call to the background (backgroundTask).
+  backgroundTasks?: boolean;
   start(options: ChatStartOptions): ChatConversation;
   // What the agent offers in a folder (its commands, skills and models),
   // without starting a conversation. Ends whatever it started once `signal`

package/lib/chat/drivers/claude-mapper.ts

@@ -72,6 +72,9 @@ export type ClaudeMessage = {
   usage?: { tool_uses?: number };
   skip_transcript?: boolean;
   ambient?: boolean;
+  is_backgrounded?: boolean;
+  // task_updated.
+  patch?: { is_backgrounded?: boolean };
   // prompt_suggestion: the agent's guess at the next message.
   suggestion?: string;
   // session_state_changed.
@@ -98,6 +101,10 @@ export function toCommand(c: SdkCommand): ChatCommand {
 
 const now = () => Date.now();
 
+// "Command was manually backgrounded by user with ID: abc. Output is being
+// written to: ..." (also "running in background with ID: abc").
+const BACKGROUND_NOTICE = /^[^\n]*background(?:ed)?[^\n]*? with ID: (\w+)/;
+
 const INTERRUPT_NOTICE =
   /doesn't want to proceed with this tool use|Request interrupted by user/i;
 
@@ -220,6 +227,8 @@ export class ClaudeMapper {
               },
             ]
           : [];
+      case "task_updated":
+        return this.taskMoved(m);
       case "task_started":
       case "task_progress":
       case "task_notification":
@@ -264,6 +273,7 @@ export class ClaudeMapper {
       taskType: m.task_type ?? prev?.taskType,
       subagentType: m.subagent_type ?? prev?.subagentType,
       status: done ? (m.status ?? "completed") : "running",
+      backgrounded: m.is_backgrounded ?? prev?.backgrounded,
       endedAt: done ? now() : undefined,
       summary: m.summary ?? prev?.summary,
       outputFile: m.output_file ?? prev?.outputFile,
@@ -276,6 +286,16 @@ export class ClaudeMapper {
     return [{ type: "item", item }];
   }
 
+  // A foreground task moved to the background (or back).
+  private taskMoved(m: ClaudeMessage): DriverEvent[] {
+    const prev = m.task_id ? this.tasks.get(m.task_id) : undefined;
+    const to = m.patch?.is_backgrounded;
+    if (!prev || to === undefined || prev.backgrounded === to) return [];
+    const item: TaskItem = { ...prev, backgrounded: to };
+    this.tasks.set(prev.taskId, item);
+    return [{ type: "item", item }];
+  }
+
   // Items are created on their first text, so blocks that never send any
   // (hidden thinking, empty starts) never show up as empty bubbles.
   private stream(m: ClaudeMessage): DriverEvent[] {
@@ -401,20 +421,38 @@ export class ClaudeMapper {
       // An interrupt answers the running tool with a notice meant for the
       // model, not the reader.
       const stopped = b.is_error && INTERRUPT_NOTICE.test(text);
+      const moved = stopped ? undefined : this.movedTask(b.tool_use_id, text);
       const done = stopped
         ? { ...tool, status: "stopped" as const, output: undefined }
-        : {
-            ...tool,
-            status: b.is_error ? ("error" as const) : ("done" as const),
-            output: clipOutput(text),
-            endedAt: now(),
-          };
+        : moved
+          ? {
+              ...tool,
+              status: "done" as const,
+              // The notice is for the model; the task has the output.
+              output: undefined,
+              endedAt: now(),
+              backgroundTaskId: moved,
+            }
+          : {
+              ...tool,
+              status: b.is_error ? ("error" as const) : ("done" as const),
+              output: clipOutput(text),
+              endedAt: now(),
+            };
       this.tools.delete(b.tool_use_id);
       out.push({ type: "item", item: done });
     }
     return out;
   }
 
+  // The task a tool call became when it went to the background, from the
+  // task it started or, failing that, the notice it was answered with.
+  private movedTask(toolUseId: string, text: string): string | undefined {
+    for (const t of this.tasks.values())
+      if (t.toolUseId === toolUseId && t.backgrounded === true) return t.taskId;
+    return BACKGROUND_NOTICE.exec(text)?.[1];
+  }
+
   private result(m: ClaudeMessage): DriverEvent[] {
     const out: DriverEvent[] = [];
     // Tools still open when the turn ends were cut off.

package/lib/chat/drivers/claude.ts

@@ -129,6 +129,7 @@ export function writtenPlanFile(m: ClaudeMessage): string | undefined {
 
 export const claudeDriver: ChatDriver = {
   id: "claude",
+  backgroundTasks: true,
 
   // Claude Code reports its commands, skills and models while starting up,
   // before any message, so a short-lived start tells the composer what's
@@ -349,6 +350,9 @@ export const claudeDriver: ChatDriver = {
       async stopTask(taskId) {
         await q.stopTask(taskId);
       },
+      backgroundTask(toolUseId) {
+        return q.backgroundTasks(toolUseId);
+      },
       async undo(checkpoint, dryRun) {
         const r = await q.rewindFiles(checkpoint, { dryRun });
         return {

package/lib/chat/events.ts

@@ -165,6 +165,8 @@ export type ChatItem =
       deferred?: boolean;
       hasOutput?: boolean;
       hasDiff?: boolean;
+      // The task this call became when it was moved to the background.
+      backgroundTaskId?: string;
     })
   | (Base & {
       kind: "todos";
@@ -233,6 +235,9 @@ export type ChatItem =
       taskType?: string;
       subagentType?: string;
       status: "running" | "completed" | "failed" | "stopped";
+      // False while it still blocks the tool call that started it; unset
+      // means it runs in the background.
+      backgrounded?: boolean;
       endedAt?: number;
       summary?: string;
       outputFile?: string;
@@ -353,10 +358,18 @@ export type ChatServerMessage =
       access: ChatAccess;
       // Plan mode: on, or null when the session can't use it.
       plan: boolean | null;
+      // Whether a blocking call can be moved to the background.
+      background?: boolean;
     }
   | { type: "context"; context: ChatContext | null }
   | { type: "undo_preview"; from: string; preview: UndoPreview }
   | { type: "task_output"; taskId: string; text: string | null }
+  | {
+      type: "background_result";
+      toolUseId?: string;
+      ok: boolean;
+      error?: string;
+    }
   | { type: "undone"; from: string; text: string };
 
 // What a browser sends.
@@ -379,6 +392,7 @@ export type ChatClientMessage =
   | ({ type: "respond"; id: string } & ApprovalDecision)
   | { type: "undo"; from: string; dryRun?: boolean }
   | { type: "stop_task"; taskId: string }
+  | { type: "background_task"; toolUseId?: string }
   | { type: "task_output"; taskId: string }
   // Older items, from before a page's cursor.
   | { type: "history"; before: number }

package/lib/chat/registry.ts

@@ -35,6 +35,8 @@ export interface Live {
   canQueue?: boolean;
   // Whether it takes "fresh" (a fresh start the reader asked for).
   canFresh?: boolean;
+  // Whether it takes "background_task" (an older worker drops it).
+  canBackground?: boolean;
   // From an older build and idle: retired once its guess at the next
   // message is in, or this fires.
   retiring?: NodeJS.Timeout;

package/lib/chat/runner.ts

@@ -15,6 +15,7 @@ import type {
   ApprovalDecision,
   ChatContext,
   ChatImage,
+  ChatServerMessage,
   ChatState,
   Compacting,
   SentBy,
@@ -304,6 +305,7 @@ async function ensureLive(sessionId: string, spawn = true): Promise<Live> {
       canPlan: !!hello.caps?.includes("plan"),
       canQueue: !!hello.caps?.includes("queue"),
       canFresh: !!hello.caps?.includes("fresh"),
+      canBackground: !!hello.caps?.includes("background"),
     };
     // From an older build and busy, or running background work: it goes at
     // its next turn boundary, by itself if it can. Messages meanwhile wait
@@ -836,6 +838,24 @@ export function stopChatTask(sessionId: string, taskId: string): void {
   registry.live.get(sessionId)?.worker.command({ type: "stop_task", taskId });
 }
 
+// Moves a blocking call to the background and says how that went.
+export async function backgroundChatTask(
+  sessionId: string,
+  toolUseId: string | undefined,
+  reply: (m: ChatServerMessage) => void
+): Promise<void> {
+  const live = registry.live.get(sessionId);
+  const r = live?.canBackground
+    ? await live.worker.background(toolUseId)
+    : { error: "unavailable" };
+  reply({
+    type: "background_result",
+    toolUseId,
+    ok: !!r.ok,
+    ...(r.error && { error: r.error }),
+  });
+}
+
 export function chatTaskOutput(
   sessionId: string,
   taskId: string

package/lib/chat/settings.ts

@@ -75,6 +75,7 @@ export function emitCapabilities(session: Session, listener?: Listener): void {
     model: chatModel(session),
     access: session.chat_access,
     plan: canPlan(session) ? !!session.chat_plan : null,
+    background: chatDriverFor(session.agent_type)?.backgroundTasks === true,
   };
   if (listener) listener(m);
   else emit(session.id, m);

package/lib/chat/socket.ts

@@ -12,6 +12,7 @@ import {
   carryOutPlan,
   chatFileSuggestions,
   chatHistory,
+  backgroundChatTask,
   chatTaskOutput,
   chatToolBody,
   deleteQueuedChat,
@@ -183,6 +184,14 @@ function onChatMessage(
     run(carryOutPlan(sessionId, String(msg.id)));
   else if (msg.type === "respond") respondChat(sessionId, msg.id, msg);
   else if (msg.type === "stop_task") stopChatTask(sessionId, msg.taskId);
+  else if (msg.type === "background_task")
+    run(
+      backgroundChatTask(
+        sessionId,
+        typeof msg.toolUseId === "string" ? msg.toolUseId : undefined,
+        reply
+      )
+    );
   else if (msg.type === "task_output")
     reply({
       type: "task_output",

package/lib/chat/worker/client.ts

@@ -41,6 +41,11 @@ export class WorkerClient {
 
   private files = new Map<string, (r: FileSuggestion[] | null) => void>();
 
+  private backgrounds = new Map<
+    string,
+    (r: { ok?: boolean; error?: string }) => void
+  >();
+
   private constructor(
     private socket: net.Socket,
     private handlers: WorkerHandlers
@@ -55,6 +60,9 @@ export class WorkerClient {
       this.undos.clear();
       for (const f of this.files.values()) f(null);
       this.files.clear();
+      for (const b of this.backgrounds.values())
+        b({ error: "The chat worker went away" });
+      this.backgrounds.clear();
       handlers.onClose(this.detached);
     });
     socket.on("error", () => socket.destroy());
@@ -101,6 +109,11 @@ export class WorkerClient {
       else u?.reject(new Error(e.error ?? "Undo failed"));
       return;
     }
+    if (e.type === "background_result") {
+      this.backgrounds.get(e.reqId)?.({ ok: e.ok, error: e.error });
+      this.backgrounds.delete(e.reqId);
+      return;
+    }
     if (e.type === "files_result") {
       this.files.get(e.reqId)?.(e.files ?? null);
       this.files.delete(e.reqId);
@@ -121,6 +134,26 @@ export class WorkerClient {
     });
   }
 
+  // Moves a blocking call (or all of them) to the background: whether
+  // anything moved, or why not (an error, or no answer in time).
+  background(
+    toolUseId?: string,
+    timeoutMs = 5000
+  ): Promise<{ ok?: boolean; error?: string }> {
+    const reqId = randomUUID();
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.backgrounds.delete(reqId);
+        resolve({ error: "timeout" });
+      }, timeoutMs);
+      this.backgrounds.set(reqId, (r) => {
+        clearTimeout(timer);
+        resolve(r);
+      });
+      this.command({ type: "background_task", reqId, toolUseId });
+    });
+  }
+
   // The agent's own matches for an @mention; null when it can't say (an
   // older worker, an error, no answer in time).
   fileSuggestions(

package/lib/chat/worker/host.ts

@@ -712,6 +712,19 @@ export class ChatHost {
         return this.conversation.respond(cmd.id, cmd);
       case "stop_task":
         return this.conversation.stopTask(cmd.taskId);
+      case "background_task":
+        try {
+          if (!this.conversation.backgroundTask) throw new Error("unsupported");
+          const ok = await this.conversation.backgroundTask(cmd.toolUseId);
+          this.emit({ type: "background_result", reqId: cmd.reqId, ok });
+        } catch (error) {
+          this.emit({
+            type: "background_result",
+            reqId: cmd.reqId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+        return;
       case "undo":
         try {
           const result = await this.conversation.undo(

package/lib/chat/worker/main.ts

@@ -76,7 +76,7 @@ async function main(sessionId: string) {
         state: host.state,
         compacting: host.compactingNow,
         streaming: [...host.streaming.values()],
-        caps: ["plan", "queue", "retire", "fresh"],
+        caps: ["plan", "queue", "retire", "fresh", "background"],
       } satisfies WorkerEvent)}\n`
     );
     client.on(

package/lib/chat/worker/protocol.ts

@@ -55,6 +55,7 @@ export type WorkerCommand =
   | ({ type: "respond"; id: string } & ApprovalDecision)
   | { type: "undo"; reqId: string; checkpoint: string; dryRun: boolean }
   | { type: "stop_task"; taskId: string }
+  | { type: "background_task"; reqId: string; toolUseId?: string }
   // It runs an older build: it takes no new message into its agent (they
   // wait in the queue) and closes at its next turn boundary, so a current
   // worker resumes the conversation with today's tools.
@@ -99,6 +100,7 @@ export type WorkerEvent =
   // The agent's guess at the next message, or null once it's stale.
   | { type: "suggestion"; text: string | null }
   | { type: "undo_result"; reqId: string; result?: UndoResult; error?: string }
+  | { type: "background_result"; reqId: string; ok?: boolean; error?: string }
   | {
       type: "files_result";
       reqId: string;

package/lib/security/auth.ts

@@ -162,8 +162,18 @@ export function authorize(req: AuthRequest, policy: AuthPolicy): AuthResult {
 
 function decide(req: AuthRequest, policy: AuthPolicy): AuthResult {
   const trusted = req.tunnel ? null : networkTrust(req, policy);
-  if (trusted) return { ok: true, via: trusted };
   const token = readToken(req.headers);
+  if (trusted) {
+    // Identity only: network trust already decided access, so a token that
+    // is unknown, revoked or fails to resolve never turns this into a refusal.
+    let deviceId: string | undefined;
+    try {
+      deviceId = (token ? policy.lookup(token) : null)?.id;
+    } catch {}
+    return deviceId
+      ? { ok: true, via: trusted, deviceId }
+      : { ok: true, via: trusted };
+  }
   const device = token ? policy.lookup(token) : null;
   if (device) return { ok: true, via: "device", deviceId: device.id };
   // AGENTOS_AUTH=off is for a login proxy on this side of the network.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.521",
+  "version": "0.3.523",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"