pi-fast-subagent 0.3.0 → 0.5.0

package/README.md

@@ -8,6 +8,8 @@ Runs subagents with `createAgentSession()` in same process instead of spawning `
 
 - Single mode: `{ agent, task }`
 - Parallel mode: `{ tasks: [...] }`
+- Background mode: `{ agent, task, background: true }` — fire-and-forget with poll/cancel
+- Slash commands for background job status + cancellation via selector UI
 - Per-call model override
 - User + project agent discovery
 - Project agents override user agents
@@ -61,22 +63,64 @@ You are code exploration specialist. Read relevant files, trace data flow, summa
 
 ## Slash Commands
 
-### `/agent`
+### `/fast-subagent:agent`
 
 List all available agents:
 
 ```
-/agent
+/fast-subagent:agent
 ```
 
 Show details for a specific agent (description, file path, model, tools, system prompt):
 
 ```
-/agent scout
+/fast-subagent:agent scout
 ```
 
 Tab-completion is supported for agent names.
 
+### `/fast-subagent:bg`
+
+Detach running foreground subagent to background:
+
+```
+/fast-subagent:bg fg_ab12cd34
+```
+
+Omit job id to list active foreground jobs:
+
+```
+/fast-subagent:bg
+```
+
+### `/fast-subagent:bg-status`
+
+Show active background subagents in selector UI. Arrow keys move selection. Enter shows full details for selected job.
+
+```
+/fast-subagent:bg-status
+```
+
+Show details for specific background job:
+
+```
+/fast-subagent:bg-status sa_ab12cd34
+```
+
+### `/fast-subagent:bg-cancel`
+
+Cancel running background subagent. Omit job id to open selector UI, then choose job with arrow keys.
+
+```
+/fast-subagent:bg-cancel
+```
+
+Cancel specific background job directly:
+
+```
+/fast-subagent:bg-cancel sa_ab12cd34
+```
+
 ## Usage
 
 ### List agents
@@ -125,6 +169,33 @@ subagent({
 })
 ```
 
+### Background (fire-and-forget)
+
+```js
+// Dispatch — returns job ID immediately
+subagent({ agent: "scout", task: "Explore src", background: true })
+// → { jobId: "sa_ab12cd34", status: "running" }
+
+// Poll — check result / progress
+subagent({ action: "poll", jobId: "sa_ab12cd34" })
+
+// Cancel
+subagent({ action: "cancel", jobId: "sa_ab12cd34" })
+
+// List all background jobs
+subagent({ action: "status" })
+
+// Detach a running foreground job to background
+subagent({ action: "detach", jobId: "fg_ab12cd34" })
+```
+
+## Roadmap
+
+Goal: keep this extension **small and focused** — aligned with pi's philosophy of minimal, composable tooling. No feature creep. Every addition must earn its place.
+
+- **UI/UX polish** — improve visibility of running subagents: clearer status lines, better progress feedback, agent name + task always visible during execution
+- **Background agents** — ala claude code
+
 ## Notes
 
 - Async/background isolation not supported in-process

package/background-job-manager.ts

@@ -0,0 +1,178 @@
+import { randomUUID } from "node:crypto";
+import type {
+  BackgroundHandleLike,
+  BackgroundJobManagerOptions,
+  BackgroundJobResult,
+  BackgroundSubagentJob,
+} from "./background-types.js";
+
+export type { BackgroundSubagentJob } from "./background-types.js";
+
+export class BackgroundJobManager {
+  private jobs = new Map<string, BackgroundSubagentJob>();
+  private evictionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private maxRunning: number;
+  private maxTotal: number;
+  private evictionMs: number;
+  private onJobComplete?: (job: BackgroundSubagentJob) => void;
+  private isShutdown = false;
+
+  constructor(options: BackgroundJobManagerOptions = {}) {
+    this.maxRunning = options.maxRunning ?? 10;
+    this.maxTotal = options.maxTotal ?? 50;
+    this.evictionMs = options.evictionMs ?? 5 * 60 * 1000;
+    this.onJobComplete = options.onJobComplete;
+  }
+
+  adoptHandle(
+    agentName: string,
+    task: string,
+    cwd: string,
+    handle: BackgroundHandleLike,
+    resultPromise: Promise<BackgroundJobResult>,
+  ): string {
+    handle.detach?.();
+
+    const abortController = new AbortController();
+    const onAbort = () => handle.abort();
+    abortController.signal.addEventListener("abort", onAbort, { once: true });
+
+    return this.attachJob(agentName, task, cwd, abortController, resultPromise.finally(() => {
+      abortController.signal.removeEventListener("abort", onAbort);
+    }));
+  }
+
+  cancel(id: string): "cancelled" | "not_found" | "already_done" {
+    const job = this.jobs.get(id);
+    if (!job) return "not_found";
+    if (job.status !== "running") return "already_done";
+
+    job.status = "cancelled";
+    job.completedAt = Date.now();
+    job.abortController.abort();
+    this.scheduleEviction(id);
+    return "cancelled";
+  }
+
+  getJob(id: string): BackgroundSubagentJob | undefined {
+    return this.jobs.get(id);
+  }
+
+  getRunningJobs(): BackgroundSubagentJob[] {
+    return [...this.jobs.values()].filter((job) => job.status === "running");
+  }
+
+  getAllJobs(): BackgroundSubagentJob[] {
+    return [...this.jobs.values()];
+  }
+
+  shutdown(): void {
+    this.isShutdown = true;
+    for (const timer of this.evictionTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.evictionTimers.clear();
+
+    for (const job of this.jobs.values()) {
+      if (job.status === "running") {
+        job.status = "cancelled";
+        job.completedAt = Date.now();
+        job.abortController.abort();
+      }
+    }
+  }
+
+  private attachJob(
+    agentName: string,
+    task: string,
+    cwd: string,
+    abortController: AbortController,
+    resultPromise: Promise<BackgroundJobResult>,
+  ): string {
+    if (this.getRunningJobs().length >= this.maxRunning) {
+      throw new Error(`Maximum concurrent background subagents reached (${this.maxRunning}).`);
+    }
+
+    if (this.jobs.size >= this.maxTotal) {
+      this.evictOldestCompleted();
+      if (this.jobs.size >= this.maxTotal) {
+        throw new Error(`Maximum total background subagent jobs reached (${this.maxTotal}).`);
+      }
+    }
+
+    const id = `sa_${randomUUID().slice(0, 8)}`;
+    const job: BackgroundSubagentJob = {
+      id,
+      agentName,
+      task,
+      cwd,
+      status: "running",
+      startedAt: Date.now(),
+      abortController,
+      promise: undefined as unknown as Promise<void>,
+    };
+
+    job.promise = resultPromise
+      .then((result) => {
+        if (job.status === "cancelled") {
+          this.scheduleEviction(id);
+          return;
+        }
+        job.status = result.exitCode === 0 ? "completed" : "failed";
+        job.completedAt = Date.now();
+        job.exitCode = result.exitCode;
+        job.resultSummary = result.summary;
+        job.error = result.error;
+        job.model = result.model;
+        this.scheduleEviction(id);
+        this.deliverResult(job);
+      })
+      .catch((error) => {
+        if (job.status === "cancelled") {
+          this.scheduleEviction(id);
+          return;
+        }
+        job.status = "failed";
+        job.completedAt = Date.now();
+        job.exitCode = 1;
+        job.error = error instanceof Error ? error.message : String(error);
+        this.scheduleEviction(id);
+        this.deliverResult(job);
+      });
+
+    this.jobs.set(id, job);
+    return id;
+  }
+
+  private deliverResult(job: BackgroundSubagentJob): void {
+    if (!this.onJobComplete) return;
+    queueMicrotask(() => this.onJobComplete?.(job));
+  }
+
+  private scheduleEviction(id: string): void {
+    if (this.isShutdown) return;
+    const existing = this.evictionTimers.get(id);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.evictionTimers.delete(id);
+      this.jobs.delete(id);
+    }, this.evictionMs);
+
+    this.evictionTimers.set(id, timer);
+  }
+
+  private evictOldestCompleted(): void {
+    let oldest: BackgroundSubagentJob | undefined;
+    for (const job of this.jobs.values()) {
+      if (job.status === "running") continue;
+      if (!oldest || job.startedAt < oldest.startedAt) oldest = job;
+    }
+    if (!oldest) return;
+
+    const timer = this.evictionTimers.get(oldest.id);
+    if (timer) clearTimeout(timer);
+    this.evictionTimers.delete(oldest.id);
+    this.jobs.delete(oldest.id);
+  }
+}

package/background-types.ts

@@ -0,0 +1,36 @@
+export type BackgroundJobStatus = "running" | "completed" | "failed" | "cancelled";
+
+export interface BackgroundSubagentJob {
+  id: string;
+  agentName: string;
+  task: string;
+  cwd: string;
+  status: BackgroundJobStatus;
+  startedAt: number;
+  completedAt?: number;
+  exitCode?: number;
+  resultSummary?: string;
+  error?: string;
+  model?: string;
+  abortController: AbortController;
+  promise: Promise<void>;
+}
+
+export interface BackgroundJobManagerOptions {
+  maxRunning?: number;
+  maxTotal?: number;
+  evictionMs?: number;
+  onJobComplete?: (job: BackgroundSubagentJob) => void;
+}
+
+export interface BackgroundJobResult {
+  summary: string;
+  exitCode: number;
+  error?: string;
+  model?: string;
+}
+
+export interface BackgroundHandleLike {
+  abort: () => void;
+  detach?: () => void;
+}

package/index.ts

@@ -8,6 +8,7 @@
  * Agent .md files are compatible with pi-subagents frontmatter format.
  */
 
+import { randomUUID } from "node:crypto";
 import type {
   AgentToolResult,
   AgentToolUpdateCallback,
@@ -15,8 +16,10 @@ import type {
   ExtensionContext,
   ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
+import { BackgroundJobManager } from "./background-job-manager.js";
+import type { BackgroundHandleLike, BackgroundJobResult, BackgroundSubagentJob } from "./background-types.js";
 import { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import { Key, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 import { truncateToVisualLines, keyHint } from "@mariozechner/pi-coding-agent";
 import {
   AuthStorage,
@@ -94,6 +97,9 @@ function summarizeToolArgs(toolName: unknown, toolInput: unknown): string {
 
 let _authStorage: ReturnType<typeof AuthStorage.create> | null = null;
 let _modelRegistry: ReturnType<typeof ModelRegistry.create> | null = null;
+let _bgManager: BackgroundJobManager | null = null;
+let _onBgJobComplete: ((job: BackgroundSubagentJob) => void) | null = null;
+let _setBgStatus: ((text: string | undefined) => void) | null = null;
 
 function getAuth() {
   if (!_authStorage) _authStorage = AuthStorage.create();
@@ -101,6 +107,27 @@ function getAuth() {
   return { authStorage: _authStorage, modelRegistry: _modelRegistry };
 }
 
+function getBgManager(): BackgroundJobManager {
+  if (!_bgManager) _bgManager = new BackgroundJobManager({
+    onJobComplete: (job) => _onBgJobComplete?.(job),
+  });
+  return _bgManager;
+}
+
+function refreshBgStatus(): void {
+  const running = getBgManager().getRunningJobs();
+  _setBgStatus?.(running.length > 0 ? `⧗ ${running.length} bg agent${running.length > 1 ? "s" : ""}` : undefined);
+}
+
+// ─── Foreground detach registry ───────────────────────────────────────────────
+
+interface ForegroundDetachEntry {
+  agentName: string;
+  task: string;
+  detach: () => string; // returns bg job id
+}
+const _fgJobs = new Map<string, ForegroundDetachEntry>();
+
 // ─── In-process runner ───────────────────────────────────────────────────────
 
 const MAX_DEPTH = 2;
@@ -142,6 +169,7 @@ interface SubagentDetails {
   running: boolean;
   elapsedMs?: number;
   model?: string;
+  backgroundJobId?: string;
   toolCalls: ToolCallEntry[];
 }
 
@@ -154,6 +182,26 @@ function formatDuration(ms: number): string {
   return m > 0 ? `${m}m ${rem}s` : `${rem}s`;
 }
 
+function summarizeTask(task: string, max = 60): string {
+  return task.length > max ? task.slice(0, max - 3) + "..." : task;
+}
+
+function formatBgJobSummary(job: BackgroundSubagentJob, now = Date.now()): string {
+  const dur = job.completedAt ? formatDuration(job.completedAt - job.startedAt) : formatDuration(now - job.startedAt);
+  return `${job.id} [${job.status}] ${job.agentName} · ${dur} · ${summarizeTask(job.task)}`;
+}
+
+function formatBgJobDetails(job: BackgroundSubagentJob, now = Date.now()): string {
+  const dur = job.completedAt ? formatDuration(job.completedAt - job.startedAt) : formatDuration(now - job.startedAt);
+  const lines = [`${job.id} [${job.status}] ${job.agentName} · ${dur}`, `Task: ${job.task}`];
+  if (job.model) lines.push(`Model: ${job.model}`);
+  if (job.status === "completed") lines.push(`\nResult:\n${job.resultSummary ?? "(no output)"}`);
+  if (job.status === "failed") lines.push(`\nError: ${job.error ?? "(unknown)"}`);
+  if (job.status === "cancelled") lines.push("\nCancelled.");
+  if (job.status === "running") lines.push("\nStill running.");
+  return lines.join("\n");
+}
+
 // Module-level depth counter — avoids process.env race conditions in parallel mode
 let _currentDepth = 0;
 
@@ -231,7 +279,10 @@ async function runAgent(
   const toolCalls: ToolCallEntry[] = [];
   const toolStartTimes = new Map<string, number>();
 
+  let done = false;
+
   function emitUpdate(): void {
+    if (done) return;
     onUpdate?.({
       content: [{ type: "text", text: currentDelta || lastOutput || "" }],
       details: {
@@ -354,6 +405,7 @@ async function runAgent(
     exitCode = 1;
     error = signal?.aborted ? "Aborted" : e instanceof Error ? e.message : String(e);
   } finally {
+    done = true;
     clearInterval(heartbeat);
     unsubscribe();
     session.dispose();
@@ -436,14 +488,22 @@ const SubagentParams = Type.Object({
     Type.Number({ description: "Max parallel concurrency (default: 4)", default: 4 }),
   ),
 
+  // Background
+  background: Type.Optional(Type.Boolean({ description: "Run in background, returns job ID immediately" })),
+  jobId: Type.Optional(Type.String({ description: "Job ID for poll/cancel" })),
+
   // Management
   action: Type.Optional(
     Type.Union(
       [
         Type.Literal("list"),
         Type.Literal("get"),
+        Type.Literal("status"),
+        Type.Literal("poll"),
+        Type.Literal("cancel"),
+        Type.Literal("detach"),
       ],
-      { description: "'list' to discover agents, 'get' to inspect one agent" },
+      { description: "'list'/'get' for agents, 'status' for bg jobs, 'poll'/'cancel' for a specific job, 'detach' to move a foreground job to background" },
     ),
   ),
   agentScope: Type.Optional(
@@ -457,9 +517,65 @@ const SubagentParams = Type.Object({
 // ─── Extension entry point ────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
+  // ─── Status keys ────────────────────────────────────────────────────────────────────
+  const BG_STATUS_KEY = "fast-subagent-bg";
+  const FG_STATUS_KEY = "fast-subagent-fg";
+
+  // ─── Background job lifecycle ─────────────────────────────────────────────────────
+  _onBgJobComplete = (job) => {
+    refreshBgStatus();
+    const elapsed = job.completedAt ? ((job.completedAt - job.startedAt) / 1000).toFixed(1) : "?";
+    const statusEmoji = job.status === "completed" ? "✓" : "✗";
+    const taskPreview = job.task.length > 80 ? `${job.task.slice(0, 80)}…` : job.task;
+    const output = job.status === "completed"
+      ? (job.resultSummary ?? "(no output)")
+      : `Error: ${job.error ?? "unknown"}`;
+    const modelInfo = job.model ? ` · ${job.model}` : "";
+    pi.sendUserMessage(
+      [
+        `**Background subagent ${statusEmoji}: ${job.id}** (${job.agentName}, ${elapsed}s${modelInfo})`,
+        `> ${taskPreview}`,
+        ``,
+        output,
+      ].join("\n"),
+      { deliverAs: "followUp" },
+    );
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    _setBgStatus = (text) => ctx.ui.setStatus(BG_STATUS_KEY, text);
+  });
+
+  pi.on("session_shutdown", async () => {
+    getBgManager().shutdown();
+    _bgManager = null;
+    _setBgStatus = null;
+  });
+
+  // ─── Ctrl+Shift+B — move foreground subagent to background ─────────────────────────
+  pi.registerShortcut(Key.ctrlShift("b"), {
+    description: "Move foreground subagent to background",
+    handler: async (ctx) => {
+      const entry = [..._fgJobs.values()][0];
+      if (!entry) {
+        ctx.ui.notify("No foreground subagent running.", "info");
+        return;
+      }
+      try {
+        const bgJobId = entry.detach();
+        ctx.ui.notify(
+          `Moved ${entry.agentName} to background as ${bgJobId}. Completion will be announced automatically.`,
+          "info",
+        );
+      } catch (e) {
+        ctx.ui.notify(e instanceof Error ? e.message : String(e), "error");
+      }
+    },
+  });
+
   // ─── /agent slash command ─────────────────────────────────────────────────
-  pi.registerCommand("agent", {
-    description: "List available subagents. Usage: /agent [name] — show details for a specific agent.",
+  pi.registerCommand("fast-subagent:agent", {
+    description: "List available subagents. Usage: /fast-subagent:agent [name] — show details for a specific agent.",
     getArgumentCompletions(prefix: string) {
       const agents = discoverAgents(process.cwd());
       return agents
@@ -518,11 +634,132 @@ export default function (pi: ExtensionAPI) {
         }
       }
       lines.push("");
-      lines.push("Tip: /agent <name> for details · Add .md files to .pi/agents/ to create new agents");
+      lines.push("Tip: /fast-subagent:agent <name> for details · Add .md files to .pi/agents/ to create new agents");
       ctx.ui.notify(lines.join("\n"), "info");
     },
   });
 
+  // ─── /bg slash command ────────────────────────────────────────────────────
+  pi.registerCommand("fast-subagent:bg", {
+    description: "Move a running foreground subagent to background. Shortcut: Ctrl+Shift+B. Usage: /fast-subagent:bg [fg-job-id] — omit ID to list active foreground jobs.",
+    getArgumentCompletions(_prefix: string) {
+      return [..._fgJobs.keys()].map((id) => ({ value: id, label: id }));
+    },
+    async handler(args: string, ctx) {
+      const id = args.trim();
+      if (!id) {
+        if (_fgJobs.size === 0) {
+          ctx.ui.notify("No active foreground subagent jobs.", "info");
+          return;
+        }
+        const lines = ["Active foreground jobs (use /fast-subagent:bg <id> to detach):"];
+        for (const [fgId, entry] of _fgJobs) {
+          lines.push(`  ${fgId}  ${entry.agentName}: ${summarizeTask(entry.task)}`);
+        }
+        ctx.ui.notify(lines.join("\n"), "info");
+        return;
+      }
+      const entry = _fgJobs.get(id);
+      if (!entry) {
+        ctx.ui.notify(`Foreground job "${id}" not found (already done or invalid).`, "warning");
+        return;
+      }
+      const bgJobId = entry.detach();
+      ctx.ui.notify(
+        `Moved to background: ${bgJobId}\nTo check status, ask me to poll job ${bgJobId}.`,
+        "info",
+      );
+    },
+  });
+
+  // ─── /bg-status slash command ─────────────────────────────────────────────
+  pi.registerCommand("fast-subagent:bg-status", {
+    description: "Show active background subagents. Usage: /fast-subagent:bg-status [sa-job-id] — omit ID to open selector.",
+    getArgumentCompletions(prefix: string) {
+      return getBgManager().getAllJobs()
+        .filter((job) => job.id.startsWith(prefix))
+        .map((job) => ({ value: job.id, label: formatBgJobSummary(job) }));
+    },
+    async handler(args: string, ctx) {
+      const id = args.trim();
+      if (id) {
+        const job = getBgManager().getJob(id);
+        if (!job) {
+          ctx.ui.notify(`Background job "${id}" not found.`, "warning");
+          return;
+        }
+        ctx.ui.notify(formatBgJobDetails(job), "info");
+        return;
+      }
+
+      const jobs = getBgManager().getRunningJobs().sort((a, b) => b.startedAt - a.startedAt);
+      if (jobs.length === 0) {
+        ctx.ui.notify("No active background subagent jobs.", "info");
+        return;
+      }
+
+      const options = jobs.map((job) => formatBgJobSummary(job));
+      const selected = await ctx.ui.select("Active background subagents", options);
+      if (!selected) return;
+
+      const jobId = selected.split(" ")[0] ?? "";
+      const job = getBgManager().getJob(jobId);
+      if (!job) {
+        ctx.ui.notify(`Background job "${jobId}" not found.`, "warning");
+        return;
+      }
+      ctx.ui.notify(formatBgJobDetails(job), "info");
+    },
+  });
+
+  // ─── /bg-cancel slash command ─────────────────────────────────────────────
+  pi.registerCommand("fast-subagent:bg-cancel", {
+    description: "Cancel running background subagent. Usage: /fast-subagent:bg-cancel [sa-job-id] — omit ID to choose with arrow keys.",
+    getArgumentCompletions(prefix: string) {
+      return getBgManager().getRunningJobs()
+        .filter((job) => job.id.startsWith(prefix))
+        .map((job) => ({ value: job.id, label: formatBgJobSummary(job) }));
+    },
+    async handler(args: string, ctx) {
+      let jobId = args.trim();
+
+      if (!jobId) {
+        const jobs = getBgManager().getRunningJobs().sort((a, b) => b.startedAt - a.startedAt);
+        if (jobs.length === 0) {
+          ctx.ui.notify("No running background subagent jobs to cancel.", "info");
+          return;
+        }
+
+        const options = jobs.map((job) => formatBgJobSummary(job));
+        const selected = await ctx.ui.select("Cancel background subagent", options);
+        if (!selected) return;
+        jobId = selected.split(" ")[0] ?? "";
+      }
+
+      const job = getBgManager().getJob(jobId);
+      if (!job) {
+        ctx.ui.notify(`Background job "${jobId}" not found.`, "warning");
+        return;
+      }
+      if (job.status !== "running") {
+        ctx.ui.notify(`Background job "${jobId}" already ${job.status}.`, "info");
+        return;
+      }
+
+      const confirmed = await ctx.ui.confirm(
+        "Cancel background subagent?",
+        `${formatBgJobSummary(job)}\n\nTask:\n${job.task}`,
+      );
+      if (!confirmed) return;
+
+      const result = getBgManager().cancel(jobId);
+      const msg = result === "cancelled" ? `Background job "${jobId}" cancelled.`
+        : result === "already_done" ? `Background job "${jobId}" already completed.`
+        : `Background job "${jobId}" not found.`;
+      ctx.ui.notify(msg, result === "cancelled" ? "info" : "warning");
+    },
+  });
+
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
@@ -614,6 +851,7 @@ export default function (pi: ExtensionAPI) {
       }
 
       function statusLine(): string {
+        if (details.backgroundJobId) return `moved to background · ${details.backgroundJobId}`;
         if (details.running) {
           const parts: string[] = ["running"];
           if (details.usage?.turns) parts.push(`${details.usage.turns} turn${details.usage.turns > 1 ? "s" : ""}`);
@@ -701,6 +939,8 @@ export default function (pi: ExtensionAPI) {
               : "";
           const statusWithHint = [status, expandHint].filter(Boolean).join("  ");
           if (statusWithHint) out.push(truncateToWidth(statusWithHint, width, "..."));
+          if (details.running && !details.backgroundJobId)
+            out.push(truncateToWidth(theme.fg("dim", "Ctrl+Shift+B: move to background"), width, "..."));
 
           return out;
         },
@@ -721,7 +961,7 @@ export default function (pi: ExtensionAPI) {
       };
 
       // ── Management: list ──────────────────────────────────────────────────────
-      if (params.action === "list" || (!params.agent && !params.tasks)) {
+      if (params.action === "list" || (!params.action && !params.agent && !params.tasks)) {
         if (agents.length === 0) {
           return {
             content: [{
@@ -750,20 +990,130 @@ export default function (pi: ExtensionAPI) {
         return { content: [{ type: "text", text: info }] };
       }
 
+      // ── Background status ───────────────────────────────────────────────────
+      if (params.action === "status") {
+        const jobs = getBgManager().getAllJobs();
+        if (jobs.length === 0) return { content: [{ type: "text", text: "No background jobs." }] };
+        const lines = jobs.map((j) => {
+          const dur = j.completedAt ? formatDuration(j.completedAt - j.startedAt) : formatDuration(Date.now() - j.startedAt);
+          return `${j.id} [${j.status}] ${j.agentName} · ${dur} · ${j.task.length > 50 ? j.task.slice(0, 47) + "..." : j.task}`;
+        });
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
+      // ── Background poll ────────────────────────────────────────────────────────
+      if (params.action === "poll") {
+        if (!params.jobId) return { content: [{ type: "text", text: "Provide jobId to poll." }] };
+        const job = getBgManager().getJob(params.jobId);
+        if (!job) return { content: [{ type: "text", text: `Job ${params.jobId} not found (completed and evicted, or invalid).` }] };
+        const dur = job.completedAt ? formatDuration(job.completedAt - job.startedAt) : formatDuration(Date.now() - job.startedAt);
+        const parts = [`${job.id} [${job.status}] ${job.agentName} · ${dur}`, `Task: ${job.task}`];
+        if (job.status === "completed") parts.push(`\nResult:\n${job.resultSummary ?? "(no output)"}`);
+        if (job.status === "failed") parts.push(`\nError: ${job.error ?? "(unknown)"}`);
+        if (job.status === "running") parts.push("Still running — poll again later.");
+        return { content: [{ type: "text", text: parts.join("\n") }] };
+      }
+
+      // ── Background cancel ──────────────────────────────────────────────────────
+      if (params.action === "cancel") {
+        if (!params.jobId) return { content: [{ type: "text", text: "Provide jobId to cancel." }] };
+        const result = getBgManager().cancel(params.jobId);
+        const msg = result === "cancelled" ? `Job ${params.jobId} cancelled.`
+          : result === "already_done" ? `Job ${params.jobId} already completed.`
+          : `Job ${params.jobId} not found.`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+
+      // ── Foreground → background detach ────────────────────────────────────────
+      if (params.action === "detach") {
+        if (!params.jobId) return { content: [{ type: "text", text: "Provide jobId (fg_xxxxx) to detach." }] };
+        const fgEntry = _fgJobs.get(params.jobId);
+        if (!fgEntry) return { content: [{ type: "text", text: `Foreground job "${params.jobId}" not found (already completed or invalid).` }] };
+        const bgJobId = fgEntry.detach();
+        return { content: [{ type: "text", text: `Moved to background: ${bgJobId}\nTo check status, ask me to poll job ${bgJobId}.` }] };
+      }
+
       // ── Single mode ───────────────────────────────────────────────────────────
       if (params.agent && params.task) {
         const { agent, error } = findAgent(params.agent);
         if (error || !agent) return { content: [{ type: "text", text: error ?? "Not found" }] };
 
-        const result = await runAgent(
-          agent,
-          params.task,
-          cwd,
-          params.model,
-          signal,
-          onUpdate,
+        // Background dispatch — fire and forget
+        if (params.background) {
+          const bgAbort = new AbortController();
+          const handle: BackgroundHandleLike = { abort: () => bgAbort.abort() };
+          const resultPromise: Promise<BackgroundJobResult> = runAgent(
+            agent, params.task, cwd, params.model, bgAbort.signal, undefined
+          ).then((r) => ({ summary: r.output, exitCode: r.exitCode, error: r.error, model: r.model }));
+          const jobId = getBgManager().adoptHandle(agent.name, params.task, cwd, handle, resultPromise);
+          return { content: [{ type: "text", text: `Background job started: ${jobId}\nTo check status, ask me to poll job ${jobId}.` }] };
+        }
+
+        // Foreground run with detach support
+        const fgId = `fg_${randomUUID().slice(0, 8)}`;
+        const agentAbort = new AbortController();
+        const forwardAbort = () => agentAbort.abort();
+        signal?.addEventListener("abort", forwardAbort, { once: true });
+
+        let detachResolveFn: ((bgJobId: string) => void) | null = null;
+        const detachPromise = new Promise<string>((resolve) => { detachResolveFn = resolve; });
+
+        // Wrap onUpdate so detach can stop forwarding updates to the parent
+        // agent's listener (which becomes invalid once execute() returns).
+        let forwardUpdates = true;
+        const wrappedOnUpdate: OnUpdate | undefined = onUpdate
+          ? (partial) => { if (forwardUpdates) onUpdate(partial); }
+          : undefined;
+
+        const agentRunPromise: Promise<RunResult> = runAgent(
+          agent, params.task, cwd, params.model, agentAbort.signal, wrappedOnUpdate,
         );
 
+        // Derived promise for the bg manager (used only if we detach)
+        const bgResultPromise: Promise<BackgroundJobResult> = agentRunPromise
+          .then((r) => ({ summary: r.output, exitCode: r.exitCode, error: r.error, model: r.model }));
+
+        _fgJobs.set(fgId, {
+          agentName: agent.name,
+          task: params.task,
+          detach: () => {
+            forwardUpdates = false;
+            signal?.removeEventListener("abort", forwardAbort);
+            const bgHandle: BackgroundHandleLike = { abort: () => agentAbort.abort() };
+            const bgJobId = getBgManager().adoptHandle(agent.name, params.task, cwd, bgHandle, bgResultPromise);
+            refreshBgStatus();
+            detachResolveFn?.(bgJobId);
+            return bgJobId;
+          },
+        });
+
+        ctx.ui.setStatus(FG_STATUS_KEY, `${agent.name} running · Ctrl+Shift+B to move to background`);
+
+        let runResult: RunResult | null = null;
+        const outcome = await Promise.race([
+          agentRunPromise.then((r) => { runResult = r; return "done" as const; }),
+          detachPromise.then(() => "detached" as const),
+        ]).finally(() => {
+          _fgJobs.delete(fgId);
+          signal?.removeEventListener("abort", forwardAbort);
+          ctx.ui.setStatus(FG_STATUS_KEY, undefined);
+        });
+
+        if (outcome === "detached") {
+          const bgJobId = await detachPromise; // already resolved — instant
+          return {
+            content: [{ type: "text", text: `Moved to background: ${bgJobId}. Completion will be announced automatically.` }],
+            details: {
+              task: params.task,
+              usage: { input: 0, output: 0, cost: 0, turns: 0 },
+              running: false,
+              backgroundJobId: bgJobId,
+              toolCalls: [],
+            } satisfies SubagentDetails,
+          };
+        }
+
+        const result = runResult!;
         return {
           content: [{ type: "text", text: getFinalText(result) }],
           details: {

package/package.json

@@ -1,14 +1,27 @@
 {
   "name": "pi-fast-subagent",
-  "version": "0.3.0",
-  "description": "In-process subagent delegation for pi with single, parallel, and chain modes",
+  "version": "0.5.0",
+  "description": "In-process subagent delegation for pi with single, parallel, and background modes",
   "type": "module",
   "keywords": [
     "pi-package",
     "pi",
+    "pi-extension",
     "subagent",
     "agents",
-    "extension"
+    "extension",
+    "delegation",
+    "parallel",
+    "concurrent",
+    "in-process",
+    "fast",
+    "coding-agent",
+    "ai-agent",
+    "llm",
+    "task-runner",
+    "scout",
+    "workflow",
+    "automation"
   ],
   "homepage": "https://github.com/tuansondinh/pi-fast-subagent#readme",
   "repository": {
@@ -21,6 +34,8 @@
   "files": [
     "index.ts",
     "agents.ts",
+    "background-job-manager.ts",
+    "background-types.ts",
     "agents/*.md",
     "README.md"
   ],