@bermudi/pi-delegate 0.1.11 → 0.1.13

package/lifecycle.ts

@@ -70,11 +70,15 @@ export function _setWholeTaskRetryForTesting(
   testWholeTaskBaseDelayMs = opts?.baseDelayMs;
 }
 
-function resolvedWholeTaskMaxRetries(): number {
-  return testWholeTaskMaxRetries ?? getWholeTaskMaxRetries();
+function resolvedWholeTaskMaxRetries(env: TaskRunEnv): number {
+  return (
+    testWholeTaskMaxRetries ?? getWholeTaskMaxRetries(env.config ?? undefined)
+  );
 }
-function resolvedWholeTaskBaseDelayMs(): number {
-  return testWholeTaskBaseDelayMs ?? getWholeTaskBaseDelayMs();
+function resolvedWholeTaskBaseDelayMs(env: TaskRunEnv): number {
+  return (
+    testWholeTaskBaseDelayMs ?? getWholeTaskBaseDelayMs(env.config ?? undefined)
+  );
 }
 
 /** Build a failed TaskResult. Used for early-failure paths (abort, busy, validation). */
@@ -254,6 +258,7 @@ function recordTaskOutcome(
     recordTask({
       callId: env.telemetryCallId,
       generation: env.telemetryGeneration,
+      telemetryConfig: env.telemetryConfig,
       async: env.async ?? false,
       taskIndex: p.index,
       task,
@@ -385,7 +390,7 @@ async function sleepForWholeTaskRetry(
 async function buildDelegateSession(
   task: ResolvedTask,
   sessionManager: SessionManager,
-  modelRegistry: TaskRunEnv["modelRegistry"],
+  env: TaskRunEnv,
 ): Promise<AgentSession> {
   // Resolve host deps for this task's cwd + system prompt. Extension-free
   // resource loaders are cached after the first call; provider-configured or
@@ -396,7 +401,7 @@ async function buildDelegateSession(
   // Pass only the provider needed by this task. This keeps a non-Kilo task
   // from receiving Kilo's provider/auth adapter merely because Kilo is also
   // configured in the parent runtime.
-  const providerConfig = modelRegistry.getRegisteredProviderConfig?.(
+  const providerConfig = env.modelRegistry.getRegisteredProviderConfig?.(
     task.model.provider,
   );
   const providerConfigs = providerConfig
@@ -407,6 +412,10 @@ async function buildDelegateSession(
     systemPrompt: task.systemPrompt,
     providerConfigs,
     modelProvider: task.model.provider,
+    // Freeze the provider-extension allowlist to the dispatch-scoped snapshot
+    // so a later delegate.json edit cannot change which executable code an
+    // already-spawned async worker is allowed to load.
+    delegateConfig: env.config,
   });
 
   const { session } = await createAgentSession({
@@ -444,11 +453,16 @@ function checkoutPooledSession(
     cwd: task.cwd,
     thinking: task.thinking,
     tools: task.tools,
+    providerExtensions: task.providerExtensionSources ?? "",
     ...task.reuseIntent,
   });
   if (co.status === "mismatch") {
     const detail = co.mismatches
-      .map((m) => `${m.field}: '${m.frozen}' vs '${m.requested}'`)
+      .map((m) =>
+        m.field === "providerExtensions"
+          ? "providerExtensions: changed"
+          : `${m.field}: '${m.frozen}' vs '${m.requested}'`,
+      )
       .join("; ");
     return {
       error: failTask(
@@ -529,7 +543,7 @@ async function resumeFromSessionFile(
     };
   }
 
-  const session = await buildDelegateSession(task, resumed, env.modelRegistry);
+  const session = await buildDelegateSession(task, resumed, env);
   return {
     session,
     sessionManager: resumed,
@@ -544,7 +558,7 @@ async function createFreshSession(
 ): Promise<AcquireResult> {
   let sessionManager: SessionManager;
   let sessionFile: string | undefined;
-  if (task.workspace === "scratch") {
+  if (task.workspace === "scratch" || task.workspace === "isolated") {
     // A discarded filesystem must not advertise a resumable conversation: a
     // later resume would run against the source cwd and silently lose scratch
     // isolation. Keep scratch transcripts in memory only.
@@ -560,11 +574,7 @@ async function createFreshSession(
     sessionFile = fresh.file;
   }
 
-  const session = await buildDelegateSession(
-    task,
-    sessionManager,
-    env.modelRegistry,
-  );
+  const session = await buildDelegateSession(task, sessionManager, env);
   return {
     session,
     sessionManager,
@@ -635,6 +645,24 @@ async function runResolvedTaskUnlocked(
   p: TaskProgress,
   taskIndex: number,
 ): Promise<TaskResult> {
+  if (
+    task.workspace === "isolated" &&
+    (task.sessionId || task.resumeFrom || task.sessionAction)
+  ) {
+    return recordTaskOutcome(
+      env,
+      p,
+      task,
+      finishTask(
+        env,
+        p,
+        failTask(
+          task,
+          "workspace 'isolated' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction.",
+        ),
+      ),
+    );
+  }
   if (task.workspace !== "scratch") {
     const outcome = await runResolvedTaskCore(env, task, p, taskIndex);
     return recordTaskOutcome(env, p, task, outcome);
@@ -944,6 +972,7 @@ async function settlePooledAttempt(
           thinking: task.thinking,
           tools: task.tools,
           cwd: task.cwd,
+          providerExtensions: task.providerExtensionSources ?? "",
         },
         tokens: r.tokens,
       });
@@ -1035,6 +1064,7 @@ async function runTaskAttempt(
       gitBaseline,
       timing.taskStartedAt,
       timing.deadlineAt,
+      env.config,
     );
 
     accounting.cumulativeTokens += r.tokens;
@@ -1159,8 +1189,12 @@ async function runWithWholeTaskRetries(
     };
   }
 
-  const maxRetries = resolvedWholeTaskMaxRetries();
-  const baseDelayMs = resolvedWholeTaskBaseDelayMs();
+  // An isolated worker is snapshotted once and reconciled once. Retrying the
+  // whole conversation against a mutated proposal tree would make attribution
+  // ambiguous, so v1 deliberately runs one attempt.
+  const maxRetries =
+    task.workspace === "isolated" ? 0 : resolvedWholeTaskMaxRetries(env);
+  const baseDelayMs = resolvedWholeTaskBaseDelayMs(env);
   let retries = 0;
   for (
     let retry = 0;

package/manual.ts

@@ -110,7 +110,7 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ agent: "default", prompt: "Investigate the auth module" }] })',
     "```",
     "",
-    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation but uses the real filesystem at its task `cwd`; tasks sharing a directory can observe and overwrite one another's changes. Fresh prompts must therefore be self-contained, and dependent or shared-file work should run separately.",
+    'Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation. A batch with multiple write-capable tasks in one shared tree is rejected before dispatch; run them sequentially, use synchronous one-shot `workspace: "isolated"` for Git-backed ordered reconciliation, or use disposable scratch workspaces.',
     "",
     "The three handles have different lifetimes:",
     "",
@@ -120,6 +120,8 @@ export function getSubagentManualMarkdown(
     "",
     "Each task entry may also carry an optional `id` — a caller-provided per-dispatch correlation key. Duplicate `id` values in the same call are rejected; when omitted, tasks are identified by array index, agent, and prompt.",
     "",
+    "Vocabulary, since 'agent' does double duty elsewhere: a **task** is one job; an **agent** is a named profile — a saved bundle of system prompt, tools, workspace, and model policy — that a task references by `agent` name; a **subagent** is the live session that executes one task. Agents are templates, not processes; nothing runs until a task dispatches.",
+    "",
     "Subagents cannot call `delegate` recursively. Their tool activity runs at `cwd`, while Pi stores the runtime session transcript in its own session directory outside that `cwd`.",
     "",
     "## Touched Files (best-effort)",
@@ -136,13 +138,13 @@ export function getSubagentManualMarkdown(
     "",
     ...builtinLines,
     "",
-    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, settings overrides (`settings.json` `delegate.agentOverrides` and `delegate.agentOverridesByParentModel`) win over the Markdown file; `default` ignores settings and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes 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.",
+    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes 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",
     "",
     agentList,
     "",
-    "Custom agents are defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Markdown agents are examples of custom agents — the parent model can shape the subagent it needs on each call. Each Markdown file is an agent with YAML frontmatter:",
+    "Custom agents are profiles, defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Inline definitions let the parent model shape the subagent it needs on each call. Each Markdown file is one profile with YAML frontmatter:",
     "",
     "```markdown",
     "---",
@@ -165,26 +167,26 @@ export function getSubagentManualMarkdown(
     "## Session Reuse",
     "",
     "When `sessionId` is set, the subagent is kept alive in a pool for the duration of the pi session.",
-    "Subsequent calls with the same `sessionId` continue the conversation — the agent remembers prior context.",
+    "Subsequent calls with the same `sessionId` continue the conversation — the session retains prior context.",
     "",
     "```ts",
     "// First call — creates and runs an inline custom agent",
     'delegate({ tasks: [{ prompt: "Investigate the auth module", systemPrompt: "You are a focused investigator. Map files and dependencies.", tools: ["read", "grep", "find", "ls"], sessionId: "auth-research" }] })',
     "",
-    "// Second call — continues the same agent",
+    "// Second call — continues the same subagent",
     'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
     "",
     "// Clean up when done",
     'delegate({ tasks: [{ sessionId: "auth-research", sessionAction: "close" }] })',
     "```",
     "",
-    'Pooled agents remain live until `sessionAction: "close"` or parent Pi session shutdown.',
+    'Pooled sessions remain live until `sessionAction: "close"` or parent Pi session shutdown.',
     "",
     "## Resuming Previous Sessions",
     "",
     "Use `resumeFrom` to continue a failed or interrupted subagent from where it left off.",
     "Pass the exact absolute path to the session `.jsonl` file copied from delegate retry output. Do not invent placeholder values or use it as a ticket ID; async resume is supported.",
-    "The agent gets the full conversation history and the new `prompt` continues naturally.",
+    "The subagent gets the full conversation history and the new `prompt` continues naturally.",
     "",
     "```ts",
     "// Copy this exact path from the failed delegate result; do not invent it.",
@@ -193,7 +195,7 @@ export function getSubagentManualMarkdown(
     "  resumeFrom: exactRetrySessionFile }] })",
     "```",
     "",
-    "Combine with `sessionId` to resume AND pool the agent for further multi-turn use:",
+    "Combine with `sessionId` to resume AND pool the subagent for further multi-turn use:",
     "",
     "```ts",
     'delegate({ tasks: [{ prompt: "Continue the investigation",',
@@ -234,9 +236,11 @@ export function getSubagentManualMarkdown(
     "## Gotchas",
     "",
     "- Dispatch validation is batch-wide and runs before spawning: one invalid task rejects the call without starting its siblings.",
+    '- Shared writers that overlap tasks in the same call or a running sync/async dispatch are rejected. Unknown tools count as mutating. Run them sequentially, use `workspace: "isolated"` for Git-backed ordered reconciliation, or use `workspace: "scratch"` when changes may be discarded.',
     "- `*` 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. Built-ins are `default`, `scout`, `coder`, and `reviewer`; omitting `agent` creates an ad-hoc task.',
+    "- Omit `thinking` for named agents unless the user asks or the task clearly needs escalation — task-level `thinking` overrides every configured tier (`agentOverrides`, `agentOverridesByParentModel`, Markdown frontmatter, `:level` model suffix), so a casual value silently defeats the configured budget. Ad-hoc tasks default to the parent's thinking.",
     "- 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.`,
@@ -244,7 +248,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 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.",
+    "Tunables live in `~/.pi/agent/delegate.json` (user scope, global — no project-level config): `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, legacy custom-agent model overrides (`agent`), and agent model/thinking/tools overrides — `agentOverrides` and `agentOverridesByParentModel` (exact `provider/model-id` key of the parent model; wins over `agentOverrides` on match). Config edits apply from the next delegate call.",
     "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.11",
+  "version": "0.1.13",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/pool.ts

@@ -18,6 +18,10 @@ export interface FrozenConfig {
   thinking: ThinkingLevel;
   tools: string[];
   cwd: string;
+  /** Stable signature of the provider-scoped extension allowlist this session
+   * was built with. A change in `delegate.json` providerExtensions must force
+   * session recreation so the old executable runtime is not silently reused. */
+  providerExtensions?: string;
 }
 
 /** The subset a reuse request supplies for validation. `model` and
@@ -29,12 +33,20 @@ export interface ConfigCandidate {
   tools: string[];
   model?: Model<Api>;
   systemPrompt?: string;
+  /** Provider-scoped extension allowlist signature for the current dispatch. */
+  providerExtensions?: string;
 }
 
 /** One field-level diff from a reuse that conflicts with the frozen config. The
  * pool computes these; the caller formats the error string. */
 export interface ConfigMismatch {
-  field: "cwd" | "thinking" | "tools" | "model" | "systemPrompt";
+  field:
+    | "cwd"
+    | "thinking"
+    | "tools"
+    | "model"
+    | "systemPrompt"
+    | "providerExtensions";
   frozen: string;
   requested: string;
 }
@@ -189,6 +201,16 @@ export function checkout(
       requested: "<requested>",
     });
   }
+  if (frozen.providerExtensions !== candidate.providerExtensions) {
+    // This field is derived from configured package sources, which may contain
+    // credentials. Never expose either the sources or their digest through the
+    // public checkout result; a digest can still enable dictionary guessing.
+    mismatches.push({
+      field: "providerExtensions",
+      frozen: "<redacted>",
+      requested: "<redacted>",
+    });
+  }
   if (mismatches.length) return { status: "mismatch", mismatches };
 
   return {

package/provider-extensions.ts

@@ -35,7 +35,11 @@ import {
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { getSubagentProviderExtensionSourcesForProvider } from "./config.ts";
-import { canonicalPath, isPathWithinDirectory, isPathWithinDirectoryLexical } from "./trusted-paths.ts";
+import {
+  canonicalPath,
+  isPathWithinDirectory,
+  isPathWithinDirectoryLexical,
+} from "./trusted-paths.ts";
 import {
   parseGitOriginIdentity,
   parsePackageSource,
@@ -331,8 +335,13 @@ export async function getProviderExtensionPaths(
   provider: string | undefined,
   cwd: string,
   agentDir: string,
+  /** Dispatch-scoped snapshot for the provider-extension allowlist. */
+  config?: import("./config.ts").DelegateConfig,
 ): Promise<ProviderExtensionResolution> {
-  const requested = getSubagentProviderExtensionSourcesForProvider(provider);
+  const requested = getSubagentProviderExtensionSourcesForProvider(
+    provider,
+    config,
+  );
   if (!requested.length) {
     return { paths: [], bestEffortPaths: new Set<string>() };
   }

package/render-branches.ts

@@ -378,6 +378,36 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
     if (!isLive && !isCancelledPending && r && "error" in r && r.error) {
       lines.push(truncLine(`${ind}${theme.fg("error", r.error)}`, w));
     }
+    if (r && "integration" in r && r.integration) {
+      const integration = r.integration;
+      const tone =
+        integration.status === "applied_unverified" ||
+        integration.status === "no_changes"
+          ? "warning"
+          : "error";
+      lines.push(
+        truncLine(
+          `${ind}${theme.fg(tone, `integration: ${integration.status} · ${integration.appliedFiles.length}/${integration.proposedFiles.length} files applied`)}`,
+          w,
+        ),
+      );
+      if (expanded) {
+        if (integration.patchPath)
+          lines.push(
+            truncLine(
+              `${ind}${theme.fg("muted", `patch: ${integration.patchPath}`)}`,
+              w,
+            ),
+          );
+        if (integration.worktreePath)
+          lines.push(
+            truncLine(
+              `${ind}${theme.fg("muted", `worktree: ${integration.worktreePath}`)}`,
+              w,
+            ),
+          );
+      }
+    }
     // Collapsed: one-line output preview so a human scanning the TUI sees
     // the payoff without expanding every task. Expanded mode renders the
     // full markdown below instead.

package/render-result.ts

@@ -166,11 +166,14 @@ export function renderDelegateResult(
     ticketStatus,
   };
 
-  // Surface the touched-file overlap warning at the top of the TUI. The same
-  // text already lives in the textual content, but the progress-based renderer
-  // ignores content, so we must render it explicitly from details. Rendering it
-  // before the progress tree places it at the top of the budgeted region, so it
-  // survives truncation from the bottom when many tasks collapse the view.
+  // Surface batch-level warnings at the top of the TUI. The same text already
+  // lives in textual content, but the progress renderer ignores content.
+  if (details?.dispatchWarning) {
+    lines.push(
+      truncLine(theme.fg("warning", `⚠ ${details.dispatchWarning}`), w),
+      "",
+    );
+  }
   if (details?.overlapWarning) {
     lines.push(
       truncLine(theme.fg("warning", `⚠ ${details.overlapWarning}`), w),

package/runner.ts

@@ -72,6 +72,8 @@ export async function runAgentSession(
   gitBaseline: Set<string> | undefined,
   start: number,
   deadlineAt?: number,
+  /** Dispatch-scoped delegate.json snapshot for the stall timeout. */
+  delegateConfig?: import("./config.ts").DelegateConfig,
 ): Promise<{
   output: string;
   error?: string;
@@ -89,7 +91,7 @@ export async function runAgentSession(
   prompted: boolean;
 }> {
   const startTime = start ?? Date.now();
-  const stallTimeoutMs = getStallTimeoutMs();
+  const stallTimeoutMs = getStallTimeoutMs(delegateConfig);
   let toolUses = 0;
   let lastActivityAt: number | undefined = startTime;
   let phase = "starting agent";

package/schema.ts

@@ -42,7 +42,7 @@ export const delegateTaskSchema = Type.Object({
   agent: Type.Optional(
     Type.String({
       description:
-        "Built-ins: default, scout, coder, reviewer. Reviewer defaults to one-shot scratch. Omit for ad-hoc.",
+        "Agent profile name. Built-ins: default, scout, coder, reviewer. Omit for ad-hoc.",
     }),
   ),
   cwd: Type.Optional(
@@ -77,7 +77,7 @@ export const delegateTaskSchema = Type.Object({
   thinking: Type.Optional(
     StringEnum(VALID_THINKING_LEVELS, {
       description:
-        "Thinking: off/minimal/low/medium/high/xhigh/max; default=parent; others=agent/off.",
+        "off/minimal/low/medium/high/xhigh/max. Omit for agents — it overrides delegate.json tiers; default inherits.",
     }),
   ),
   sessionId: Type.Optional(
@@ -106,9 +106,9 @@ export const delegateTaskSchema = Type.Object({
     }),
   ),
   workspace: Type.Optional(
-    StringEnum(["shared", "scratch"], {
+    StringEnum(["shared", "scratch", "isolated"], {
       description:
-        "shared source; scratch disposable copy, one-shot; not security isolation. Reviewer=scratch; others=shared.",
+        "shared; scratch discarded; isolated=sync one-shot Git apply; not security isolation. Reviewer=scratch.",
     }),
   ),
 });
@@ -116,47 +116,50 @@ export const delegateTaskSchema = Type.Object({
 // Single source of truth for registration and generated help. The exported
 // argument types in types.ts project this canonical schema; providers see
 // only these fields.
-export const delegateArgumentsSchema = Type.Object({
-  ticketAction: Type.Optional(
-    StringEnum(["poll", "cancel", "wait"], {
-      description:
-        "Ticket control: poll=snapshot; wait=block until settled; cancel=abort. Prefer wait; never cancel for time.",
-    }),
-  ),
-  async: Type.Optional(
-    Type.Boolean({
-      description:
-        "Detach work, return a ticket; applies to ALL tasks. Results auto-deliver. Wait only if blocked.",
-      default: false,
-    }),
-  ),
-  ticket: Type.Optional(
-    Type.String({
-      description: "Ticket ID; omit only when polling all tickets.",
-    }),
-  ),
-  force: Type.Optional(
-    Type.Boolean({
-      description:
-        "With cancel: false previews active work; true confirms abort. Completed writes/commands remain.",
-      default: false,
-    }),
-  ),
-  timeoutMs: Type.Optional(
-    Type.Number({
-      minimum: 0,
-      description:
-        "Bounds wait (ms); omit to block until settled. Timeout returns a snapshot; do not poll afterward.",
-    }),
-  ),
-  tasks: Type.Optional(
-    Type.Array(delegateTaskSchema, {
-      minItems: 0,
-      description:
-        "Tasks run concurrently; shared workspaces share files. scratch uses a disposable CoW copy. []=full manual.",
-    }),
-  ),
-});
+export const delegateArgumentsSchema = Type.Object(
+  {
+    ticketAction: Type.Optional(
+      StringEnum(["poll", "cancel", "wait"], {
+        description:
+          "Ticket control: poll=snapshot; wait=block until settled; cancel=abort. Prefer wait; never cancel for time.",
+      }),
+    ),
+    async: Type.Optional(
+      Type.Boolean({
+        description:
+          "Detach work, return a ticket; applies to ALL tasks. Results auto-deliver. Wait only if blocked.",
+        default: false,
+      }),
+    ),
+    ticket: Type.Optional(
+      Type.String({
+        description: "Ticket ID; omit only when polling all tickets.",
+      }),
+    ),
+    force: Type.Optional(
+      Type.Boolean({
+        description:
+          "With cancel: false previews active work; true confirms abort. Completed writes/commands remain.",
+        default: false,
+      }),
+    ),
+    timeoutMs: Type.Optional(
+      Type.Number({
+        minimum: 0,
+        description:
+          "Bounds wait (ms); omit to block until settled. Timeout returns a snapshot; do not poll afterward.",
+      }),
+    ),
+    tasks: Type.Optional(
+      Type.Array(delegateTaskSchema, {
+        minItems: 0,
+        description:
+          "Tasks run concurrently; shared workspaces share files. scratch uses a disposable CoW copy. []=full manual.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
 
 /** Fields that belong to a task entry. Models sometimes place these at the top
  * level of the arguments; the shim folds them back into a single task. */
@@ -238,6 +241,10 @@ export function validateDelegateOperation(
       : undefined; // Intentional help request.
   }
 
+  if (params.async && tasks.some((task) => task.workspace === "isolated")) {
+    return 'workspace "isolated" is synchronous; remove async.';
+  }
+
   // Reject mixed shapes: flat task fields at the top level alongside a
   // nonempty tasks array. The normalize shim only wraps flat fields when
   // there is no tasks array, so a mixed call silently lets tasks win —
@@ -263,13 +270,14 @@ export function validateDelegateOperation(
       (key) => !VALID_TASK_KEYS.has(key),
     );
     if (unknownKeys.length) {
-      const asyncHint = unknownKeys.includes("async")
-        ? " 'async' is a top-level flag; move it out of the task entry."
+      const misplacedTopLevel = unknownKeys.filter((key) => key === "async");
+      const topLevelHint = misplacedTopLevel.length
+        ? ` ${misplacedTopLevel.map((key) => `'${key}'`).join(" and ")} ${misplacedTopLevel.length === 1 ? "is a" : "are"} top-level flag${misplacedTopLevel.length === 1 ? "" : "s"}; move ${misplacedTopLevel.length === 1 ? "it" : "them"} out of the task entry.`
         : "";
       return (
         `task ${index + 1}: unknown field(s) ${unknownKeys
           .map((key) => `'${key}'`)
-          .join(", ")}.${asyncHint} ` +
+          .join(", ")}.${topLevelHint} ` +
         `Valid task fields: ${[...VALID_TASK_KEYS].join(", ")}.`
       );
     }
@@ -282,11 +290,10 @@ export function validateDelegateOperation(
       return `task ${index + 1}: deadlineMs must be a positive number of milliseconds.`;
     }
     if (
-      task.workspace === "scratch" &&
-      !task.agent &&
+      (task.workspace === "scratch" || task.workspace === "isolated") &&
       (task.sessionId || task.resumeFrom || sessionAction !== undefined)
     ) {
-      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.`;
+      return `task ${index + 1}: workspace '${task.workspace}' 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) {