@justjoshn/pi-pstack 0.15.36-pi.11 → 0.15.36-pi.13

package/src/subscriptions/durable-store.ts

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { performance } from 'node:perf_hooks';
 
 import { durableRegistryPath, durableRuntimeDir } from '../paths.ts';
+import { acquireLease, alive } from '../process-lock.ts';
 import { parseCron } from './cron.ts';
 import type { ArmStatus, DurableRegistry, DurableSubscription, EventAdmission, PendingEvent, StoredSubscription, SupervisorLock } from './durable-types.ts';
 import { routineSlug } from './webhook.ts';
@@ -18,28 +19,6 @@ export function canonicalPath(path: string): string {
   }
 }
 
-function zombie(pid: number): boolean {
-  if (process.platform !== 'linux') return false;
-  try {
-    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
-    const close = stat.lastIndexOf(')');
-    return close !== -1 && stat.slice(close + 2, close + 3) === 'Z';
-  } catch {
-    return false;
-  }
-}
-
-export function alive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    // A zombie still answers kill(pid, 0) until its parent reaps it, but it holds no lock and runs nothing.
-    return !zombie(pid);
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
 function writeAtomic(path: string, value: unknown): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
@@ -77,58 +56,6 @@ export function writeRoutinesPort(cwd: string, port: number): void {
   }
 }
 
-export type Lease = { token: string; release: () => void };
-
-/** Publish a nonempty directory atomically. Recovery removes only the dead holder's token. */
-export function acquireLease(path: string): Lease | undefined {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const token = `${process.pid}-${randomUUID()}`;
-  const temporary = `${path}.${token}.tmp`;
-  mkdirSync(temporary, { mode: 0o700 });
-  try {
-    writeFileSync(join(temporary, token), '', { mode: 0o600 });
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-      try {
-        renameSync(temporary, path);
-        return {
-          token,
-          release: () => {
-            rmSync(join(path, token), { force: true });
-            try {
-              rmdirSync(path);
-            } catch (error) {
-              if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-            }
-          },
-        };
-      } catch (error) {
-        if (!['ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-      }
-      let holders: string[];
-      try {
-        holders = readdirSync(path);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
-        throw error;
-      }
-      for (const holder of holders) {
-        const pid = Number(/^(\d+)-[a-f0-9-]+$/.exec(holder)?.[1]);
-        if (!Number.isInteger(pid)) throw new Error(`Invalid subscription lock ${path}. Retain it for diagnosis.`);
-        if (alive(pid)) return undefined;
-        rmSync(join(path, holder), { force: true });
-      }
-      try {
-        rmdirSync(path);
-      } catch (error) {
-        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-      }
-    }
-    return undefined;
-  } finally {
-    rmSync(temporary, { recursive: true, force: true });
-  }
-}
-
 export function ownerIsLive(cwd: string, sessionId: string): boolean {
   const path = ownerLockPath(cwd, sessionId);
   try {

package/src/subscriptions/index.ts

@@ -6,24 +6,9 @@ import { type Static, Type } from 'typebox';
 import { Value } from 'typebox/value';
 import { isOneShot } from '../modes.ts';
 import { routinesDir } from '../paths.ts';
+import { acquireLease, type Lease } from '../process-lock.ts';
 import { parseCron } from './cron.ts';
-import {
-  acquireLease,
-  cancelDesired,
-  canonicalPath,
-  createDesired,
-  deliverOwner,
-  finishFresh,
-  isDesired,
-  isSupervisorLive,
-  type Lease,
-  ownerLockPath,
-  readArm,
-  readRegistry,
-  runsDetached,
-  startFresh,
-  visibleSubscriptions,
-} from './durable-store.ts';
+import { cancelDesired, canonicalPath, createDesired, deliverOwner, finishFresh, isDesired, isSupervisorLive, ownerLockPath, readArm, readRegistry, runsDetached, startFresh, visibleSubscriptions } from './durable-store.ts';
 import type { StoredSubscription } from './durable-types.ts';
 import { defaultEnsureSupervisor, waitForArm, waitForSupervisor } from './ensure-supervisor.ts';
 import { type GhRunner, targetText } from './github.ts';

package/src/subscriptions/supervisor.ts

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
 
 import { routinesDir } from '../paths.ts';
+import { alive } from '../process-lock.ts';
 import { cronMatches, parseCron } from './cron.ts';
 import {
   acceptEvent,
   acquireSupervisorLock,
-  alive,
   canonicalPath,
   clearError,
   expireDesired,

package/src/task/agents.ts

@@ -11,18 +11,54 @@ export interface AgentDefinition {
   model?: string;
   readonly: boolean;
   background: boolean;
+  /** False for a type that never launches subagents of its own, such as Cursor's built-in explore. */
+  spawns?: boolean;
+  /** Pi tools this type turns on beyond Pi's defaults, such as explore's search tools. */
+  tools?: readonly string[];
   prompt: string;
   file?: string;
 }
 
 export const GENERAL_PURPOSE: AgentDefinition = {
   type: 'generalPurpose',
-  description: 'General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when a search or task needs several steps of its own.',
+  description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when searching for a keyword or file and not confident you'll find the match quickly.",
   readonly: false,
   background: false,
   prompt: '',
 };
 
+/**
+ * Cursor's built-in codebase explorer: a file-search specialist that the caller tells how thorough to be, and that has
+ * no Task tool of its own.
+ */
+export const EXPLORE: AgentDefinition = {
+  type: 'explore',
+  description:
+    'Fast agent specialized for exploring codebases. Use it to find files by pattern (such as "src/components/**/*.tsx"), search code for keywords (such as "API endpoints"), or answer questions about the codebase (such as "how do API endpoints work?"). When you call it, name the thoroughness you want: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for a comprehensive search across many locations and naming conventions.',
+  readonly: false,
+  background: false,
+  spawns: false,
+  tools: ['grep', 'find', 'ls'],
+  prompt: [
+    'You are a file search specialist. You navigate and explore codebases thoroughly.',
+    '',
+    'You are good at:',
+    '- finding files fast with glob patterns (find)',
+    '- searching code and text with regular expressions (grep)',
+    '- reading and analyzing file contents (read)',
+    '',
+    'Guidelines:',
+    '- Match how hard you search to the thoroughness the caller asked for.',
+    '- Give file paths as absolute paths in your final response.',
+    '- Do not use emojis.',
+    '- Send your final report directly as a regular message.',
+    '',
+    'You are meant to be fast and to return as soon as you can. Use your tools efficiently: think about where the files and implementations are likely to be, and run several grep and read calls in parallel wherever you can.',
+    '',
+    "Complete the caller's search request efficiently and report your findings clearly.",
+  ].join('\n'),
+};
+
 function parseAgentFile(file: string): AgentDefinition {
   const { frontmatter, body } = parseFrontmatter(readFileSync(file, 'utf8'));
   const name = frontmatter['name'];
@@ -39,12 +75,12 @@ function parseAgentFile(file: string): AgentDefinition {
   };
 }
 
-/** generalPurpose first, then every `*.md` agent file in `dir` sorted by file name. */
+/** The built-in types (generalPurpose, explore) first, as Cursor lists them, then every `*.md` agent file in `dir` sorted by file name. */
 export function loadAgentDefinitions(dir: string = AGENTS_DIR): AgentDefinition[] {
   const files = readdirSync(dir)
     .filter((name) => name.endsWith('.md'))
     .toSorted();
-  return [GENERAL_PURPOSE, ...files.map((name) => parseAgentFile(join(dir, name)))];
+  return [GENERAL_PURPOSE, EXPLORE, ...files.map((name) => parseAgentFile(join(dir, name)))];
 }
 
 export function findAgent(agents: readonly AgentDefinition[], type: string | undefined): AgentDefinition {

package/src/task/card.ts

@@ -35,6 +35,7 @@ interface NotificationCardDetails {
   status: 'success' | 'error';
   agentId: string;
   title: string;
+  description?: string;
   detail: string;
 }
 
@@ -49,10 +50,11 @@ export function taskNotificationCardText(message: { content: string | { type: st
     const lines = raw.split('\n');
     return (expanded || lines.length <= COLLAPSED_LINES ? lines : [...lines.slice(0, COLLAPSED_LINES), `… ${lines.length - COLLAPSED_LINES} more lines`]).join('\n');
   }
-  const { title, status, agentId, detail } = message.details;
+  const { title, description, status, agentId, detail } = message.details;
   const lines = detail.split('\n');
   const body = expanded || lines.length <= COLLAPSED_LINES ? lines : [...lines.slice(0, COLLAPSED_LINES), `… ${lines.length - COLLAPSED_LINES} more lines`];
-  const head = `${title.trim() === '' ? 'subagent' : title.trim()} · ${status} · agent ${agentId}`;
+  const name = [description, title].map((value) => value?.trim() ?? '').find((value) => value !== '') ?? 'subagent';
+  const head = `${name} · ${status} · agent ${agentId}`;
   return [head, ...body].join('\n');
 }
 

package/src/task/format.ts

@@ -28,7 +28,7 @@ export function bounded(text: string, transcript: string | undefined): string {
   return `${result.content}\n[truncated: showing ${result.outputLines} of ${result.totalLines} lines${size}; ${where}]`;
 }
 
-const agentIdLine = (agentId: string) => `Agent ID: ${agentId} (pass it as \`resume\` to send a follow-up after it completes)`;
+const agentIdLine = (agentId: string) => `Agent ID: ${agentId} (can be used with the \`resume\` parameter to send a follow-up after it completes)`;
 const transcriptLine = (transcript: string | undefined) => (transcript === undefined ? [] : [`Transcript: ${transcript}`]);
 
 export function foregroundText(agentId: string, response: string, transcript: string | undefined, notes: readonly string[] = []): string {
@@ -37,7 +37,7 @@ export function foregroundText(agentId: string, response: string, transcript: st
 
 export function backgroundText(agentId: string, transcript: string | undefined, notes: readonly string[] = []): string {
   return [
-    'Subagent is running in the background. Its final response arrives automatically after your turn ends, so do not wait or poll for it. End your turn or work on something else.',
+    "Subagent is running in the background. When you end your turn, you will be automatically sent the subagent's final response upon its completion, so do not wait for it - either end your turn or work on something else.",
     '',
     agentIdLine(agentId),
     ...transcriptLine(transcript),
@@ -65,16 +65,28 @@ export function worktreePreface(worktree: Worktree, prompt: string): string {
 export interface NotificationFields {
   status: 'success' | 'error';
   agentId: string;
+  /** The model-facing title, from the prompt as Cursor writes it. */
   title: string;
+  /** The Task description, which names the subagent in the UI. */
+  description?: string;
   toolCallId: string;
   detail: string;
   /** What the background child spent. It stays in the notification details, because Pi gives extensions no way to add it to session totals. */
   usage?: Usage;
 }
 
+const TITLE_LIMIT = 80;
+
+/** Cursor titles a completion by its prompt: the first non-empty line, cut at 80 characters. */
+export function notificationTitle(prompt: string): string {
+  const line = prompt.split('\n').find((candidate) => candidate.trim() !== '') ?? '';
+  return line.trim().slice(0, TITLE_LIMIT);
+}
+
 export function notificationText(fields: NotificationFields): string {
   return [
-    'The following task has finished. If you already handled it, ignore this notification and do not restate earlier responses.',
+    '<system_notification>',
+    'The following task has finished. If you were already aware, ignore this notification and do not restate prior responses.',
     '',
     '<task>',
     'kind: subagent',
@@ -84,5 +96,7 @@ export function notificationText(fields: NotificationFields): string {
     `tool_call_id: ${fields.toolCallId}`,
     `detail: ${fields.detail}`,
     '</task>',
+    '</system_notification>',
+    "Perform any necessary follow-up actions in response to the subagent completion above. If no follow-up work is needed, no further action is required. If you mention an agent or subagent in your response, link it with the `[Name](id)` Don't use generic label such as `[agent]`, `[worker]`, or `[subagent]`. Don't repeat the same confirmation every time.",
   ].join('\n');
 }

package/src/task/records.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, w
 import { join } from 'node:path';
 
 import { parseSessionEntries, SessionManager } from '@earendil-works/pi-coding-agent';
+import { acquireLease, alive } from '../process-lock.ts';
 import type { ModelSpec } from './models.ts';
 import type { Worktree } from './worktree.ts';
 
@@ -142,15 +143,6 @@ export function recordIds(dir: string): string[] {
     .map((name) => name.slice(0, -'.json'.length));
 }
 
-function alive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
 const isPid = (value: number) => Number.isInteger(value) && value > 0;
 
 /** The live pid the agent's run lock names, or undefined when no live process holds it. */
@@ -198,33 +190,46 @@ export interface RunLock {
 /**
  * Pi appends to a session file without a lock, so two processes on one agent ID would interleave its transcript.
  * The lock file holds the pid of the process writing the transcript. A lock without a readable pid counts as held.
- * A dead holder's lock is removed only if it still names that holder, then created again exclusively; two
- * processes taking over the same stale lock in the narrow window between that re-read and the removal can both succeed.
+ * A token-directory lease serializes acquisition and stale recovery without changing the PID file read by stop/status.
  */
 export function acquireRunLock(dir: string, agentId: string): RunLock {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   const path = join(dir, `${agentId}.lock`);
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    if (createExclusive(path)) {
-      let owner = process.pid;
-      return {
-        holdFor: (pid) => {
-          writeAtomically(path, String(pid));
-          owner = pid;
-        },
-        // Best effort: a lock left behind names a pid that will be dead, so the next acquire takes it over.
-        release: () => {
-          try {
-            if (holderOf(path) === owner) rmSync(path, { force: true });
-          } catch (error) {
-            if (!['EACCES', 'EPERM', 'EROFS', 'EBUSY', 'EIO'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-          }
-        },
-      };
+  const lease = acquireLease(`${path}.owner`);
+  if (lease === undefined) throw stillRunning(agentId, runningPid(dir, agentId), path);
+  let acquired = false;
+  try {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      if (createExclusive(path)) {
+        acquired = true;
+        let owner = process.pid;
+        return {
+          holdFor: (pid) => {
+            writeAtomically(path, String(pid));
+            owner = pid;
+          },
+          release: () => {
+            for (const release of [
+              () => {
+                if (holderOf(path) === owner) rmSync(path, { force: true });
+              },
+              lease.release,
+            ]) {
+              try {
+                release();
+              } catch (error) {
+                if (!['EACCES', 'EPERM', 'EROFS', 'EBUSY', 'EIO'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+              }
+            }
+          },
+        };
+      }
+      const holder = holderOf(path);
+      if (holder !== undefined && (!isPid(holder) || alive(holder))) throw stillRunning(agentId, holder, path);
+      if (holder !== undefined && holderOf(path) === holder) rmSync(path, { force: true });
     }
-    const holder = holderOf(path);
-    if (holder !== undefined && (!isPid(holder) || alive(holder))) throw stillRunning(agentId, holder, path);
-    if (holder !== undefined && holderOf(path) === holder) rmSync(path, { force: true });
+    throw stillRunning(agentId, holderOf(path), path);
+  } finally {
+    if (!acquired) lease.release();
   }
-  throw stillRunning(agentId, holderOf(path), path);
 }

package/src/task/registry.ts

@@ -15,6 +15,7 @@ interface Running {
 
 export interface BackgroundNotice {
   title: string;
+  description: string;
   toolCallId: string;
   mode: ExtensionContext['mode'];
   detailFor: (outcome: ChildOutcome) => Pick<NotificationFields, 'status' | 'detail' | 'usage'>;
@@ -42,7 +43,7 @@ export function createSubagentRegistry(pi: ExtensionAPI) {
       release();
       // Shutdown killed this child; the retired runtime's pi must not be touched.
       if (retired || notice === undefined) return;
-      deliver({ ...notice.detailFor(outcome), agentId, title: notice.title, toolCallId: notice.toolCallId }, notice.mode);
+      deliver({ ...notice.detailFor(outcome), agentId, title: notice.title, description: notice.description, toolCallId: notice.toolCallId }, notice.mode);
     });
     running.set(agentId, { settled, handle, readonly, background: notice !== undefined });
   };

package/src/task/runner.ts

@@ -31,10 +31,13 @@ export interface ChildArgsOptions {
   restoreTools?: readonly string[];
   /** The parent's project trust, so the child loads the same project resources (`ctx.isProjectTrusted()`). */
   trusted?: boolean;
+  /** Tools the agent type adds to Pi's default loadout (explore's search tools). */
+  addTools?: readonly string[];
 }
 
 /** Argv for one `pi --mode rpc` subagent process. Its prompts travel as RPC commands on stdin, never in argv. */
 export function childArgs(options: ChildArgsOptions): string[] {
+  const extraTools = [...new Set([...(options.restoreTools ?? []), ...(options.addTools ?? [])])];
   const model = options.model === undefined ? [] : ['--model', `${options.model.provider}/${options.model.id}`, ...(options.model.thinking === undefined ? [] : ['--thinking', options.model.thinking])];
   return [
     '--mode',
@@ -48,7 +51,7 @@ export function childArgs(options: ChildArgsOptions): string[] {
     ...(options.trusted === undefined ? [] : [options.trusted ? '--approve' : '--no-approve']),
     ...model,
     ...(options.readonly === true ? ['--tools', READONLY_TOOLS, '--no-mcp'] : []),
-    ...(options.readonly !== true && (options.restoreTools ?? []).length > 0 ? ['--tools', (options.restoreTools ?? []).map((name) => `+${name}`).join(',')] : []),
+    ...(options.readonly !== true && extraTools.length > 0 ? ['--tools', extraTools.map((name) => `+${name}`).join(',')] : []),
   ];
 }
 

package/src/task/stop.ts

@@ -65,7 +65,8 @@ async function stopElsewhere(agentId: string, lockPath: string, pid: number): Pr
 export interface StopAgentOptions {
   /** A child this process runs, if any. */
   running: (agentId: string) => { handle: ChildHandle } | undefined;
-  depth: number;
+  /** An agent that cannot launch subagents has none to stop. */
+  canSpawn: boolean;
 }
 
 const DESCRIPTION =
@@ -79,8 +80,7 @@ export function registerStopAgent(pi: ExtensionAPI, options: StopAgentOptions):
     promptSnippet: 'Stop a running subagent by agent ID',
     parameters: Type.Object({ agent_id: Type.String({ description: 'Agent ID from an earlier Task call in this workspace.' }) }),
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    // Nesting stops at the subagent of a subagent, which has no subagents to stop.
-    defaultActive: options.depth < 2,
+    defaultActive: options.canSpawn,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const agentId = validateAgentId(params.agent_id);
       const owned = options.running(agentId);

package/src/task/tool.ts

@@ -5,12 +5,12 @@ import { isAbsolute, join, relative } from 'node:path';
 import { getSupportedThinkingLevels } from '@earendil-works/pi-ai';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { type Static, Type } from 'typebox';
-import { childIdentity, childVariables } from '../child-env.ts';
+import { BUILD_PLAN_ENV, childIdentity, childVariables } from '../child-env.ts';
 import { rootStoreDir, subagentDir, workspaceStateDir, worktreesDir } from '../paths.ts';
 import { piCommand } from '../pi-command.ts';
 import { type AgentDefinition, findAgent } from './agents.ts';
 import { renderTaskCard, renderTaskNotification } from './card.ts';
-import { backgroundText, bounded, foregroundText, steerText, worktreeLine, worktreePreface } from './format.ts';
+import { backgroundText, bounded, foregroundText, notificationTitle, steerText, worktreeLine, worktreePreface } from './format.ts';
 import { type AvailableModel, type ModelSpec, resolveSubagentModel } from './models.ts';
 import { createProgress } from './progress.ts';
 import { type AgentRecord, acquireRunLock, forkTranscript, type RunLock, readonlyLaunchRestores, readRecord, transcriptFor, writeRecord } from './records.ts';
@@ -19,16 +19,17 @@ import { type ChildHandle, type ChildInput, type ChildOutcome, childArgs, resolv
 import { registerStopAgent } from './stop.ts';
 import { addWorktree, planWorktree, type Worktree } from './worktree.ts';
 
-const TITLE_LIMIT = 200;
-
 export const TaskParams = Type.Object({
-  description: Type.String({ description: 'A short (3-5 word) title for the subagent, shown in the UI.' }),
-  prompt: Type.String({ description: 'The task for the agent to perform. The subagent sees nothing of this conversation, so include every detail and say what to report back.' }),
+  description: Type.String({
+    description:
+      "A short, user-friendly title for the subagent, shown in the UI as the subagent's name. Make it concrete and distinct from recent titles. When you resume an agent for a separate task, give it an updated title; keep the title when it continues the same work.",
+  }),
+  prompt: Type.String({ description: 'The task for the agent to perform.' }),
   subagent_type: Type.Optional(Type.String({ description: 'Subagent type from the pstack_subagents section. Defaults to generalPurpose.' })),
   model: Type.Optional(
     Type.String({
       description:
-        'Optional model for this agent, from the pstack_subagents section: inherit (default), a Pi model such as claude-opus-5-5:xhigh or provider/model:high, or claude-opus-5-5[effort=high]. An invalid value fails with the allowed list; pick a listed value or omit it. Ignored with resume; with fork, defaults to the source agent model.',
+        'Optional model for this agent, from the pstack_subagents section: inherit (default), a Pi model such as claude-opus-5-5:xhigh or provider/model:high, or claude-opus-5-5[effort=high]. An invalid value fails with the allowed list; pick a listed value or omit it, and never retry a rejected value unchanged. Omitted, the agent runs on the parent model. Use inherit unless the user or a skill asks for another listed model. Ignored with resume, which keeps the earlier model; with fork, defaults to the source agent model.',
     }),
   ),
   resume: Type.Optional(
@@ -110,6 +111,7 @@ export interface Launch {
   attachments: string[];
   notes: string[];
   description: string;
+  buildPlan?: string;
 }
 
 const runsReadonly = (plan: Launch) => plan.readonly || plan.planMode;
@@ -268,10 +270,22 @@ export function planFork(params: TaskInput, ctx: ExtensionContext, agents: reado
 
 function launchChild(plan: Launch, input: ChildInput, signal: AbortSignal | undefined, onEvent?: (event: { type: string } & Record<string, unknown>) => void) {
   const readonly = runsReadonly(plan);
-  const env = { ...process.env, ...childVariables(plan.agent.type, plan.depth, readonly, plan.rootStore, workspaceStateDir(plan.workspace), plan.rootWorkspace) };
+  const env = {
+    ...process.env,
+    ...childVariables(plan.agent.type, plan.depth, readonly, plan.rootStore, workspaceStateDir(plan.workspace), plan.rootWorkspace),
+    ...(plan.buildPlan === undefined ? {} : { [BUILD_PLAN_ENV]: plan.buildPlan }),
+  };
   const transcript = plan.kind === 'fresh' || readonly ? undefined : transcriptFor(subagentDir(plan.workspace), plan.agentId);
   const restoreTools = transcript === undefined ? [] : readonlyLaunchRestores(transcript);
-  const args = childArgs({ sessionDir: subagentDir(plan.workspace), agentId: plan.agentId, readonly, restoreTools, trusted: plan.trusted, ...(plan.model === undefined ? {} : { model: plan.model }) });
+  const args = childArgs({
+    sessionDir: subagentDir(plan.workspace),
+    agentId: plan.agentId,
+    readonly,
+    restoreTools,
+    trusted: plan.trusted,
+    ...(plan.agent.tools === undefined ? {} : { addTools: plan.agent.tools }),
+    ...(plan.model === undefined ? {} : { model: plan.model }),
+  });
   return startChild({ command: piCommand(), args, prompt: input.text, images: input.images, cwd: plan.executionCwd, env, ...(signal === undefined ? {} : { signal }), ...(onEvent === undefined ? {} : { onEvent }) });
 }
 
@@ -359,11 +373,11 @@ function foregroundResult(plan: Launch, outcome: ChildOutcome) {
   return { content: [{ type: 'text' as const, text }], details: details(plan, false, 'error'), usage: outcome.usage, isError: true };
 }
 
-/** Cursor shows the Task description as the subagent's name, so the completion notice carries it too. */
-export function backgroundNotice(plan: Launch, description: string, ctx: ExtensionContext, toolCallId: string): BackgroundNotice {
-  const flat = description.replace(/\s+/g, ' ').trim();
+/** Cursor titles the completion by the prompt's first line and names the subagent in the UI by its description. */
+export function backgroundNotice(plan: Launch, prompt: string, description: string, ctx: ExtensionContext, toolCallId: string): BackgroundNotice {
   return {
-    title: flat.length > TITLE_LIMIT ? `${flat.slice(0, TITLE_LIMIT)}…` : flat,
+    title: notificationTitle(prompt),
+    description: description.replace(/\s+/g, ' ').trim(),
     toolCallId,
     mode: ctx.mode,
     detailFor: (outcome) => {
@@ -449,8 +463,21 @@ async function steerRunning(params: TaskInput, running: { handle: ChildHandle; r
   return { content: [{ type: 'text' as const, text: steerText(agentId, notes) }], details: { agentId, status: 'steered', pid: running.handle.pid ?? null, description: params.description } };
 }
 
-const TASK_DESCRIPTION =
-  'Launch a subagent: a separate Pi process with its own context that works autonomously and returns one final message. It sees nothing of this conversation, so give it a self-contained prompt and say what to report back. Put several Task calls in one message to run them in parallel. Subagent types and model values are listed in the pstack_subagents section of the system prompt.';
+const TASK_DESCRIPTION = [
+  'Launch a new agent to handle a complex, multi-step task on its own. Each agent is a separate Pi process with its own context, and each subagent_type has its own instructions and tools. Pick the type with subagent_type; the types, and the model values the model parameter takes, are listed in the pstack_subagents section of the system prompt.',
+  '',
+  'Do not use Task for a narrow or specific question. To find where one class is defined, read a known file, or search two or three files, use read, grep, or find directly. When separate areas can be explored in parallel, launch several agents at once. Do not hand the whole request to one agent and relay its answer.',
+  '',
+  'Usage notes:',
+  '- Give every call a short (3-5 word) description.',
+  '- To run agents in parallel, put several Task calls in one message. Do this whenever the work splits, and always when the user asks for agents in parallel.',
+  '- The agent returns one final message. Say exactly what it should report back.',
+  "- The agent cannot see the user's messages or your earlier steps, so the prompt must carry every detail and all the context it needs.",
+  '- Trust the agent output in general.',
+  '- When a subagent type says to use it proactively, use it without being asked.',
+  '- resume continues an earlier agent with its context preserved. Without resume, each call starts fresh.',
+  '- A background agent notifies you automatically when it finishes, after you end your turn. Do not poll it, sleep, or check on its progress. Work on something else or end your turn, and do not mention this to the user.',
+].join('\n');
 
 // Interactive Pi redraws the chat between a replaced session's shutdown and the next session's start, which erases a
 // warning sent at shutdown. The next runtime shows it instead, so it rides on globalThis across the reload.
@@ -466,6 +493,8 @@ function dropTask(pi: ExtensionAPI): void {
 export interface TaskToolOptions {
   agents: readonly AgentDefinition[];
   depth: number;
+  /** False in a subagent of a subagent, and in a type that never launches subagents (explore). */
+  canSpawn: boolean;
   /** Whether plan mode is on: its Task launches run readonly and here, and record nothing of that. */
   planMode?: () => boolean;
 }
@@ -473,8 +502,12 @@ export interface TaskToolOptions {
 export interface StartBackgroundOptions {
   /** A Pi model spec, used by subscription timers so a live and a detached fire run the same model. */
   model?: string;
+  /** cloud runs the agent in its own git worktree, as plan mode's "build in cloud" does. */
+  environment?: 'cloud';
   /** The owner's project-trust decision, used when this subscription fire starts away from its chat. */
   trusted?: boolean;
+  /** Imports the reviewed plan's todos into the worker before its first model request. */
+  buildPlan?: string;
 }
 
 export interface TaskHandle {
@@ -498,7 +531,7 @@ export function registerTask(pi: ExtensionAPI, options: TaskToolOptions): TaskHa
   });
   pi.on('session_start', (_event, ctx) => {
     sessionCtx = ctx;
-    if (options.depth >= 2) dropTask(pi);
+    if (!options.canSpawn) dropTask(pi);
     const message = carrier[STOPPED_NOTICE];
     delete carrier[STOPPED_NOTICE];
     if (message !== undefined && ctx.hasUI) ctx.ui.notify(message, 'warning');
@@ -510,8 +543,8 @@ export function registerTask(pi: ExtensionAPI, options: TaskToolOptions): TaskHa
     description: TASK_DESCRIPTION,
     promptSnippet: 'Launch subagents (foreground, background with completion notifications, resume by agent ID)',
     parameters: TaskParams,
-    // Nesting stops at the subagent of a subagent, so that depth never sees the tool.
-    defaultActive: options.depth < 2,
+    // Nesting stops at the subagent of a subagent, so that depth never sees the tool, and so does explore.
+    defaultActive: options.canSpawn,
     renderResult: (result, renderOptions) => renderTaskCard(result, renderOptions),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       taskPreflight(params, options.depth);
@@ -527,7 +560,7 @@ export function registerTask(pi: ExtensionAPI, options: TaskToolOptions): TaskHa
       const handle = start(plan, input, background ? undefined : signal, lock, progress?.onEvent);
       pid = handle.pid;
       if (background) {
-        registry.track(plan.agentId, handle, lock.release, runsReadonly(plan), backgroundNotice(plan, plan.description, ctx, toolCallId));
+        registry.track(plan.agentId, handle, lock.release, runsReadonly(plan), backgroundNotice(plan, params.prompt, plan.description, ctx, toolCallId));
         return { content: [{ type: 'text', text: backgroundText(plan.agentId, transcriptOf(plan), plan.notes) }], details: details(plan, true, 'running', handle.pid) };
       }
       registry.track(plan.agentId, handle, lock.release, runsReadonly(plan));
@@ -541,18 +574,25 @@ export function registerTask(pi: ExtensionAPI, options: TaskToolOptions): TaskHa
     },
   });
 
-  registerStopAgent(pi, { running: registry.get, depth: options.depth });
+  registerStopAgent(pi, { running: registry.get, canSpawn: options.canSpawn });
 
   async function startBackground(description: string, prompt: string, startOptions?: StartBackgroundOptions): Promise<string> {
     const ctx = sessionCtx;
     if (ctx === undefined) throw new Error('No session is active, so no subagent can start.');
-    const params: TaskInput = { description, prompt, run_in_background: true, ...(startOptions?.model === undefined ? {} : { model: startOptions.model }) };
+    const params: TaskInput = {
+      description,
+      prompt,
+      run_in_background: true,
+      ...(startOptions?.model === undefined ? {} : { model: startOptions.model }),
+      ...(startOptions?.environment === undefined ? {} : { environment: startOptions.environment }),
+    };
     taskPreflight(params, options.depth);
     const { plan, lock } = prepare(params, ctx, options, registry.isRunning);
     if (startOptions?.trusted !== undefined) plan.trusted = startOptions.trusted;
+    if (startOptions?.buildPlan !== undefined) plan.buildPlan = startOptions.buildPlan;
     await createWorktree(plan, lock, undefined);
     const handle = start(plan, { text: prompt.trim(), images: [] }, undefined, lock);
-    registry.track(plan.agentId, handle, lock.release, runsReadonly(plan), backgroundNotice(plan, description, ctx, `pstack-${plan.agentId}`));
+    registry.track(plan.agentId, handle, lock.release, runsReadonly(plan), backgroundNotice(plan, prompt, description, ctx, `pstack-${plan.agentId}`));
     return plan.agentId;
   }