@bermudi/pi-delegate 0.1.0 → 0.1.1

package/status.ts

@@ -0,0 +1,203 @@
+/**
+ * Background-activity visibility: footer status, settle warning, and
+ * session-replacement guards for live async tickets.
+ *
+ * Async tickets keep subagents running after the parent turn settles, but pi
+ * renders an idle session — nothing tells the human work is still in flight,
+ * and quitting silently kills it. This module owns the three signals that
+ * close that gap:
+ *
+ * 1. A persistent footer status (`ctx.ui.setStatus`) while any ticket is
+ *    active — the only always-on indicator that background subagents exist.
+ * 2. A one-shot warning notification at the first `agent_settled` with each
+ *    active ticket — the moment a user is most likely to assume everything
+ *    is done and close the session.
+ * 3. A confirm guard on the session-replacement paths pi lets extensions
+ *    cancel (`session_before_switch`, `session_before_fork`).
+ *
+ * Quit (Ctrl+C×2 / Ctrl+D / /quit) and /reload CANNOT be intercepted from an
+ * extension — `session_shutdown` is advisory, not cancellable. The footer
+ * status plus the exit/reload trace in extension.ts are the mitigations
+ * there.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ticketRegistry } from "./tickets.ts";
+import type { AsyncTicket } from "./types.ts";
+
+const STATUS_KEY = "delegate";
+
+export interface ActiveTicketSummary {
+  /** Tickets in a non-terminal state (running or cancelling). */
+  tickets: AsyncTicket[];
+  /** Progress rows still executing or queued across active tickets. */
+  activeSubagents: number;
+}
+
+/** Snapshot the live background work from the ticket registry. */
+export function activeTicketSummary(): ActiveTicketSummary {
+  const tickets: AsyncTicket[] = [];
+  let activeSubagents = 0;
+  for (const ticket of ticketRegistry.values()) {
+    if (ticket.status !== "running" && ticket.status !== "cancelling") continue;
+    tickets.push(ticket);
+    activeSubagents += ticket.progress.filter(
+      (p) => p.status === "running" || p.status === "pending",
+    ).length;
+  }
+  return { tickets, activeSubagents };
+}
+
+function plural(n: number, noun: string): string {
+  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+
+/** Footer status text, or undefined when nothing is active. */
+export function buildStatusText(
+  summary: ActiveTicketSummary,
+): string | undefined {
+  const { tickets, activeSubagents } = summary;
+  if (tickets.length === 0) return undefined;
+  // Wind-down window: tasks have settled but the ticket has not flipped to a
+  // terminal status yet. "settling" is more honest than "0 subagents".
+  if (activeSubagents === 0) {
+    return tickets.length === 1
+      ? `⏳ ${tickets[0]!.id} settling…`
+      : `⏳ ${plural(tickets.length, "ticket")} settling…`;
+  }
+  return tickets.length === 1
+    ? `⏳ ${plural(activeSubagents, "subagent")} · ${tickets[0]!.id}`
+    : `⏳ ${plural(activeSubagents, "subagent")} · ${plural(tickets.length, "ticket")}`;
+}
+
+/** Most recent context with UI access. Refreshed by every sync call that
+ *  receives a ctx, so event-driven updates can reach the footer without a
+ *  direct ctx of their own. Single runtime per process — a replaced runtime
+ *  refreshes this on its first delegate call or session event. */
+let lastCtx: ExtensionContext | undefined;
+/** Last text pushed to the footer — setStatus triggers a render, so dedupe. */
+let lastStatusText: string | undefined;
+/** Tickets already warned about at settle. Pruned to active tickets on sync. */
+const settledWarnedTicketIds = new Set<string>();
+
+/** Recompute the footer status from the registry and push it when changed.
+ *  Called on every ticket lifecycle mutation (create, progress, complete,
+ *  cancel); event-driven only — no timers, so the text never goes stale
+ *  (counts are the only content). */
+export function syncDelegateStatus(ctx?: ExtensionContext): void {
+  if (ctx) lastCtx = ctx;
+
+  const summary = activeTicketSummary();
+  const text = buildStatusText(summary);
+
+  if (settledWarnedTicketIds.size) {
+    const activeIds = new Set(summary.tickets.map((t) => t.id));
+    for (const id of settledWarnedTicketIds) {
+      if (!activeIds.has(id)) settledWarnedTicketIds.delete(id);
+    }
+  }
+
+  if (!lastCtx || text === lastStatusText) return;
+  try {
+    // The `ui` getter itself throws on a stale ctx — pi invalidates the old
+    // runtime on session replacement, and an unwinding ticket can race the
+    // teardown. A footer update must never crash the host.
+    lastCtx.ui.setStatus(STATUS_KEY, text);
+    lastStatusText = text;
+  } catch {
+    // Drop the stale ctx; the next live event re-caches a fresh one.
+    lastCtx = undefined;
+    lastStatusText = undefined;
+  }
+}
+
+/** Drop the cached ctx and warn-set on session shutdown — the runtime is
+ *  about to be invalidated, and any post-teardown sync (e.g. an aborted
+ *  ticket unwinding) must become a no-op instead of touching a stale ctx. */
+export function clearDelegateStatusContext(): void {
+  lastCtx = undefined;
+  lastStatusText = undefined;
+  settledWarnedTicketIds.clear();
+}
+
+/** Warn once per ticket at the first agent_settled with that ticket active —
+ *  the "looks idle but isn't" moment. The persistent footer status carries
+ *  the information from then on, so later settles stay quiet. */
+export function notifyActiveTicketsOnSettled(ctx: ExtensionContext): void {
+  lastCtx = ctx;
+  const summary = activeTicketSummary();
+  const fresh = summary.tickets.filter(
+    (t) => !settledWarnedTicketIds.has(t.id),
+  );
+  if (!fresh.length) return;
+
+  const subagents = fresh.reduce(
+    (n, t) =>
+      n +
+      t.progress.filter((p) => p.status === "running" || p.status === "pending")
+        .length,
+    0,
+  );
+  const detail =
+    fresh.length === 1
+      ? `(ticket ${fresh[0]!.id})`
+      : `across ${plural(fresh.length, "ticket")} (${fresh.map((t) => t.id).join(", ")})`;
+  try {
+    ctx.ui.notify(
+      `⏳ ${plural(subagents, "background subagent")} still running ${detail} — quitting pi aborts them`,
+      "warning",
+    );
+    for (const t of fresh) settledWarnedTicketIds.add(t.id);
+  } catch {
+    // Stale or headless ctx: drop it so the next live event re-caches one.
+    lastCtx = undefined;
+    lastStatusText = undefined;
+  }
+}
+
+/** Block a session replacement (switch/fork) while background subagents are
+ *  live, unless the human confirms. Returns `{ cancel: true }` to abort the
+ *  replacement, undefined to let it proceed. Headless contexts (no dialog
+ *  capability) are never blocked — automation must not deadlock on a
+ *  confirm it cannot answer. */
+export async function guardSessionReplacement(
+  ctx: ExtensionContext,
+  action: "switch" | "fork",
+): Promise<{ cancel: true } | undefined> {
+  lastCtx = ctx;
+  const summary = activeTicketSummary();
+  if (!summary.tickets.length || !ctx.hasUI) return undefined;
+
+  const ids = summary.tickets.map((t) => t.id).join(", ");
+  const verb =
+    action === "switch" ? "Switching sessions" : "Forking this session";
+  const proceed = await ctx.ui.confirm(
+    "Background subagents still running",
+    `${plural(summary.activeSubagents, "subagent")} (${ids}) still working. ` +
+      `${verb} aborts them — work already done is not rolled back. Continue anyway?`,
+  );
+  return proceed ? undefined : { cancel: true };
+}
+
+/** One-line description of live work for shutdown traces. */
+export function describeActiveTickets(
+  summary: ActiveTicketSummary = activeTicketSummary(),
+): string {
+  const ids = summary.tickets.map((t) => t.id).join(", ");
+  const agents = [
+    ...new Set(
+      summary.tickets.flatMap((t) =>
+        t.progress
+          .filter((p) => p.status === "running" || p.status === "pending")
+          .map((p) => p.agent),
+      ),
+    ),
+  ];
+  const agentList = agents.length ? ` [${agents.join(", ")}]` : "";
+  return `${plural(summary.activeSubagents, "background subagent")}${agentList} (ticket${summary.tickets.length === 1 ? "" : "s"}: ${ids})`;
+}
+
+export function _resetDelegateStatusForTesting(): void {
+  lastCtx = undefined;
+  lastStatusText = undefined;
+  settledWarnedTicketIds.clear();
+}

package/task-resolution.ts

@@ -1,6 +1,10 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { DEFAULT_TOOLS, VALID_THINKING } from "./constants.ts";
+import {
+  DEFAULT_AGENT_NAME,
+  DEFAULT_TOOLS,
+  VALID_THINKING,
+} from "./constants.ts";
 import { TOOL_FACTORIES, resolveToolGroups } from "./tools.ts";
 import { configFor } from "./pool.ts";
 import { isSessionBusy } from "./tickets.ts";
@@ -14,10 +18,62 @@ import type {
   AgentConfig,
   DelegateToolCtx,
   DelegateToolResult,
+  ParentAgentDefaults,
   ResolvedTask,
   TaskDef,
 } from "./types.ts";
 
+const PROJECT_CONTEXT_START =
+  "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n";
+const PROJECT_CONTEXT_END = "\n</project_context>\n";
+
+/**
+ * Parent `getSystemPrompt()` is the fully assembled prompt, including the
+ * parent's AGENTS.md files. A delegated session resolves resources for its own
+ * cwd, so carrying that section across would leak global instructions and
+ * duplicate project context. Preserve the parent's base prompt and everything
+ * outside Pi's structured context section; the child ResourceLoader appends its
+ * own (filtered) context afterward.
+ *
+ * The AGENTS.md/CLAUDE.md content is inserted verbatim inside
+ * `<project_instructions>...</project_instructions>` blocks. A file that
+ * itself contains `\n</project_context>\n` would otherwise terminate the
+ * scan early and leak the remainder of the parent context (P1). We therefore
+ * treat a candidate closing marker as valid only when it is *outside* any
+ * open `<project_instructions>` block — i.e. the first `PROJECT_CONTEXT_END`
+ * after `start` that is not nested. That matches the generated section's
+ * final closing marker while ignoring embedded fakes. A trailing
+ * `</project_context>` in post-context prompt text (skills/cwd) would also be
+ * outside, but such text is controlled by Pi and far less likely; picking the
+ * first outside marker preserves trailing prompt content instead of
+ * over-consuming it.
+ */
+export function stripInheritedProjectContext(
+  prompt: string | undefined,
+): string | undefined {
+  if (!prompt) return prompt;
+  const start = prompt.indexOf(PROJECT_CONTEXT_START);
+  if (start < 0) return prompt;
+  let searchFrom = start + PROJECT_CONTEXT_START.length;
+  let end = -1;
+  while (true) {
+    const candidate = prompt.indexOf(PROJECT_CONTEXT_END, searchFrom);
+    if (candidate < 0) break;
+    const before = prompt.slice(start, candidate);
+    const openCount = (before.match(/<project_instructions/g) || []).length;
+    const closeCount = (before.match(/<\/project_instructions>/g) || []).length;
+    if (openCount > closeCount) {
+      // Inside a file block — embedded fake, skip it.
+      searchFrom = candidate + PROJECT_CONTEXT_END.length;
+      continue;
+    }
+    end = candidate;
+    break; // first valid outside block is the true closing
+  }
+  if (end < 0) return prompt;
+  return `${prompt.slice(0, start)}${prompt.slice(end + PROJECT_CONTEXT_END.length)}`;
+}
+
 /** Build a tool result for an error/notice with no task progress. */
 function noticeResult(
   text: string,
@@ -67,10 +123,12 @@ export function validateTasks(
 
   const unknown: string[] = [];
   for (const t of tasks) {
-    if (t.agent && !agents.has(t.agent)) unknown.push(t.agent);
+    if (t.agent && t.agent !== DEFAULT_AGENT_NAME && !agents.has(t.agent)) {
+      unknown.push(t.agent);
+    }
   }
   if (unknown.length) {
-    const names = [...agents.keys()];
+    const names = [DEFAULT_AGENT_NAME, ...agents.keys()];
     return noticeResult(
       `Unknown agent(s): ${unknown.join(", ")}. Available: ${names.join(", ") || "(none)"}. Call delegate with an empty tasks array for help.`,
       tasks,
@@ -89,6 +147,7 @@ export function resolveTasks(
   tasks: TaskDef[],
   ctx: DelegateToolCtx,
   agents: Map<string, AgentConfig>,
+  parentDefaults: ParentAgentDefaults,
 ): ResolvedTask[] {
   // Build parent transcript lazily — only computed once if any task uses with-parent-transcript
   let parentTranscript: string | null = null;
@@ -107,22 +166,26 @@ export function resolveTasks(
     );
   }
 
-  const parentSystemPrompt = ctx.getSystemPrompt?.();
+  const parentSystemPrompt = stripInheritedProjectContext(
+    ctx.getSystemPrompt?.(),
+  );
 
   return tasks.map((t, i) => {
-    const agent = t.agent ? agents.get(t.agent) : undefined;
+    const isDefaultAgent = t.agent === DEFAULT_AGENT_NAME;
+    const agent = t.agent && !isDefaultAgent ? agents.get(t.agent) : undefined;
     const cwd = resolveCwd(t.cwd ?? ctx.cwd, ctx.cwd);
 
     // Load settings-based overrides for this agent
     const settings = loadDelegateSettings(cwd);
     const agentOverride =
-      t.agent && settings?.agentOverrides?.[t.agent]
+      t.agent && !isDefaultAgent && settings?.agentOverrides?.[t.agent]
         ? settings.agentOverrides[t.agent]
         : undefined;
 
     // Build system prompt. Explicit task prompts and named agent prompts
-    // win; ad-hoc subagents inherit the parent prompt when Pi exposes it,
-    // then get explicit skills/AGENTS.md injection below.
+    // win; ad-hoc subagents inherit the parent's base prompt when Pi exposes
+    // it. The assembled parent project-context section was stripped above;
+    // the child ResourceLoader supplies context for this task's cwd.
     const pooledConfig = t.sessionId ? configFor(t.sessionId) : undefined;
 
     // Prompt is required for fresh tasks. ResumeFrom provides context already.
@@ -138,10 +201,11 @@ export function resolveTasks(
     }
 
     // System prompt resolution. AgentSession's resource loader owns
-    // skills + AGENTS.md discovery (it appends them via _rebuildSystemPrompt),
-    // so we resolve only the *base* prompt here: explicit task prompt → named
-    // agent body → parent session prompt → default. The resolved base is
-    // passed as the loader's customPrompt (see buildDelegateSession).
+    // skills + project AGENTS.md discovery (it appends them via
+    // _rebuildSystemPrompt), so we resolve only the *base* prompt here:
+    // explicit task prompt → named agent body → sanitized parent prompt →
+    // default. The resolved base is passed as the loader's customPrompt (see
+    // buildDelegateSession).
     // Keep explicit intent separate: a bare `{ prompt, sessionId }` continues
     // the frozen prompt even if the parent prompt has since changed, while an
     // explicit task/profile prompt must not be silently ignored on reuse.
@@ -149,7 +213,9 @@ export function resolveTasks(
       ? t.systemPrompt
       : agent?.systemPrompt?.trim()
         ? agent.systemPrompt
-        : undefined;
+        : isDefaultAgent
+          ? parentSystemPrompt
+          : undefined;
     const systemPrompt = buildSubagentSystemPrompt({
       taskSystemPrompt: t.systemPrompt,
       agentSystemPrompt: agent?.systemPrompt,
@@ -193,39 +259,44 @@ export function resolveTasks(
     if (t.action !== "close" && t.action !== "list") {
       // A pool hit always runs its frozen model, but an explicitly requested
       // task/profile model still has to be resolved so checkout can reject a
-      // contradictory request rather than silently discarding it.
+      // contradictory request rather than silently discarding it. Naming the
+      // built-in `default` profile is also explicit: it requests the live
+      // parent model, so reuse fails clearly if the pool was frozen differently.
       if (pooledConfig) {
         const requestedModelSpec =
           t.model ??
-          (t.agent ? (agentOverride?.model ?? agent?.model) : undefined);
+          (t.agent && !isDefaultAgent
+            ? (agentOverride?.model ?? agent?.model)
+            : undefined);
         if (requestedModelSpec) {
-          requestedModel = resolveModelRequest(
+          const requested = resolveModelRequest(
             requestedModelSpec,
             ctx.modelRegistry,
             ctx.model,
-          ).model;
+          );
+          requestedModel = requested.model;
+          modelSuffix = requested.strippedSuffix;
           if (!requestedModel) {
             throw new Error(
               `Task ${i}: requested model '${requestedModelSpec}' is not available. Check provider config or remove the model field to continue the pooled session.`,
             );
           }
+        } else if (isDefaultAgent) {
+          requestedModel = ctx.model;
         }
         model = pooledConfig.model;
       } else {
-        // Resolve an explicit model spec (precedence: task > session > config >
-        // frontmatter). resolveModelSpec returns undefined when none is set, so
-        // we skip model re-resolution entirely — passing the parent's composite id
-        // (e.g. OpenRouter's "deepseek/deepseek-v4-flash") would split on "/"
-        // and misroute to the upstream provider. Leaving resolvedModel
-        // undefined also lets findAvailableAlternative run below: it returns
-        // ctx.model as-is when it has auth, or swaps to an authenticated
-        // same-id alternative when the parent's provider lost auth.
+        // The built-in `default` profile bypasses delegate.json and settings:
+        // absent a task override, it means this exact live parent Model object.
+        // Other tasks retain the normal task > config > frontmatter chain.
         const agentType = t.agent ?? "inline";
-        const modelSpec = resolveModelSpec({
-          taskModel: t.model ?? agentOverride?.model,
-          agentType,
-          frontmatterModel: agent?.model,
-        });
+        const modelSpec = isDefaultAgent
+          ? t.model
+          : resolveModelSpec({
+              taskModel: t.model ?? agentOverride?.model,
+              agentType,
+              frontmatterModel: agent?.model,
+            });
         const resolvedRequest = modelSpec
           ? resolveModelRequest(modelSpec, ctx.modelRegistry, ctx.model)
           : undefined;
@@ -242,10 +313,11 @@ export function resolveTasks(
           );
         }
 
-        model =
-          resolvedModel ??
-          findAvailableAlternative(ctx.model, ctx.modelRegistry) ??
-          ctx.model;
+        model = isDefaultAgent
+          ? (resolvedModel ?? ctx.model)
+          : (resolvedModel ??
+            findAvailableAlternative(ctx.model, ctx.modelRegistry) ??
+            ctx.model);
       }
 
       if (!model) {
@@ -259,10 +331,14 @@ export function resolveTasks(
       // "continue with only sessionId" works without re-supplying tools.
       // Explicit overrides that don't match get rejected by acquireAgentSession.
       const isPoolHit = pooledConfig !== undefined;
+      const parentNativeTools = parentDefaults.tools.filter(
+        (name) => name in TOOL_FACTORIES,
+      );
       tools = resolveToolGroups(
         t.tools ??
           agentOverride?.tools ??
           agent?.tools ??
+          (isDefaultAgent ? parentNativeTools : undefined) ??
           (isPoolHit ? pooledConfig?.tools : undefined) ??
           DEFAULT_TOOLS,
       );
@@ -273,17 +349,23 @@ export function resolveTasks(
         );
       }
 
-      // Resolve thinking. Precedence: task field → agent override → agent
-      // frontmatter → frozen pooled config → a Pi-style `:level` model suffix
-      // (honored only as a last-resort default, so a model-emitted `claude:max`
-      // runs at max when nothing else sets thinking). The suffix is lowest on
-      // purpose: an agent author's `thinking: low` must beat `model: x:max`.
+      // Resolve thinking. Precedence for most agents: explicit `thinking` >
+      // agent override > frontmatter > frozen pooled config > model `:level`
+      // suffix (last resort). The built-in `default` agent intentionally
+      // inverts the last two steps: model suffix beats the parent's live
+      // thinking, which beats the frozen pooled value. This surfaces a clear
+      // `config mismatch` error on reuse when the parent thinking level has
+      // changed, rather than silently reusing a stale frozen value. The final
+      // pooled fallback is reachable only when parentDefaults.thinking is
+      // undefined (headless parent without a thinking level).
       const thinkingRaw =
         t.thinking ??
         agentOverride?.thinking ??
         agent?.thinking ??
-        (isPoolHit ? pooledConfig?.thinking : undefined) ??
+        (isPoolHit && !isDefaultAgent ? pooledConfig?.thinking : undefined) ??
         modelSuffix ??
+        (isDefaultAgent ? parentDefaults.thinking : undefined) ??
+        (isPoolHit ? pooledConfig?.thinking : undefined) ??
         "off";
       thinking = VALID_THINKING.has(thinkingRaw)
         ? (thinkingRaw as ThinkingLevel)
@@ -307,10 +389,11 @@ export function resolveTasks(
       // Empty only for close/list actions (validated above) — downstream
       // display code treats "" and absent alike (`t.prompt || …`).
       prompt: prompt ?? "",
-      // Display label for ad-hoc subagents (no named profile). NOTE: the
-      // config-namespace key at resolveModelSpec stays "inline" — that's a
-      // delegate.json/settings contract, not a display string (friction #4).
-      agentName: agent?.name ?? "ad-hoc",
+      // Keep the built-in selector visible in progress/results. Omitted-agent
+      // inline tasks retain the established `ad-hoc` label and config namespace.
+      agentName: isDefaultAgent
+        ? DEFAULT_AGENT_NAME
+        : (agent?.name ?? "ad-hoc"),
       warnings,
       reuseIntent: {
         model: requestedModel,

package/types.ts

@@ -65,6 +65,14 @@ export interface AsyncTicket {
   waiters?: TicketWaiter[];
 }
 
+/** Live parent settings captured when a delegate call starts. The built-in
+ *  `default` profile mirrors these settings, limited to tools delegate can
+ *  safely recreate without loading the parent's extensions. */
+export interface ParentAgentDefaults {
+  thinking: ThinkingLevel;
+  tools: string[];
+}
+
 export interface ReuseIntent {
   /** Explicit model requested by this call/profile; omitted means use frozen. */
   model?: Model<Api>;