@bermudi/pi-delegate 0.1.15 → 0.1.16

package/agents.ts

@@ -120,7 +120,7 @@ export const BUILTIN_AGENT_CONFIGS: Readonly<Record<string, AgentConfig>> = {
   [DEFAULT_AGENT_NAME]: {
     name: DEFAULT_AGENT_NAME,
     description:
-      "Mirror the live parent model, thinking level, native tools, and base prompt.",
+      "General-purpose subagent mirroring the live parent model, thinking level, native tools, and base prompt. Prefer it for general work; pick a specialist only when its role, tool limits, or scratch workspace genuinely fit.",
     tools: DEFAULT_TOOLS,
     systemPrompt: "",
     builtin: true,

package/constants.ts

@@ -59,3 +59,13 @@ export const VALID_THINKING_LEVELS = [
  *  `Set<VALID_THINKING_LEVELS[number]>`) so the `.has(string)` call sites in
  *  task-resolution.ts and agents.ts stay ergonomic under strict typing. */
 export const VALID_THINKING: Set<string> = new Set(VALID_THINKING_LEVELS);
+
+/** Session-control actions: RPC against the session pool, not work. Callers
+ *  spell them at the TOP level (`sessionAction`, one action per call — #32).
+ *  This predicate remains the one shared spelling of the control set for the
+ *  session-mode intent check and validator in schema.ts and the pipeline
+ *  guards over internally bridged tasks (task-resolution.ts). Per-action
+ *  behavior lives at the branch sites (e.g. lifecycle applySessionAction). */
+export function isSessionControlAction(action: unknown): boolean {
+  return action === "close" || action === "list";
+}

package/delegate.ts

@@ -3,6 +3,7 @@ export { default } from "./extension.ts";
 export type {
   AgentConfig,
   SessionAction,
+  DispatchableTask,
   WorkspaceMode,
   TicketAction,
   DelegateArguments,

package/dispatch.ts

@@ -48,6 +48,7 @@ import type {
   DelegateToolResult,
   ParentAgentDefaults,
   ResolvedTask,
+  DispatchableTask,
   TaskDef,
   TaskProgress,
   TaskResult,
@@ -58,7 +59,7 @@ const UNSAFE_SHARED_WRITES_WARNING =
   "UNSAFE SHARED WRITES ENABLED: shared-write admission is bypassed. Delegate provides no isolation or rollback.";
 
 interface ActiveSyncDispatch {
-  tasks: TaskDef[];
+  tasks: DispatchableTask[];
   resolved: ResolvedTask[];
 }
 
@@ -157,7 +158,7 @@ export function makeFireUpdater(
 export interface AsyncDispatchInput {
   pi: ExtensionAPI;
   ctx: DelegateToolCtx;
-  tasks: TaskDef[];
+  tasks: DispatchableTask[];
   resolved: ResolvedTask[];
   progress: TaskProgress[];
   parentModelId: string | undefined;
@@ -169,7 +170,7 @@ export interface AsyncDispatchInput {
 /** Inputs needed by the sync (blocking) dispatch path. */
 export interface SyncDispatchInput {
   ctx: DelegateToolCtx;
-  tasks: TaskDef[];
+  tasks: DispatchableTask[];
   resolved: ResolvedTask[];
   progress: TaskProgress[];
   parentModelId: string | undefined;
@@ -193,7 +194,7 @@ export interface DelegateDispatchInput {
   callSpan?: CallSpan;
 }
 
-function taskReference(task: TaskDef, index: number): string {
+function taskReference(task: DispatchableTask, index: number): string {
   return `Task ${index + 1}${task.id ? `#${task.id}` : ""}`;
 }
 
@@ -207,7 +208,7 @@ function asAdmissionWriter(task: ResolvedTask): ResolvedTask {
 }
 
 function sharedWriteRejection(
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   parentModelId: string | undefined,
   conflicts: SharedWriteConflict[],
   references: readonly string[] = tasks.map(taskReference),
@@ -236,7 +237,7 @@ function sharedWriteRejection(
 }
 
 function sharedWriteSafetyFailure(
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   parentModelId: string | undefined,
   error: unknown,
 ): DelegateToolResult {
@@ -289,13 +290,26 @@ export async function dispatchDelegate(
     return validationError;
   }
 
-  const resolved = resolveTasks(
+  const resolveResult = resolveTasks(
     tasks,
     ctx,
     agents,
     parentDefaults,
     dispatchConfig,
   );
+  if (resolveResult.error !== undefined) {
+    callSpan?.finish({
+      status: "failed",
+      totalTokens: 0,
+      totalCost: 0,
+      wallMs: Date.now() - callSpan.startedAt,
+    });
+    return {
+      content: [{ type: "text", text: resolveResult.error }],
+      details: { tasks, results: [], progress: [], parentModel: parentModelId },
+    };
+  }
+  const resolved = resolveResult.tasks;
   if (params.async && resolved.some((task) => task.workspace === "isolated")) {
     callSpan?.finish({
       status: "failed",

package/extension.ts

@@ -44,7 +44,11 @@ import {
   prepareTelemetryForSession,
   sealTelemetryWrites,
 } from "./telemetry.ts";
-import type { DelegateArguments, DelegateDetails } from "./types.ts";
+import type {
+  DelegateArguments,
+  DelegateDetails,
+  DispatchableTask,
+} from "./types.ts";
 
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 10_000;
 let shutdownDrainTimeoutMs = DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
@@ -52,6 +56,17 @@ let shutdownDrainTimeoutMs = DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
 type ShutdownDrainResult =
   { drained: true; failures: unknown[] } | { drained: false; failures: [] };
 
+/** Bridge the promoted top-level session RPC (`sessionAction` + `sessionId`)
+ * to the internal single-entry batch the runner executes. Internal only — the
+ * public task schema has no `sessionAction`; validation guarantees close
+ * carries a sessionId by this point. */
+function bridgeSessionControlTask(params: DelegateArguments): DispatchableTask {
+  return {
+    ...(params.sessionId ? { sessionId: params.sessionId } : {}),
+    sessionAction: params.sessionAction,
+  };
+}
+
 /** Wait for shutdown workers without allowing a stuck provider/tool to hold
  * Pi's reload or exit hostage. The allSettled promise is intentionally left
  * attached after timeout so a late rejection cannot become unhandled. */
@@ -160,6 +175,11 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       let mode: string;
       if (params.ticketAction) {
         mode = params.ticketAction;
+      } else if (params.sessionAction) {
+        // Session RPC is its own mode, not a task shape — label it before the
+        // tasks-based branches so close/list spans stop misreporting as
+        // "sync" with a zero task count.
+        mode = "session";
       } else if (tasks.length === 0) {
         mode = "manual";
       } else if (params.async) {
@@ -246,6 +266,35 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       // silently swap the agent roster.
       const agents = discoverAgents(ctx.cwd);
 
+      // ── Session RPC (top-level sessionAction, #32 promotion) ─────────
+      // Session control is no longer spelled as a task, but it still runs
+      // through the one runner: bridge it to an internal single-entry batch so
+      // busy-index validation, per-session locking (lifecycle's literal
+      // per-action branches), progress rows, and result formatting all keep
+      // their existing behavior. Never async — validation rejects that.
+      // Must precede the help short-circuit: session RPC carries no tasks and
+      // must not be mistaken for an empty help request.
+      if (params.sessionAction) {
+        invalidateHostDepsCache();
+        // Keep the footer-status pipeline in step exactly as a normal
+        // dispatch would (deduped no-op when nothing is running).
+        syncDelegateStatus(ctx);
+        return await dispatchDelegate({
+          pi,
+          params: { ...params, tasks: [bridgeSessionControlTask(params)] },
+          ctx,
+          agents,
+          parentModelId,
+          parentDefaults: {
+            thinking: pi.getThinkingLevel(),
+            tools: pi.getActiveTools(),
+          },
+          signal,
+          onUpdate,
+          callSpan,
+        });
+      }
+
       // ── Help mode ─────────────────────────────────────────────────
       if (!tasks.length) {
         succeedCall();

package/manual.ts

@@ -138,6 +138,8 @@ export function getSubagentManualMarkdown(
     "",
     ...builtinLines,
     "",
+    "Prefer `default` for general work: it is the only built-in guaranteed to run the parent's exact model and thinking. `scout`/`coder`/`reviewer` apply any configured delegate.json tiers (`agentOverrides`, `agentOverridesByParentModel`) and may run a different model or thinking level than the parent. `scout` is read-only, and `reviewer` runs in a disposable scratch workspace — its writes are discarded by design. Choose a specialist for its role, not its name.",
+    "",
     "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",
@@ -177,10 +179,10 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
     "",
     "// Clean up when done",
-    'delegate({ tasks: [{ sessionId: "auth-research", sessionAction: "close" }] })',
+    'delegate({ sessionAction: "close", sessionId: "auth-research" })',
     "```",
     "",
-    'Pooled sessions remain live until `sessionAction: "close"` or parent Pi session shutdown.',
+    'Pooled sessions remain live until a top-level `sessionAction: "close"` or parent Pi session shutdown.',
     "",
     "## Resuming Previous Sessions",
     "",
@@ -239,7 +241,7 @@ export function getSubagentManualMarkdown(
     '- 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.',
+    '- Prefer `agent: "default"` — the parent\'s live model/thinking/native tools/base prompt — for general tasks. Pick `scout`/`coder`/`reviewer` only when the role, tool limits, or scratch workspace fit; they follow delegate.json tiers and may not run the parent model. Omitting `agent` creates an ad-hoc task (parent model, full tools).',
     "- 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.",

package/package.json

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

package/render-branches.ts

@@ -470,7 +470,8 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
       );
     }
 
-    // Warnings (e.g. unknown tools ignored) — muted line under the task.
+    // Warnings (e.g. scratch-workspace notices, ignored model suffix) — muted
+    // line under the task.
     pushWarnings(p, ind);
 
     // Tool activities: compact summary only in expanded mode, terminal tasks only.

package/schema.ts

@@ -1,5 +1,8 @@
 import { Type, type SchemaOptions } from "@sinclair/typebox";
-import { VALID_THINKING_LEVELS } from "./constants.ts";
+import {
+  VALID_THINKING_LEVELS,
+  isSessionControlAction,
+} from "./constants.ts";
 import type { DelegateArguments } from "./types.ts";
 
 // JSON Schema string enum that keeps the literal union in `Static<>`.
@@ -30,19 +33,19 @@ export const delegateTaskSchema = Type.Object({
       minLength: 1,
       maxLength: 64,
       description:
-        "Optional task correlation key; 1-64 chars; A-Z a-z 0-9 . _ - only; duplicate ids rejected. Omit for index.",
+        "Optional correlation key; duplicates rejected; omit for index.",
     }),
   ),
   prompt: Type.Optional(
     Type.String({
       description:
-        "Self-contained task prompt; fresh context cannot see this chat. Omit only for close, list, or resumeFrom.",
+        "Self-contained task prompt; fresh context cannot see this chat. Omit only for resumeFrom.",
     }),
   ),
   agent: Type.Optional(
     Type.String({
       description:
-        "Agent profile name. Built-ins: default, scout, coder, reviewer. Omit for ad-hoc.",
+        "default mirrors the parent's tools; scout/coder/reviewer specialists. Ad-hoc tasks get * tools even when the parent is narrower.",
     }),
   ),
   cwd: Type.Optional(
@@ -86,13 +89,6 @@ export const delegateTaskSchema = Type.Object({
         "Live pool key for multi-turn reuse; omit for one-shot tasks.",
     }),
   ),
-  sessionAction: Type.Optional(
-    StringEnum(["prompt", "close", "list"], {
-      description:
-        "Session action; close needs sessionId; list shows active pooled sessions.",
-      default: "prompt",
-    }),
-  ),
   resumeFrom: Type.Optional(
     Type.String({
       description:
@@ -108,7 +104,7 @@ export const delegateTaskSchema = Type.Object({
   workspace: Type.Optional(
     StringEnum(["shared", "scratch", "isolated"], {
       description:
-        "shared; scratch discarded; isolated=sync one-shot Git apply; not security isolation. Reviewer=scratch.",
+        "shared edits source; scratch discards; isolated orders Git worktree proposals; none confine access.",
     }),
   ),
 });
@@ -124,6 +120,18 @@ export const delegateArgumentsSchema = Type.Object(
           "Ticket control: poll=snapshot; wait=block until settled; cancel=abort. Prefer wait; never cancel for time.",
       }),
     ),
+    sessionAction: Type.Optional(
+      StringEnum(["close", "list"], {
+        description:
+          '"close" ends the named pooled session; "list" lists active ones. Runs instead of tasks.',
+      }),
+    ),
+    sessionId: Type.Optional(
+      Type.String({
+        description:
+          'With "close": the pooled session to end. Alone, a sessionId folds into a task as reuse.',
+      }),
+    ),
     async: Type.Optional(
       Type.Boolean({
         description:
@@ -162,7 +170,10 @@ export const delegateArgumentsSchema = Type.Object(
 );
 
 /** 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. */
+ * level of the arguments; the normalizer folds them back into a single task.
+ * `sessionAction` is NOT here: it was promoted to a top-level field (#32), so
+ * top-level presence means session-RPC intent, not task intent — the classifier
+ * and its mode validators own it now. */
 const TASK_FIELD_NAMES = [
   "id",
   "prompt",
@@ -174,7 +185,6 @@ const TASK_FIELD_NAMES = [
   "tools",
   "thinking",
   "sessionId",
-  "sessionAction",
   "resumeFrom",
   "deadlineMs",
   "workspace",
@@ -187,7 +197,18 @@ const TASK_FIELD_NAMES = [
  * the work while the call in fact ran synchronously). */
 const VALID_TASK_KEYS = new Set<string>(TASK_FIELD_NAMES);
 
-/** Validate the three operation modes after compatibility reshaping. */
+/** Task fields that are known spellings of top-level fields — rejected inside
+ * task entries with a corrective hint pointing at their real home. */
+const TOP_LEVEL_TASK_KEY_HINTS = new Set(["async", "sessionAction"]);
+
+/** Validate the four operation modes after compatibility reshaping.
+ *
+ * One classifier with fixed precedence runs first: `ticketAction` → ticket
+ * RPC; `sessionAction` → session RPC; non-empty `tasks` → dispatch; otherwise
+ * help. Each mode gets a small total validator that rejects foreign fields
+ * generically (naming the offending field and the fix), so ordering is no
+ * longer load-bearing across checks and a new field costs one schema entry
+ * plus one mode check. */
 export function validateDelegateOperation(
   params: DelegateArguments,
 ): string | undefined {
@@ -195,37 +216,85 @@ export function validateDelegateOperation(
   if ("action" in rawParams) {
     return (
       "unsupported field 'action'; use 'ticketAction' for poll/cancel/wait " +
-      "or 'sessionAction' for prompt/close/list."
+      "or 'sessionAction' for close/list."
     );
   }
-  const tasks = params.tasks ?? [];
 
-  const ticketAction = params.ticketAction;
-  const isTicketControl = ticketAction !== undefined;
+  // Mode classification — precedence by selector presence.
+  if (params.ticketAction !== undefined) {
+    return validateTicketMode(params);
+  }
+  if (params.sessionAction !== undefined) {
+    return validateSessionMode(params);
+  }
+  return validateDispatchOrHelpMode(params);
+}
 
-  if (isTicketControl) {
-    const taskIntentFields = ([...TASK_FIELD_NAMES, "tasks"] as const).filter(
-      (field) => rawParams[field] !== undefined,
-    );
-    if (taskIntentFields.length) {
-      return `ticket control cannot be combined with task-intent field(s) ${taskIntentFields
-        .map((field) => `'${field}'`)
-        .join(", ")}; call it separately.`;
-    }
-    if (params.async === true) {
-      return "ticket control cannot include async; call it separately.";
-    }
-    if (ticketAction !== "poll" && !params.ticket) {
-      return `ticketAction '${ticketAction}' requires ticket.`;
-    }
-    if (ticketAction !== "cancel" && params.force === true) {
-      return "force is valid only with ticketAction 'cancel'.";
-    }
-    if (ticketAction !== "wait" && params.timeoutMs !== undefined) {
-      return "timeoutMs is valid only with ticketAction 'wait'.";
-    }
-    return undefined;
+/** Fields recognized at the top level in session mode: the selector itself
+ * plus its target. Anything else (ticket fields, async, tasks, stray task
+ * fields) is foreign to session RPC. */
+const SESSION_MODE_FIELDS = new Set(["sessionAction", "sessionId"]);
+
+/** Session RPC: one close/list action per call against one pooled session. */
+function validateSessionMode(params: DelegateArguments): string | undefined {
+  const rawParams = params as Record<string, unknown>;
+  const { sessionAction } = params;
+  // Nothing strips or defaults anymore; any value besides 'close'/'list'
+  // fails closed below rather than misclassifying.
+  if (!isSessionControlAction(sessionAction)) {
+    return `sessionAction '${String(sessionAction)}' is not a session control action; use 'close' or 'list'.`;
+  }
+  if (sessionAction === "close" && !params.sessionId) {
+    return "sessionAction 'close' requires sessionId.";
+  }
+  const foreign = Object.keys(rawParams).filter(
+    (key) => !SESSION_MODE_FIELDS.has(key),
+  );
+  if (foreign.length) {
+    return `sessionAction '${sessionAction}' cannot be combined with ${foreign
+      .map((field) => `'${field}'`)
+      .join(", ")}; run it alone — a session action takes only 'sessionAction' (plus 'sessionId' for 'close').`;
+  }
+  return undefined;
+}
+
+/** Ticket RPC: `ticketAction` owns the call; every other field family is
+ * foreign. Note `sessionAction` must be listed explicitly: it left
+ * `TASK_FIELD_NAMES` when it was promoted to top level, and without owning it
+ * here the old task-level exclusion would silently evaporate. */
+function validateTicketMode(params: DelegateArguments): string | undefined {
+  const rawParams = params as Record<string, unknown>;
+  const ticketAction = params.ticketAction;
+  const incompatibleFields = (
+    [...TASK_FIELD_NAMES, "tasks", "sessionAction"] as const
+  ).filter((field) => rawParams[field] !== undefined);
+  if (incompatibleFields.length) {
+    return `ticket control cannot be combined with field(s) ${incompatibleFields
+      .map((field) => `'${field}'`)
+      .join(", ")}; call it separately.`;
+  }
+  if (params.async === true) {
+    return "ticket control cannot include async; call it separately.";
+  }
+  if (ticketAction !== "poll" && !params.ticket) {
+    return `ticketAction '${ticketAction}' requires ticket.`;
+  }
+  if (ticketAction !== "cancel" && params.force === true) {
+    return "force is valid only with ticketAction 'cancel'.";
   }
+  if (ticketAction !== "wait" && params.timeoutMs !== undefined) {
+    return "timeoutMs is valid only with ticketAction 'wait'.";
+  }
+  return undefined;
+}
+
+/** Dispatch (non-empty `tasks`) or help (empty/absent). Stray ticket- and
+ * session-mode selectors are foreign here and rejected generically. */
+function validateDispatchOrHelpMode(
+  params: DelegateArguments,
+): string | undefined {
+  const rawParams = params as Record<string, unknown>;
+  const tasks = params.tasks ?? [];
 
   if (params.ticket !== undefined) {
     return "ticket requires ticketAction 'poll', 'cancel', or 'wait'.";
@@ -249,30 +318,29 @@ export function validateDelegateOperation(
   // nonempty tasks array. The normalize shim only wraps flat fields when
   // there is no tasks array, so a mixed call silently lets tasks win —
   // a model mistake that should fail loudly.
-  if (tasks.length > 0) {
-    const flatTaskFields = TASK_FIELD_NAMES.filter(
-      (field) => rawParams[field] !== undefined,
-    );
-    if (flatTaskFields.length) {
-      return `cannot mix top-level task field(s) ${flatTaskFields
-        .map((field) => `'${field}'`)
-        .join(
-          ", ",
-        )} with an explicit tasks array; move them into a task entry or remove tasks.`;
-    }
+  const flatTaskFields = TASK_FIELD_NAMES.filter(
+    (field) => rawParams[field] !== undefined,
+  );
+  if (flatTaskFields.length) {
+    return `cannot mix top-level task field(s) ${flatTaskFields
+      .map((field) => `'${field}'`)
+      .join(
+        ", ",
+      )} with an explicit tasks array; move them into a task entry or remove tasks.`;
   }
 
   for (const [index, task] of tasks.entries()) {
     const rawTask = task as Record<string, unknown>;
-    const sessionAction = task.sessionAction;
 
     const unknownKeys = Object.keys(rawTask).filter(
       (key) => !VALID_TASK_KEYS.has(key),
     );
     if (unknownKeys.length) {
-      const misplacedTopLevel = unknownKeys.filter((key) => key === "async");
+      const misplacedTopLevel = unknownKeys.filter((key) =>
+        TOP_LEVEL_TASK_KEY_HINTS.has(key),
+      );
       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.`
+        ? ` ${misplacedTopLevel.map((key) => `'${key}'`).join(" and ")} ${misplacedTopLevel.length === 1 ? "is a" : "are"} top-level field${misplacedTopLevel.length === 1 ? "" : "s"}; move ${misplacedTopLevel.length === 1 ? "it" : "them"} out of the task entry.`
         : "";
       return (
         `task ${index + 1}: unknown field(s) ${unknownKeys
@@ -291,28 +359,9 @@ export function validateDelegateOperation(
     }
     if (
       (task.workspace === "scratch" || task.workspace === "isolated") &&
-      (task.sessionId || task.resumeFrom || sessionAction !== undefined)
+      (task.sessionId || task.resumeFrom)
     ) {
-      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) {
-        return `task ${index + 1}: sessionAction 'close' requires sessionId.`;
-      }
-      const extras = Object.keys(rawTask).filter(
-        (key) => key !== "sessionAction" && key !== "sessionId" && key !== "id",
-      );
-      if (extras.length) {
-        return `task ${index + 1}: sessionAction 'close' accepts only sessionAction and sessionId.`;
-      }
-    }
-    if (sessionAction === "list") {
-      const extras = Object.keys(rawTask).filter(
-        (key) => key !== "sessionAction" && key !== "id",
-      );
-      if (extras.length) {
-        return `task ${index + 1}: sessionAction 'list' accepts only sessionAction.`;
-      }
+      return `task ${index + 1}: workspace '${task.workspace}' is one-shot and cannot be combined with sessionId or resumeFrom. Set workspace: "shared" to use a persistent agent.`;
     }
   }
 
@@ -350,13 +399,29 @@ function hasTicketControlIntent(record: Record<string, unknown>): boolean {
   );
 }
 
+/** True when `record` carries top-level session-RPC intent: an explicit
+ * close/list `sessionAction`. A bare top-level `sessionId` is deliberately
+ * NOT session intent — it stays task-intent and wraps into a task as reuse.
+ * Only `sessionAction` presence selects the session mode. */
+function hasSessionControlIntent(record: Record<string, unknown>): boolean {
+  return isSessionControlAction(record.sessionAction);
+}
+
 /** Fold top-level task fields into a single `tasks` entry. Only fires when
- * there is no usable tasks array and no ticket-control intent — those calls
- * are legitimately taskless. `sessionAction` is part of `TASK_FIELD_NAMES`,
- * so a top-level `sessionAction` rides along into the wrapped task. */
+ * there is no usable tasks array and neither ticket-control intent nor
+ * session-control intent makes those calls legitimately taskless.
+ * `sessionAction` is not part of `TASK_FIELD_NAMES`: a top-level close/list
+ * means session RPC and must reach the classifier unwrapped — wrapping first
+ * would swallow stray fields into a task instead of rejecting them. */
 function wrapFlatTaskFields(record: Record<string, unknown>): void {
   const hasTasks = Array.isArray(record.tasks) && record.tasks.length > 0;
-  if (hasTasks || hasTicketControlIntent(record)) return;
+  if (
+    hasTasks ||
+    hasTicketControlIntent(record) ||
+    hasSessionControlIntent(record)
+  ) {
+    return;
+  }
   const task: Record<string, unknown> = {};
   for (const key of TASK_FIELD_NAMES) {
     if (record[key] !== undefined) {
@@ -390,9 +455,11 @@ function normalizeTaskEntry(entry: unknown): unknown {
  * models then misread as "the tool is broken"):
  * - `tasks` as a JSON string instead of an array;
  * - task fields (`prompt`, `systemPrompt`, `tools`, ...) placed at the top
- *   level instead of inside a `tasks` entry — wrapped into a single task;
+ *   level instead of inside a `tasks` entry — wrapped into a single task,
+ *   unless ticket- or session-control intent makes the call legitimately
+ *   taskless (see `hasTicketControlIntent` / `hasSessionControlIntent`);
  * - `tools` as a JSON string (or bare token) inside a task entry;
- * - `agent: ""` inside a task entry — treated as omitted (ad-hoc).
+ * - `agent: ""` inside a task entry — treated as omitted (ad-hoc);
  * All other invalid input is left for normal schema validation to reject
  * loudly.
  *

package/task-resolution.ts

@@ -5,6 +5,7 @@ import {
   DEFAULT_AGENT_NAME,
   DEFAULT_TOOLS,
   VALID_THINKING,
+  isSessionControlAction,
 } from "./constants.ts";
 import {
   TOOL_FACTORIES,
@@ -36,7 +37,8 @@ import type {
   DelegateToolResult,
   ParentAgentDefaults,
   ResolvedTask,
-  TaskDef,
+  ResolveTasksResult,
+  DispatchableTask,
 } from "./types.ts";
 
 const PROJECT_CONTEXT_START =
@@ -92,7 +94,7 @@ export function stripInheritedProjectContext(
 /** Build a tool result for an error/notice with no task progress. */
 function noticeResult(
   text: string,
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   parentModel: string | undefined,
 ): DelegateToolResult {
   return {
@@ -110,7 +112,7 @@ function formatTaskRef(index: number, id: string | undefined): string {
  *  ticket, and unknown agent names. Returns an error result to short-circuit
  *  the call, or null when all checks pass. */
 export function validateTasks(
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   agents: Map<string, AgentConfig>,
   parentModelId: string | undefined,
 ): DelegateToolResult | null {
@@ -152,7 +154,7 @@ export function validateTasks(
           : `uses workspace \`${workspace}\``;
       const persistentAgent = task.agent ?? "agent";
       return noticeResult(
-        `${formatTaskRef(index, task.id)}: Agent \`${persistentAgent}\` ${defaultText}, which is one-shot and cannot use \`sessionId\`, \`resumeFrom\`, or session actions. Set \`workspace: "shared"\` to use a persistent ${persistentAgent}.`,
+        `${formatTaskRef(index, task.id)}: Agent \`${persistentAgent}\` ${defaultText}, which is one-shot and cannot use \`sessionId\` or \`resumeFrom\`. Set \`workspace: "shared"\` to use a persistent ${persistentAgent}.`,
         tasks,
         parentModelId,
       );
@@ -235,15 +237,17 @@ export function validateTasks(
 
 /** Resolve every task into a fully-specified `ResolvedTask`: cwd, system
  *  prompt, model, tools, thinking, and prompt (with optional parent-transcript
- *  injection). Throws on unrecoverable misconfiguration (missing prompt,
- *  unavailable explicit model, no model at all). */
+ *  injection). Returns `{ error }` — rejecting the whole batch before any
+ *  dispatch — when any task names a tool outside the closed valid set for its
+ *  resolved model's provider. Throws on unrecoverable misconfiguration
+ *  (missing prompt, unavailable explicit model, no model at all). */
 export function resolveTasks(
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   ctx: DelegateToolCtx,
   agents: Map<string, AgentConfig>,
   parentDefaults: ParentAgentDefaults,
   dispatchConfig: DelegateConfig = getDelegateConfigSnapshot(),
-): ResolvedTask[] {
+): ResolveTasksResult {
   // Build parent transcript lazily — only computed once if any task uses with-parent-transcript
   let parentTranscript: string | null = null;
   const needsParentContext = tasks.some(
@@ -269,7 +273,10 @@ export function resolveTasks(
   const agentOverrides = getAgentOverrides(dispatchConfig);
   const overridesByParentModel = getAgentOverridesByParentModel(dispatchConfig);
 
-  return tasks.map((t, i) => {
+  const resolveTask = (
+    t: DispatchableTask,
+    i: number,
+  ): ResolvedTask | { error: string } => {
     const isDefaultAgent = t.agent === DEFAULT_AGENT_NAME;
     const agent = t.agent
       ? (agents.get(t.agent) ?? BUILTIN_AGENT_CONFIGS[t.agent])
@@ -318,8 +325,7 @@ export function resolveTasks(
 
     // Prompt is required for fresh tasks. ResumeFrom provides context already.
     if (
-      t.sessionAction !== "close" &&
-      t.sessionAction !== "list" &&
+      !isSessionControlAction(t.sessionAction) &&
       !t.resumeFrom &&
       !t.prompt?.trim()
     ) {
@@ -328,11 +334,12 @@ export function resolveTasks(
       );
     }
 
-    // Resolve tools — warn about unknown tool names.
+    // Resolve tools — unknown names reject the whole batch (checked below,
+    // post-model-resolution, because the provider decides the valid set).
     // For active pooled sessions, fall back to the frozen pooled config so
     // "continue with only sessionId" works without re-supplying tools.
     // Explicit overrides that don't match get rejected by acquireAgentSession.
-    if (t.sessionAction !== "close" && t.sessionAction !== "list") {
+    if (!isSessionControlAction(t.sessionAction)) {
       // For `default` a deny-only override (no explicit allowlist) is not
       // materialized at discovery; apply its denylist to the parent's actual
       // tools here so a read-only parent stays read-only.
@@ -428,7 +435,7 @@ export function resolveTasks(
     let modelSuffix: ThinkingLevel | undefined;
     let thinking: ThinkingLevel = "off";
 
-    if (t.sessionAction !== "close" && t.sessionAction !== "list") {
+    if (!isSessionControlAction(t.sessionAction)) {
       const agentType = t.agent ?? "inline";
       // The built-in `default` profile bypasses delegate.json model overrides.
       // The other built-ins accept task and modern agent overrides, but
@@ -568,15 +575,20 @@ export function resolveTasks(
       dispatchConfig,
     );
 
+    // The valid tool set is closed: core TOOL_FACTORIES plus the static
+    // per-provider list. Unknown names hard-reject the whole batch (mirroring
+    // unknown agent names) instead of warn-dropping a silently weakened
+    // subagent. Frozen pooled configs are known-good: they were filtered
+    // against this same static set when first resolved, so bare
+    // "continue with only sessionId" resumes never trip this check.
     const availableTools = availableToolNames(model?.provider);
     const availableToolSet = new Set(availableTools);
     const unknownTools = tools.filter((name) => !availableToolSet.has(name));
     if (unknownTools.length) {
-      warnings.push(
-        `Unknown tool(s) ignored: ${unknownTools.join(", ")}. Available: ${availableTools.join(", ")}`,
-      );
+      return {
+        error: `${formatTaskRef(i, t.id)}: unknown tool(s): ${unknownTools.join(", ")}. Available: ${availableTools.join(", ")}. Fix the tool names in the task's tools list or the agent profile's tools.`,
+      };
     }
-    tools = tools.filter((name) => availableToolSet.has(name));
     systemPrompt = buildSubagentSystemPrompt({
       taskSystemPrompt: t.systemPrompt,
       agentSystemPrompt: agent?.systemPrompt,
@@ -627,5 +639,13 @@ export function resolveTasks(
       },
       providerExtensionSources,
     };
-  });
+  };
+
+  const resolved: ResolvedTask[] = [];
+  for (const [i, task] of tasks.entries()) {
+    const result = resolveTask(task, i);
+    if ("error" in result) return { error: result.error };
+    resolved.push(result);
+  }
+  return { tasks: resolved };
 }

package/ticket-format.ts

@@ -274,9 +274,13 @@ export function formatCancelPreview(ticket: AsyncTicket): string {
 
   for (const p of ticket.progress) {
     if (p.status === "done") {
-      lines.push(`✓ ${p.agent}${resumeMarker(p)}${formatTaskId(p.id)} · completed`);
+      lines.push(
+        `✓ ${p.agent}${resumeMarker(p)}${formatTaskId(p.id)} · completed`,
+      );
     } else if (p.status === "failed") {
-      lines.push(`✗ ${p.agent}${resumeMarker(p)}${formatTaskId(p.id)} · ${p.error ?? "failed"}`);
+      lines.push(
+        `✗ ${p.agent}${resumeMarker(p)}${formatTaskId(p.id)} · ${p.error ?? "failed"}`,
+      );
     } else if (p.status === "running") {
       lines.push(formatInFlightTaskLine(p));
     } else {

package/types.ts

@@ -53,13 +53,22 @@ type CanonicalTaskDef = NonNullable<
 export type TicketAction = NonNullable<
   CanonicalDelegateArguments["ticketAction"]
 >;
-/** Per-task session action: "prompt" | "close" | "list". */
-export type SessionAction = NonNullable<CanonicalTaskDef["sessionAction"]>;
+/** Top-level session RPC action: "close" | "list" (#32 promotion). */
+export type SessionAction = NonNullable<
+  CanonicalDelegateArguments["sessionAction"]
+>;
 /** Filesystem mode: shared source tree or an ephemeral CoW scratch copy. */
 export type WorkspaceMode = NonNullable<CanonicalTaskDef["workspace"]>;
 
 export type TaskDef = CanonicalTaskDef;
 
+/** Pipeline-wide task type: caller-provided TaskDefs plus the internal
+ * session-RPC bridge task built by extension.ts from the promoted top-level
+ * `sessionAction`/`sessionId` fields. `sessionAction` left the public task
+ * schema in #32 (it became top-level); the runner still executes the bridged
+ * operation through ResolvedTask, so the dispatch pipeline accepts both. */
+export type DispatchableTask = TaskDef & { sessionAction?: SessionAction };
+
 export type DelegateArguments = CanonicalDelegateArguments;
 
 // ── Async Ticket Types ─────────────────────────────────────────────────────
@@ -169,6 +178,14 @@ export interface ResolvedTask {
   providerExtensionSources?: string;
 }
 
+/** Result of `resolveTasks`: either every task resolved, or a batch-wide
+ *  rejection (e.g. an unknown tool name) with no tasks to dispatch. The
+ *  optional-`error` discriminant keeps `.tasks` accessible on the whole union
+ *  so success-path callers can narrow with a single `error !== undefined` check. */
+export type ResolveTasksResult =
+  | { tasks: ResolvedTask[]; error?: undefined }
+  | { tasks?: undefined; error: string };
+
 export interface FileAttributionPathSignature {
   /** Absolute component inspected while resolving the pre-execution target. */
   path: string;
@@ -251,8 +268,9 @@ export interface TaskProgress {
   model?: string;
   lastActivityAt?: number;
   activities: ToolActivity[];
-  /** Human-facing notices (e.g. unknown tools ignored). Surfaced in the TUI
-   *  under the task; the LLM gets the same text in `content` already. */
+  /** Human-facing notices (e.g. scratch/isolated workspace notices, an
+   *  ignored model `:level` suffix). Surfaced in the TUI under the task; the
+   *  LLM gets the same text in `content` already. */
   warnings?: string[];
 }
 

package/workspace.ts

@@ -142,9 +142,61 @@ function throwIfSetupCancelled(
   );
 }
 
+/** Project an absolute source-tree symlink target onto its counterpart inside
+ * the copy, as a relative target so the copy stays self-contained. Returns
+ * undefined when the target is not lexically inside the source root, which is
+ * the only case that can be rewritten without following it. */
+function relinkTargetIntoCopy(
+  linkPath: string,
+  target: string,
+  root: string,
+  sourceRoot: string,
+): string | undefined {
+  if (!path.isAbsolute(target) || !isWithin(sourceRoot, target)) {
+    return undefined;
+  }
+  const projected = path.join(root, path.relative(sourceRoot, target));
+  if (!isWithin(root, projected)) return undefined;
+  const relative = path.relative(path.dirname(linkPath), projected);
+  return relative === "" ? "." : relative;
+}
+
+/** Restore owner traversal/write bits so a partial copy can be removed.
+ * `cp --archive` reproduces read-only source directories, and their copies
+ * would otherwise leak a lease directory behind a failed setup. */
+async function makeTreeRemovable(root: string): Promise<void> {
+  let entries: fs.Dirent[];
+  try {
+    await fs.promises.chmod(root, 0o700);
+    entries = await fs.promises.readdir(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      await makeTreeRemovable(path.join(root, entry.name));
+    }
+  }
+}
+
+async function replaceSymlink(linkPath: string, target: string): Promise<void> {
+  const staging = path.join(
+    path.dirname(linkPath),
+    `.pi-delegate-relink-${process.pid.toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  await fs.promises.symlink(target, staging);
+  try {
+    await fs.promises.rename(staging, linkPath);
+  } catch (error) {
+    await fs.promises.rm(staging, { force: true });
+    throw error;
+  }
+}
+
 /** Validate the completed copy before any subagent receives its path. */
 async function validateCopiedTree(
   root: string,
+  sourceRoot: string,
   signal: AbortSignal,
   parentSignal: AbortSignal | undefined,
 ): Promise<void> {
@@ -179,10 +231,31 @@ async function validateCopiedTree(
       }
       if (!entry.isSymbolicLink()) continue;
       const target = await fs.promises.readlink(candidate);
+      // `cp --archive` copies link text verbatim, so an absolute in-project
+      // link (bun/pnpm-style local package installs) still resolves to the
+      // real tree from inside the copy. Retarget it at its copied counterpart
+      // instead of failing: the link keeps working and stays disposable.
+      const relinked = relinkTargetIntoCopy(
+        candidate,
+        target,
+        root,
+        sourceRoot,
+      );
+      if (relinked !== undefined) {
+        try {
+          await replaceSymlink(candidate, relinked);
+        } catch (error) {
+          throw new ScratchSetupError(
+            `Scratch workspace could not retarget in-project symlink '${path.relative(root, candidate)}' at its copied counterpart.`,
+            { cause: error },
+          );
+        }
+        continue;
+      }
       const resolvedTarget = path.resolve(path.dirname(candidate), target);
       if (path.isAbsolute(target) || !isWithin(root, resolvedTarget)) {
         throw new ScratchSetupError(
-          `Scratch workspace cannot safely copy symlink '${path.relative(root, candidate)}' because it points outside the project.`,
+          `Scratch workspace cannot safely copy symlink '${path.relative(root, candidate)}' -> '${target}': it resolves outside the disposable copy, so relative writes through it would reach the host. Remove the link, or run this task with workspace "shared" (read-only tools) or "isolated".`,
         );
       }
     }
@@ -704,7 +777,12 @@ export async function createScratchWorkspace(
     // GNU cp --archive applies the source root's mode to the destination.
     // Restore the private boundary after it has finished copying metadata.
     await fs.promises.chmod(scratchRoot, 0o700);
-    await validateCopiedTree(scratchRoot, controller.signal, signal);
+    await validateCopiedTree(
+      scratchRoot,
+      sourceRoot,
+      controller.signal,
+      signal,
+    );
     if (
       await fs.promises.stat(path.join(scratchRoot, ".git")).then(
         (stat) => stat.isDirectory(),
@@ -766,7 +844,7 @@ export async function createScratchWorkspace(
   } catch (error) {
     if (leaseRoot) {
       try {
-        await fs.promises.chmod(leaseRoot, 0o700);
+        await makeTreeRemovable(leaseRoot);
         await fs.promises.rm(leaseRoot, { recursive: true, force: true });
       } catch (cleanupError) {
         console.error(
@@ -913,13 +991,18 @@ export async function createScratchWorkspace(
         readStableLink(source, sourceStat),
       ]);
       // A readlink or identity race is not evidence that the nodes matched.
-      // Keep the lexical source path rather than dropping it.
-      if (
-        scratchTarget !== undefined &&
-        sourceTarget !== undefined &&
-        scratchTarget === sourceTarget
-      ) {
-        return undefined;
+      // Keep the lexical source path rather than dropping it. An in-project
+      // absolute source link was deliberately retargeted at setup, so its
+      // copied form matches that projection rather than the source text.
+      if (scratchTarget !== undefined && sourceTarget !== undefined) {
+        const expected =
+          relinkTargetIntoCopy(
+            lexical,
+            sourceTarget,
+            completedRoot,
+            sourceRoot!,
+          ) ?? sourceTarget;
+        if (scratchTarget === expected) return undefined;
       }
     }
     // This is evidence about the lexical node, not its current target.