@bermudi/pi-delegate 0.1.7 → 0.1.9

package/host.ts

@@ -16,7 +16,8 @@
  * must not run the parent's interactive extensions (custom UI, slash commands,
  * hooks that call `pi.appendEntry()`/`pi.sendMessage()`). A narrow,
  * provider-scoped allowlist is injected as `additionalExtensionPaths` for
- * safety-critical integrations. Those extension-bearing dependencies are
+ * provider-specific integrations (best-effort for shipped defaults). Those
+ * extension-bearing dependencies are
  * deliberately built per session: `AgentSession._buildRuntime` hands the
  * loader's `extensionsResult.runtime` to a new `ExtensionRunner`, whose
  * `bindCore()` overwrites mutable methods on that runtime (`sendMessage`,
@@ -37,7 +38,15 @@
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { existsSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 import {
   DefaultPackageManager,
   DefaultResourceLoader,
@@ -49,7 +58,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import {
   getSubagentProviderExtensionMap,
-  getSubagentProviderExtensionsForProvider,
+  getSubagentProviderExtensionSourcesForProvider,
 } from "./config.ts";
 
 export interface HostDeps {
@@ -94,6 +103,14 @@ const hostDepsInflight = new Map<string, Promise<HostDeps>>();
 /** Prevent a pre-invalidation build from repopulating or clearing newer state. */
 let hostDepsCacheGeneration = 0;
 
+// When the shipped best-effort default (npm:@bermudi/pi-codex) is absent — the
+// normal state for most users — Pi's DefaultPackageManager.getInstalledPath
+// would synchronously spawn `npm root -g` to check the legacy global fallback.
+// Doing that once per task in a fan-out blocks the event loop N times and
+// serializes the fan-out. Cache the *absence* per dispatch so only the first
+// task in a fan-out pays the cost; the rest skip the lookup entirely.
+const missingBestEffortNpmCache = new Set<string>();
+
 function canonicalPath(candidate: string): string {
   try {
     return realpathSync(candidate);
@@ -508,17 +525,84 @@ async function assertConfiguredNpmVersion(
   }
 }
 
+/** Result of resolving a provider's allowlisted extension sources. */
+interface ProviderExtensionResolution {
+  /** User-scope package roots to inject as subagent extension paths. */
+  paths: string[];
+  /** Roots originating from shipped best-effort defaults; these may degrade
+   * silently — see the drop-site comments for why silence is the design. */
+  bestEffortPaths: Set<string>;
+}
+
+/**
+ * UI notifier for the provider-extension-loaded notice, primed from
+ * extension.ts `execute` (the only place the real, ui-bearing ctx exists —
+ * host-dep construction itself has no UI context). Consumed defensively:
+ * a throw means the ctx went stale (headless run, torn-down TUI) and simply
+ * un-primes the notifier so the next live execute re-primes it.
+ */
+let providerExtensionNotifier: ((message: string) => void) | undefined;
+
+/**
+ * Prime the UI notifier used for the best-effort extension-loaded notice.
+ * Idempotent and cheap; called at the top of every delegate execute. Pass
+ * `undefined` to un-prime (tests) — an un-primed notifier makes the notice a
+ * no-op, which is also the default state in headless/test runs.
+ */
+export function registerProviderExtensionNotifier(
+  notify: ((message: string) => void) | undefined,
+): void {
+  providerExtensionNotifier = notify;
+}
+
+/** provider+root pairs already noticed this process. */
+const noticedProviderExtensionRoots = new Set<string>();
+
+/**
+ * Announce that a shipped best-effort provider integration actually loaded
+ * for delegated subagents. This is the deliberate inverse of the silent
+ * drop: absence of an optional integration is normal and never mentioned,
+ * but a default that IS active changes subagent behavior (remote compaction
+ * on codex models) invisibly — so it gets one info notice per process per
+ * provider+root, not one per dispatch. User-configured sources never get
+ * here: the user installed them knowingly and they fail closed.
+ */
+function noticeProviderExtensionLoaded(
+  provider: string | undefined,
+  root: string,
+): void {
+  const providerName = provider?.trim() || "provider";
+  const key = `${providerName.toLowerCase()}\0${root}`;
+  if (noticedProviderExtensionRoots.has(key)) return;
+  const notify = providerExtensionNotifier;
+  if (!notify) return;
+  const label = basename(root) || root;
+  try {
+    notify(`⚡ ${label} integration active for ${providerName} subagents`);
+    noticedProviderExtensionRoots.add(key);
+  } catch {
+    // Cosmetic notice on a stale ctx — fail open (status.ts precedent for
+    // cached-ctx notify): drop the notifier, keep the key un-noticed so a
+    // live ctx can still surface it later. Delegation is unaffected.
+    providerExtensionNotifier = undefined;
+  }
+}
+
 async function getProviderExtensionPaths(
   provider: string | undefined,
   cwd: string,
   agentDir: string,
   packageLookupSettingsManager: SettingsManager,
-): Promise<string[]> {
-  // Provider-key normalization (trim + lowercase) lives in `config.ts` —
-  // `getSubagentProviderExtensionsForProvider` is the single owner of that
-  // logic, so this module never re-implements it.
-  const requested = getSubagentProviderExtensionsForProvider(provider);
-  if (!requested.length) return [];
+): Promise<ProviderExtensionResolution> {
+  // Provider-key normalization (trim + lowercase) lives in `config.ts` — the
+  // sources getter is the single owner of that logic, so this module never
+  // re-implements it. Provenance (required vs best-effort) is decided there
+  // too, by config presence: user-listed sources fail closed; shipped
+  // defaults degrade silently — the extension-free path is Pi's normal
+  // operation, not a warning condition.
+  const requested = getSubagentProviderExtensionSourcesForProvider(provider);
+  if (!requested.length)
+    return { paths: [], bestEffortPaths: new Set<string>() };
 
   const packageManager = new DefaultPackageManager({
     cwd,
@@ -567,12 +651,34 @@ async function getProviderExtensionPaths(
 
   const installedPaths = new Map<string, string>();
   const missing: string[] = [];
-  for (const source of requested) {
+  for (const { source, required } of requested) {
+    // For best-effort npm defaults that are absent — the normal state for the
+    // shipped optional integration — avoid Pi's legacy global npm fallback
+    // (`npm root -g`) on every task in a fan-out. The first task in a dispatch
+    // still pays the cost to discover the absence, but subsequent tasks with
+    // the same agentDir+source skip the synchronous spawn entirely. The cache
+    // is per-dispatch and cleared on invalidateHostDepsCache.
+    if (!required && source.trim().toLowerCase().startsWith("npm:")) {
+      const missingKey = `${agentDir}\0${source}`;
+      if (missingBestEffortNpmCache.has(missingKey)) {
+        continue;
+      }
+      const userPath = packageManager.getInstalledPath(source, "user");
+      if (!userPath) {
+        missingBestEffortNpmCache.add(missingKey);
+        continue;
+      }
+      installedPaths.set(source, userPath);
+      continue;
+    }
     // Deliberately resolve only the user scope. Project-local packages are
     // untrusted input and must never become executable subagent extensions.
     const userPath = packageManager.getInstalledPath(source, "user");
     if (!userPath) {
-      missing.push(source);
+      if (required) missing.push(source);
+      // A best-effort default that is not installed is skipped silently: for
+      // most users the package was never installed at all, and its absence is
+      // the normal, correct state — not something to warn about.
       continue;
     }
     installedPaths.set(source, userPath);
@@ -587,23 +693,29 @@ async function getProviderExtensionPaths(
   }
 
   const paths = new Set<string>();
-  for (const source of requested) {
+  const bestEffortPaths = new Set<string>();
+  for (const { source, required } of requested) {
     const userPath = installedPaths.get(source);
-    // Every requested source was collected above; this guard keeps the map
-    // boundary explicit if that invariant changes later.
-    if (!userPath) {
-      throw new Error(
-        "A configured provider extension disappeared before validation; delegation stopped.",
-      );
-    }
-    validateInstalledPath(source, userPath);
-    if (hasNpmVersionSpecifier(source)) {
-      await assertConfiguredNpmVersion(packageManager, source, userPath);
+    // Best-effort defaults that were not installed never reached the map.
+    if (!userPath) continue;
+    try {
+      validateInstalledPath(source, userPath);
+      if (hasNpmVersionSpecifier(source)) {
+        await assertConfiguredNpmVersion(packageManager, source, userPath);
+      }
+    } catch (error) {
+      if (required) throw error;
+      // A best-effort default that cannot be verified is skipped, not loaded
+      // and not fatal. Silent by design: an installed-but-broken package also
+      // fails in the parent's own extension inventory, where Pi surfaces it;
+      // this path only mirrors a signal the user has already seen.
+      continue;
     }
     paths.add(userPath);
+    if (!required) bestEffortPaths.add(userPath);
   }
 
-  return [...paths];
+  return { paths: [...paths], bestEffortPaths };
 }
 
 /**
@@ -646,14 +758,16 @@ export async function getHostDeps(options: HostDepsOptions): Promise<HostDeps> {
       .map(([provider, entries]) => [provider, [...entries]] as const),
   );
   const providerConfigs = options.providerConfigs ?? [];
-  const requestedExtensions = getSubagentProviderExtensionsForProvider(
+  const requestedExtensions = getSubagentProviderExtensionSourcesForProvider(
     options.modelProvider,
   );
 
-  // Resolve provider extensions before deciding whether to use the cache. This
-  // fails closed for missing sources while keeping both package lookup and child
-  // resource loading isolated from executable project settings.
+  // Resolve provider extensions before deciding whether to use the cache.
+  // User-configured sources fail closed when missing; shipped defaults are
+  // best-effort and silently drop instead. Both package lookup and child
+  // resource loading stay isolated from executable project settings.
   let additionalExtensionPaths: string[] = [];
+  let bestEffortExtensionRoots = new Set<string>();
   if (requestedExtensions.length > 0) {
     // Package lookup is a user-scope trust boundary. Pi's legacy npm fallback
     // may execute the configured npmCommand to discover the global npm root,
@@ -663,12 +777,14 @@ export async function getHostDeps(options: HostDepsOptions): Promise<HostDeps> {
       agentDir,
       { projectTrusted: false },
     );
-    additionalExtensionPaths = await getProviderExtensionPaths(
+    const resolution = await getProviderExtensionPaths(
       options.modelProvider,
       options.cwd,
       agentDir,
       packageLookupSettingsManager,
     );
+    additionalExtensionPaths = resolution.paths;
+    bestEffortExtensionRoots = resolution.bestEffortPaths;
   }
 
   // Provider configs may contain functions (custom stream/OAuth handlers), so a
@@ -731,65 +847,111 @@ export async function getHostDeps(options: HostDepsOptions): Promise<HostDeps> {
     if (testRetryBaseMs !== undefined) {
       installFastRetry(resolvedSettingsManager, testRetryBaseMs);
     }
-    const resourceLoader = new DefaultResourceLoader({
-      cwd: options.cwd,
-      agentDir,
-      settingsManager: resolvedSettingsManager,
-      // Subagents are headless workers — they must not load the parent's
-      // interactive extension inventory. The only paths supplied here are the
-      // explicitly allowlisted, user-scoped provider extensions.
-      noExtensions: true,
-      // Global AGENTS.md files describe the parent harness, not the delegated
-      // task. Keep cwd/ancestor project context discovery, but remove Pi's
-      // global file and the legacy ~/.agents equivalent. This override also
-      // handles symlinked global files because it compares discovered paths.
-      agentsFilesOverride: ({ agentsFiles }) => ({
-        agentsFiles: agentsFiles.filter(
-          ({ path: contextPath }) =>
-            !isExcludedGlobalContextFile(contextPath, agentDir),
-        ),
-      }),
-      ...(additionalExtensionPaths.length ? { additionalExtensionPaths } : {}),
-      // When a named agent supplies a custom prompt, it becomes the loader's
-      // customPrompt — overriding the default system prompt AgentSession would
-      // otherwise build. `systemPrompt` (the source) wins over file discovery.
-      ...(options.systemPrompt !== undefined
-        ? { systemPrompt: options.systemPrompt }
-        : {}),
-    });
-    await resourceLoader.reload();
-
-    const extensionsResult = resourceLoader.getExtensions();
-    const extensionErrors = extensionsResult.errors;
-    const loadedExtensionPaths = extensionsResult.extensions.map(
-      (extension) => extension.resolvedPath || extension.path,
-    );
-    // A package can resolve successfully while exposing only skills/prompts,
-    // or a malformed manifest can expose no loadable extension at all. Treat
-    // that as a failed provider integration rather than silently delegating
-    // without the safety-critical behavior the allowlist requested.
-    const missingExtensionRoots = additionalExtensionPaths.filter(
-      (root) =>
-        !loadedExtensionPaths.some((extensionPath) =>
-          isPathWithinDirectory(root, extensionPath),
-        ),
-    );
-    if (extensionErrors.length > 0 || missingExtensionRoots.length > 0) {
+    // Best-effort default sources that fail to load are dropped and the loader
+    // is rebuilt without them, so the subagent runs extension-free on Pi's
+    // native compaction — silently, per the drop-site rationale above.
+    // User-configured sources still fail closed below.
+    //
+    // Loop invariant: pi's ResourceLoader.reload() never *throws* for an
+    // extension's own failure — its loader wraps module import AND factory
+    // invocation in try/catch and returns them as `extensionsResult.errors`
+    // (verified in pi 0.80.x, core/extensions/loader.ts). A reload() throw is
+    // therefore environmental (settings reload, package resolution) and not
+    // attributable to any supplied root; letting it propagate is correct even
+    // when best-effort roots are present.
+    let extensionPaths = additionalExtensionPaths;
+    let resourceLoader: DefaultResourceLoader;
+    for (;;) {
+      resourceLoader = new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir,
+        settingsManager: resolvedSettingsManager,
+        // Subagents are headless workers — they must not load the parent's
+        // interactive extension inventory. The only paths supplied here are
+        // the explicitly allowlisted, user-scoped provider extensions.
+        noExtensions: true,
+        // Global AGENTS.md files describe the parent harness, not the
+        // delegated task. Keep cwd/ancestor project context discovery, but
+        // remove Pi's global file and the legacy ~/.agents equivalent. This
+        // override also handles symlinked global files because it compares
+        // discovered paths.
+        agentsFilesOverride: ({ agentsFiles }) => ({
+          agentsFiles: agentsFiles.filter(
+            ({ path: contextPath }) =>
+              !isExcludedGlobalContextFile(contextPath, agentDir),
+          ),
+        }),
+        ...(extensionPaths.length
+          ? { additionalExtensionPaths: extensionPaths }
+          : {}),
+        // When a named agent supplies a custom prompt, it becomes the loader's
+        // customPrompt — overriding the default system prompt AgentSession
+        // would otherwise build. `systemPrompt` (the source) wins over file
+        // discovery.
+        ...(options.systemPrompt !== undefined
+          ? { systemPrompt: options.systemPrompt }
+          : {}),
+      });
+      await resourceLoader.reload();
+
+      const extensionsResult = resourceLoader.getExtensions();
+      const extensionErrors = extensionsResult.errors;
+      const loadedExtensionPaths = extensionsResult.extensions.map(
+        (extension) => extension.resolvedPath || extension.path,
+      );
+      // A package can resolve successfully while exposing only skills/prompts,
+      // or a malformed manifest can expose no loadable extension at all.
+      const missingExtensionRoots = extensionPaths.filter(
+        (root) =>
+          !loadedExtensionPaths.some((extensionPath) =>
+            isPathWithinDirectory(root, extensionPath),
+          ),
+      );
       const failedRoots = new Set(
         missingExtensionRoots.concat(
-          additionalExtensionPaths.filter((root) =>
+          extensionPaths.filter((root) =>
             extensionErrors.some((error) =>
               isPathWithinDirectory(root, error.path),
             ),
           ),
         ),
       );
-      const failureCount = Math.max(failedRoots.size, extensionErrors.length);
-      const providerName =
-        options.modelProvider?.trim() || "the selected provider";
-      throw new Error(
-        `Failed to load ${failureCount} allowlisted provider extension(s) for ${providerName}; delegation stopped instead of running without the required integration.`,
+      // An error inside a best-effort root is attributable to that root; any
+      // other error (including one no supplied root claims) stays fatal.
+      const fatalErrors = extensionErrors.filter(
+        (error) =>
+          ![...bestEffortExtensionRoots].some((root) =>
+            isPathWithinDirectory(root, error.path),
+          ),
+      );
+      const fatalRoots = [...failedRoots].filter(
+        (root) => !bestEffortExtensionRoots.has(root),
+      );
+      if (fatalErrors.length > 0 || fatalRoots.length > 0) {
+        const failureCount = Math.max(fatalRoots.length, fatalErrors.length);
+        const providerName =
+          options.modelProvider?.trim() || "the selected provider";
+        throw new Error(
+          `Failed to load ${failureCount} allowlisted provider extension(s) for ${providerName}; delegation stopped instead of running without the required integration.`,
+        );
+      }
+      const droppableRoots = [...failedRoots].filter((root) =>
+        bestEffortExtensionRoots.has(root),
       );
+      if (droppableRoots.length === 0) break;
+      extensionPaths = extensionPaths.filter(
+        (root) => !droppableRoots.includes(root),
+      );
+    }
+
+    // Positive visibility for the invisible-by-design path: surviving
+    // best-effort roots each produced at least one loaded extension, and
+    // that changes subagent behavior without any user action — the one
+    // state worth a notice. Once per process per provider+root.
+    for (const root of extensionPaths) {
+      if (bestEffortExtensionRoots.has(root)) {
+        noticeProviderExtensionLoaded(options.modelProvider, root);
+      }
     }
 
     return {
@@ -840,6 +1002,7 @@ export function invalidateHostDepsCache(): void {
   hostDepsCacheGeneration++;
   hostDepsCache.clear();
   hostDepsInflight.clear();
+  missingBestEffortNpmCache.clear();
 }
 
 /** Test-only alias retained for existing test setup. */
@@ -860,6 +1023,7 @@ export function _setModelRuntimeFactoryForTesting(
   testModelRuntimeFactory = factory;
   hostDepsCache.clear();
   hostDepsInflight.clear();
+  missingBestEffortNpmCache.clear();
 }
 
 /**
@@ -883,6 +1047,7 @@ export function _setHostRetryBaseMsForTesting(
     // ensures newly-built ones come back unpatched.
     hostDepsCache.clear();
     hostDepsInflight.clear();
+    missingBestEffortNpmCache.clear();
     return;
   }
   for (const deps of hostDepsCache.values()) {

package/manual.ts

@@ -39,7 +39,7 @@ function schemaTable(properties: Record<string, TSchema>): string {
 export function getSubagentManualMarkdown(
   agents: Map<string, AgentConfig>,
 ): string {
-  const entries = [...agents];
+  const entries = [...agents].filter(([, a]) => !a.builtin);
   const agentList = entries.length
     ? entries
         .map(([n, a]) => {
@@ -95,11 +95,14 @@ export function getSubagentManualMarkdown(
     "- Git failures degrade to an empty diff.",
     "- A path missing from `touched:` does **not** mean the file was unchanged. Delegate does not isolate file access or roll back writes.",
     "",
-    "## Built-in Agent",
+    "## Built-in Agents",
     "",
-    "- **default**: mirrors the live parent model, thinking level, delegatable native tools, and base system prompt.",
+    "- **default**: mirrors the live parent model, thinking level, delegatable native tools, and base prompt. It uses the shared workspace.",
+    "- **scout**: investigates without modifying files. Tools: `read`, `grep`, `find`, `ls`. Shared workspace.",
+    "- **coder**: implements and verifies changes. Tools: `read`, `write`, `edit`, `bash`. Shared workspace.",
+    '- **reviewer**: reviews the current snapshot and reports findings. Tools: `read`, `bash`. Defaults to a disposable scratch workspace; set `workspace: "shared"` for a persistent reviewer with `sessionId`.',
     "",
-    "Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context is rebuilt safely for the task's `cwd`; per-task fields remain explicit overrides.",
+    "Fresh built-ins inherit the parent's exact model object and thinking level unless task fields or settings override them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
     "",
     "## Available Custom Agents",
     "",
@@ -199,7 +202,7 @@ export function getSubagentManualMarkdown(
     "- Dispatch validation is batch-wide and runs before spawning: one invalid task rejects the call without starting its siblings.",
     "- `*` means read/write/edit/bash, not every tool. `grep`, `find`, and `ls` are valid explicit tools and are the `ro` preset.",
     '- `tasks` is an array. The tool recovers common stringified calls for compatibility, but canonical calls use `{ tasks: [{ prompt: "..." }] }`.',
-    '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Omitting `agent` creates an ad-hoc task with delegate defaults.',
+    '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Built-ins are `default`, `scout`, `coder`, and `reviewer`; omitting `agent` creates an ad-hoc task.',
     "- An ad-hoc task with no `tools` uses `*`; a named custom task uses its profile; a profile with no tools uses `*`.",
     "- Subagents inherit all skills discovered in their `cwd` (via AgentSession's resource loader). Per-task skill filtering is not supported — curate the cwd's skill set instead.",
     `- Sync \`delegate\` runs at most ${getMaxConcurrent()} tasks at once (the rest queue, not fail). Use \`async: true\` to move work to the background.`,
@@ -211,7 +214,7 @@ export function getSubagentManualMarkdown(
     "",
     "## Config",
     "",
-    "Tunables live in `~/.pi/agent/delegate.json`: `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, and per-agent model overrides.",
+    "Tunables live in `~/.pi/agent/delegate.json`: `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, and legacy custom-agent model overrides. Built-in model/thinking/tools overrides live in `settings.json`; `agentOverridesByParentModel` uses an exact `provider/model-id` key and project settings take precedence.",
     "The inactivity watchdog requests cooperative `AgentSession.abort()` cancellation and waits for the subagent to become idle; it is not a hard wall-clock execution deadline.",
     "",
     `Output bounding: subagent outputs longer than ${OUTPUT_SPILL_THRESHOLD_CHARS} characters are spilled to a temp file, and only the last ${OUTPUT_SPILL_TAIL_CHARS} characters stay in the LLM-facing result. Adjust with \`output.spillThresholdChars\` and \`output.spillTailChars\`. Spill files are written to the system temp directory with owner-only permissions; the full output is always available in the expanded TUI view and the spilled file.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/schema.ts

@@ -40,7 +40,7 @@ export const delegateTaskSchema = Type.Object({
   agent: Type.Optional(
     Type.String({
       description:
-        "Use `default`: parent model/thinking/native tools/base prompt. Omit=ad-hoc; unknown fails call.",
+        "Built-ins: default, scout, coder, reviewer. Reviewer defaults to one-shot scratch. Omit for ad-hoc.",
     }),
   ),
   cwd: Type.Optional(
@@ -106,8 +106,7 @@ export const delegateTaskSchema = Type.Object({
   workspace: Type.Optional(
     StringEnum(["shared", "scratch"], {
       description:
-        "scratch=disposable CoW project copy; relative edits are discarded. Not security isolation. Default=shared.",
-      default: "shared",
+        "shared source; scratch disposable copy, one-shot; not security isolation. Reviewer=scratch; others=shared.",
     }),
   ),
 });
@@ -327,9 +326,10 @@ export function validateDelegateOperation(
     }
     if (
       task.workspace === "scratch" &&
+      !task.agent &&
       (task.sessionId || task.resumeFrom || sessionAction !== undefined)
     ) {
-      return `task ${index + 1}: workspace 'scratch' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction.`;
+      return `task ${index + 1}: workspace 'scratch' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction. Set workspace: "shared" to use a persistent agent.`;
     }
     if (sessionAction === "close") {
       if (!task.sessionId) {