@bermudi/pi-delegate 0.1.15 → 0.1.17

package/schema.ts

@@ -1,5 +1,5 @@
 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 +30,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 +86,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 +101,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 +117,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 +167,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 +182,6 @@ const TASK_FIELD_NAMES = [
   "tools",
   "thinking",
   "sessionId",
-  "sessionAction",
   "resumeFrom",
   "deadlineMs",
   "workspace",
@@ -187,7 +194,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 +213,105 @@ 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.`;
+/** 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.";
+  }
+  // Skip only fields carrying their documented default/no-op value: a caller
+  // (or a schema validator that materialises defaults) may spell out
+  // `async: false`, `force: false`, or `tasks: []` explicitly. Other false or
+  // empty-array values remain foreign so future fields cannot bypass this mode
+  // boundary merely by sharing the same value shape.
+  const foreign = Object.keys(rawParams).filter((key) => {
+    if (SESSION_MODE_FIELDS.has(key) || rawParams[key] === undefined) {
+      return false;
     }
-    if (ticketAction !== "cancel" && params.force === true) {
-      return "force is valid only with ticketAction 'cancel'.";
+    if ((key === "async" || key === "force") && rawParams[key] === false) {
+      return false;
     }
-    if (ticketAction !== "wait" && params.timeoutMs !== undefined) {
-      return "timeoutMs is valid only with ticketAction 'wait'.";
+    if (
+      key === "tasks" &&
+      Array.isArray(rawParams[key]) &&
+      rawParams[key].length === 0
+    ) {
+      return false;
     }
-    return undefined;
+    return true;
+  });
+  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 +335,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 +376,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 +416,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 +472,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 };
 }