@bermudi/pi-delegate 0.1.6 → 0.1.8

package/README.md

@@ -38,6 +38,19 @@ Parent extension/MCP tools are not copied, and project instructions are rebuilt
 for the task's `cwd`. Omit `agent` when you want an ad-hoc task using delegate's
 normal inline defaults instead.
 
+The other built-ins are:
+
+- `scout` — read-only investigation with `read`, `grep`, `find`, and `ls`.
+- `coder` — implementation and verification with `read`, `write`, `edit`, and
+  `bash` in the shared workspace.
+- `reviewer` — review with `read` and `bash`, using a disposable scratch copy by
+  default. Set `workspace: "shared"` when a reviewer needs a persistent
+  `sessionId`.
+
+Fresh built-ins inherit the parent's exact model object and thinking level.
+Task-level overrides win; settings can provide unconditional overrides or exact
+parent-model overrides under `delegate.agentOverridesByParentModel`.
+
 ### Disposable scratch workspace
 
 For review, tests, or other commands whose project changes should be thrown
@@ -136,7 +149,7 @@ over an installed extension.
   rare override. Markdown agents are examples of custom agents.
 - **Named agent** / **Markdown agent** — A reusable custom agent persisted as a
   Markdown file in `.pi/agents/*.md` or `~/.pi/agent/agents/*.md`. The frontmatter
-  defines its name, description, model, tools, thinking level, and skills; the
+  defines its name, description, model, tools, and thinking level; the
   Markdown body is its system prompt.
 - **Ad-hoc subagent** — A subagent created from inline task fields instead of a
   named Markdown agent profile. In current output this is labeled `ad-hoc`.

package/agents.ts

@@ -7,8 +7,13 @@ import type {
 } from "@earendil-works/pi-agent-core";
 import { parseFrontmatter as parsePiFrontmatter } from "@earendil-works/pi-coding-agent";
 import {
+  BUILTIN_AGENT_NAMES,
+  CODER_AGENT_NAME,
   DEFAULT_AGENT_NAME,
   DEFAULT_TOOLS,
+  READONLY_TOOLS,
+  REVIEWER_AGENT_NAME,
+  SCOUT_AGENT_NAME,
   VALID_THINKING,
 } from "./constants.ts";
 import { resolveToolGroups } from "./tools.ts";
@@ -110,6 +115,50 @@ export function parseFrontmatter(
 
 // ── Agent Discovery ───────────────────────────────────────────────────────
 
+/** Built-in profiles are always available and cannot vary with Markdown files. */
+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.",
+    tools: DEFAULT_TOOLS,
+    systemPrompt: "",
+    builtin: true,
+    workspace: "shared",
+  },
+  [SCOUT_AGENT_NAME]: {
+    name: SCOUT_AGENT_NAME,
+    description: "Investigate without modifying the source project.",
+    tools: READONLY_TOOLS,
+    systemPrompt:
+      "Explore the codebase to answer the assigned question. Do not modify files. Trace relevant code, tests, documentation, and history when useful. Return concise findings with concrete paths, symbols, and any uncertainty. Prefer evidence over speculation.",
+    builtin: true,
+    workspace: "shared",
+  },
+  [CODER_AGENT_NAME]: {
+    name: CODER_AGENT_NAME,
+    description: "Implement and verify changes in the shared source tree.",
+    tools: DEFAULT_TOOLS,
+    systemPrompt:
+      "Implement the assigned change. Read the existing code and project instructions first. Prefer the smallest maintainable solution that follows existing conventions. Surface failures clearly. Run focused tests or checks and report what changed, what passed, and any remaining risk.",
+    builtin: true,
+    workspace: "shared",
+  },
+  [REVIEWER_AGENT_NAME]: {
+    name: REVIEWER_AGENT_NAME,
+    description: "Inspect the current snapshot and report actionable findings.",
+    tools: ["read", "bash"],
+    systemPrompt:
+      "Review the current snapshot for correctness, regressions, security problems, and missing tests. Do not modify the source project. Run focused checks when useful. Report actionable findings ordered by severity, with concrete paths and locations. If there are no material findings, say so plainly; do not invent issues or merely summarize the implementation.",
+    builtin: true,
+    workspace: "scratch",
+  },
+};
+
+export function isBuiltinAgentName(name: string): boolean {
+  return (BUILTIN_AGENT_NAMES as readonly string[]).includes(name);
+}
+
 /** Find the nearest ancestor containing project-scoped agent files. */
 export function findProjectRoot(cwd: string): string | null {
   let dir = cwd;
@@ -330,7 +379,9 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
     scope: "claude",
   });
 
-  const agents = new Map<string, AgentConfig>();
+  const agents = new Map<string, AgentConfig>(
+    Object.entries(BUILTIN_AGENT_CONFIGS),
+  );
   const loadDir = (
     { dir, scope }: { dir: string; scope: AgentConfig["scope"] },
     loader: (fp: string) => AgentConfig | null,
@@ -345,9 +396,9 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
       if (!e.name.endsWith(".md") || e.name.endsWith(".chain.md")) continue;
       const filePath = path.join(dir, e.name);
       const cfg = loader(filePath);
-      if (cfg?.name === DEFAULT_AGENT_NAME) {
+      if (cfg && isBuiltinAgentName(cfg.name)) {
         console.warn(
-          `[delegate] ignoring agent profile '${DEFAULT_AGENT_NAME}' from ${filePath}: the name is reserved for the built-in parent-mirroring profile.`,
+          `[delegate] ignoring agent profile '${cfg.name}' from ${filePath}: the name is reserved for a built-in delegate profile.`,
         );
         continue;
       }

package/constants.ts

@@ -1,6 +1,23 @@
 /** Reserved built-in profile that mirrors the live parent configuration. */
 export const DEFAULT_AGENT_NAME = "default";
 
+/** Reserved built-in profile for read-only investigation. */
+export const SCOUT_AGENT_NAME = "scout";
+
+/** Reserved built-in profile for shared-workspace implementation work. */
+export const CODER_AGENT_NAME = "coder";
+
+/** Reserved built-in profile for isolated review work. */
+export const REVIEWER_AGENT_NAME = "reviewer";
+
+/** All names reserved by delegate's built-in profiles. */
+export const BUILTIN_AGENT_NAMES = [
+  DEFAULT_AGENT_NAME,
+  SCOUT_AGENT_NAME,
+  CODER_AGENT_NAME,
+  REVIEWER_AGENT_NAME,
+] as const;
+
 /** Full-capability agent set. Inline-task default and the `*` shorthand.
  *  Bash subsumes search, so the dedicated grep/find/ls tools are excluded. */
 export const DEFAULT_TOOLS = ["read", "write", "edit", "bash"];

package/delegate.ts

@@ -24,6 +24,10 @@ export type { DelegateConfig } from "./config.ts";
 
 export {
   DEFAULT_AGENT_NAME,
+  SCOUT_AGENT_NAME,
+  CODER_AGENT_NAME,
+  REVIEWER_AGENT_NAME,
+  BUILTIN_AGENT_NAMES,
   DEFAULT_TOOLS,
   READONLY_TOOLS,
   MAX_CONCURRENCY,
@@ -123,6 +127,8 @@ export {
   loadAgentFile,
   loadClaudeAgentFile,
   discoverAgents,
+  BUILTIN_AGENT_CONFIGS,
+  isBuiltinAgentName,
   buildSubagentSystemPrompt,
   DEFAULT_SUBAGENT_SYSTEM_PROMPT,
 } from "./agents.ts";
@@ -133,7 +139,12 @@ export {
   resolveModelRequest,
   findAvailableAlternative,
 } from "./model.ts";
-export { readDelegateSettingsFile, loadDelegateSettings } from "./settings.ts";
+export {
+  readDelegateSettingsFile,
+  loadDelegateSettings,
+  clearDelegateSettingsCache,
+} from "./settings.ts";
+export type { AgentOverride } from "./settings.ts";
 export { resolveCwd, extractOutput, extractUsage } from "./utils.ts";
 export {
   decideSpill,

package/dispatch.ts

@@ -24,6 +24,7 @@ import {
 import { validateDelegateOperation } from "./schema.ts";
 import { notifyCrossLeafDelivery, syncDelegateStatus } from "./status.ts";
 import { validateTasks, resolveTasks } from "./task-resolution.ts";
+import { clearDelegateSettingsCache } from "./settings.ts";
 import type { CallSpan } from "./telemetry.ts";
 import type {
   AgentConfig,
@@ -146,6 +147,9 @@ export interface DelegateDispatchInput {
 export async function dispatchDelegate(
   input: DelegateDispatchInput,
 ): Promise<DelegateToolResult> {
+  // Settings are user-editable. Clear once at the dispatch boundary so every
+  // task in this batch observes one consistent settings snapshot.
+  clearDelegateSettingsCache();
   const {
     pi,
     params,
@@ -293,7 +297,6 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
   const asyncEnv: TaskRunEnv = {
     signal: ticketSignal,
     modelRegistry,
-    parentSessionManager: ctx.sessionManager,
     ticketId,
     delegateStartedAt: ticket.created,
     telemetryCallId: callSpan?.id,
@@ -426,7 +429,6 @@ export async function dispatchSync(
   const syncEnv: TaskRunEnv = {
     signal,
     modelRegistry: ctx.modelRegistry,
-    parentSessionManager: ctx.sessionManager,
     ticketId: undefined,
     delegateStartedAt: startedAt,
     telemetryCallId: callSpan?.id,

package/lifecycle.ts

@@ -18,7 +18,6 @@ import { isSessionBusy } from "./tickets.ts";
 import {
   createSubagentSessionManager,
   persistSessionHeader,
-  setParentSession,
 } from "./sessions.ts";
 import { runAgentSession, formatDeadlineExceededError } from "./runner.ts";
 import { getGitChangedFiles } from "./file-tracking.ts";
@@ -329,8 +328,8 @@ async function sleepForWholeTaskRetry(
 }
 
 /** Build the AgentSession for a fresh or resumed subagent via createAgentSession.
- *  Reuses the caller-supplied sessionManager (so parent-linking + per-task .jsonl
- *  files stay under our control). Extension-free host deps may be cached, while
+ *  Reuses the caller-supplied sessionManager (so per-task .jsonl files stay under
+ *  our control). Extension-free host deps may be cached, while
  *  provider-configured or allowlisted-extension deps are session-local because
  *  Pi binds mutable extension callbacks onto each loader runtime. */
 async function buildDelegateSession(
@@ -484,10 +483,6 @@ async function acquireAgentSession(
       };
     }
 
-    // Link resumed session to parent for /resume discoverability.
-    const parentFile = env.parentSessionManager?.getSessionFile?.();
-    if (parentFile) setParentSession(resumed, parentFile);
-
     const session = await buildDelegateSession(
       task,
       resumed,
@@ -508,10 +503,7 @@ async function acquireAgentSession(
     // isolation. Keep scratch transcripts in memory only.
     sessionManager = SessionManager.inMemory(task.cwd);
   } else {
-    const fresh = createSubagentSessionManager(
-      env.parentSessionManager,
-      task.cwd,
-    );
+    const fresh = createSubagentSessionManager(task.cwd);
     if (!fresh) {
       return {
         error: failTask(task, "Internal: could not create session file"),

package/manual.ts

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

package/migrate-delegate-sessions.ts

@@ -0,0 +1,202 @@
+/**
+ * Move old pi-delegate sessions out of Pi's normal session index.
+ *
+ * This is intentionally a standalone migration, not extension startup code:
+ * `pi -r` indexes sessions before extensions are loaded.
+ *
+ * Usage:
+ *   bun run migrate-delegate-sessions.ts          # report only
+ *   bun run migrate-delegate-sessions.ts --apply  # unlink and move
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+type JsonObject = Record<string, unknown>;
+
+const agentDir = getAgentDir();
+const sourceDir = path.join(agentDir, "sessions");
+const destinationDir = path.join(agentDir, "delegate-sessions");
+const apply = process.argv.includes("--apply");
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) &&
+      relative !== ".." &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function readSession(file: string): JsonObject[] | undefined {
+  try {
+    const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+    const entries: JsonObject[] = [];
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const parsed: unknown = JSON.parse(line);
+      if (!isObject(parsed)) return undefined;
+      entries.push(parsed);
+    }
+    return entries;
+  } catch {
+    return undefined;
+  }
+}
+
+function readSessionHeader(file: string): JsonObject | undefined {
+  try {
+    const firstLine = fs.readFileSync(file, "utf8").split(/\r?\n/, 1)[0];
+    const parsed: unknown = JSON.parse(firstLine);
+    return isObject(parsed) && parsed.type === "session" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function sessionHeader(entries: JsonObject[]): JsonObject | undefined {
+  const header = entries[0];
+  return header?.type === "session" ? header : undefined;
+}
+
+function entryKey(entry: JsonObject): string {
+  return JSON.stringify(entry);
+}
+
+/**
+ * Pi's forkFrom() copies every non-header entry from the source session before
+ * writing anything new. Old delegate sessions do not copy the parent history.
+ * This is the discriminator: parentSession by itself is deliberately not
+ * sufficient because genuine Pi forks also have it.
+ */
+function isPiFork(
+  childEntries: JsonObject[],
+  parentEntries: JsonObject[],
+): boolean {
+  const childBody = childEntries.slice(1);
+  const parentBody = parentEntries.slice(1);
+  if (parentBody.length === 0 || childBody.length < parentBody.length) {
+    return false;
+  }
+  return parentBody.every(
+    (entry, index) => entryKey(entry) === entryKey(childBody[index]),
+  );
+}
+
+function findJsonlFiles(directory: string): string[] {
+  if (!fs.existsSync(directory)) return [];
+  const files: string[] = [];
+  const visit = (current: string): void => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const candidate = path.join(current, entry.name);
+      if (entry.isDirectory()) visit(candidate);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl"))
+        files.push(candidate);
+    }
+  };
+  visit(directory);
+  return files;
+}
+
+interface MigrationCandidate {
+  source: string;
+  destination: string;
+}
+
+const candidates: MigrationCandidate[] = [];
+let skipped = 0;
+const parentCache = new Map<string, JsonObject[] | undefined>();
+
+for (const file of findJsonlFiles(sourceDir)) {
+  const header = readSessionHeader(file);
+  const parent = header?.parentSession;
+  if (!header || typeof parent !== "string") continue;
+
+  const parentPath = path.resolve(parent);
+  if (!isWithin(sourceDir, parentPath) || !fs.existsSync(parentPath)) {
+    skipped++;
+    console.warn(`skip (parent unavailable): ${file}`);
+    continue;
+  }
+
+  let parentEntries = parentCache.get(parentPath);
+  if (parentEntries === undefined && !parentCache.has(parentPath)) {
+    parentEntries = readSession(parentPath);
+    parentCache.set(parentPath, parentEntries);
+  }
+  const entries = readSession(file);
+  if (!entries) {
+    skipped++;
+    console.warn(`skip (invalid session): ${file}`);
+    continue;
+  }
+  if (!parentEntries || isPiFork(entries, parentEntries)) continue;
+
+  const relative = path.relative(sourceDir, file);
+  candidates.push({
+    source: file,
+    destination: path.join(destinationDir, relative),
+  });
+}
+
+console.log(
+  `${apply ? "Migrating" : "Found"} ${candidates.length} delegate session(s); ` +
+    `${skipped} skipped because their parent could not be verified.`,
+);
+
+if (!apply) {
+  for (const candidate of candidates) {
+    console.log(`would move: ${candidate.source} -> ${candidate.destination}`);
+  }
+  console.log("Nothing changed. Re-run with --apply to perform the migration.");
+  process.exit(0);
+}
+
+let moved = 0;
+for (const candidate of candidates) {
+  const entries = readSession(candidate.source);
+  const header = entries && sessionHeader(entries);
+  if (!entries || !header) {
+    console.warn(`skip (changed during migration): ${candidate.source}`);
+    continue;
+  }
+
+  delete header.parentSession;
+  const parent = path.dirname(candidate.destination);
+  fs.mkdirSync(parent, { recursive: true });
+
+  const temporary = `${candidate.source}.delegate-migration-${process.pid}.tmp`;
+  try {
+    if (fs.existsSync(candidate.destination)) {
+      throw new Error("destination already exists");
+    }
+    fs.writeFileSync(
+      temporary,
+      `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`,
+      { flag: "wx", mode: 0o600 },
+    );
+    fs.renameSync(temporary, candidate.source);
+    fs.renameSync(candidate.source, candidate.destination);
+    console.log(`moved: ${candidate.source} -> ${candidate.destination}`);
+    moved++;
+  } catch (error) {
+    try {
+      if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    } catch {
+      // Preserve the original error below; the temp file is harmless and
+      // uniquely named for this process.
+    }
+    console.error(
+      `failed: ${candidate.source}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+console.log(`Moved ${moved}/${candidates.length} delegate session(s).`);

package/package.json

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

package/schema.ts

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

package/sessions.ts

@@ -1,67 +1,26 @@
 import * as fs from "node:fs";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { SessionManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 
-/** Link a subagent session to its parent and persist the header when possible. */
-export function setParentSession(sm: SessionManager, parentPath: string): void {
-  const inner = sm as unknown as {
-    fileEntries: Array<{ type: string; parentSession?: string }>;
-    getSessionFile?: () => string | undefined;
-    _rewriteFile?: () => void;
-  };
-  const header = inner.fileEntries[0];
-  if (header && header.type === "session") {
-    header.parentSession = parentPath;
-    // For a *resumed* session the file already exists on disk and the manager
-    // is flushed (SessionManager.open/setSessionFile sets flushed=true). The
-    // in-memory header mutation above is otherwise lost: upstream _persist()
-    // only *appends* new entries once flushed — it never rewrites the header.
-    // So a resumeFrom session would never surface as a child in /resume despite
-    // the link being set in memory. Rewrite the whole file (header + entries)
-    // so the parentSession field is actually persisted. Fresh sessions skip
-    // this (file doesn't exist yet); their first _persist() writes the mutated
-    // header along with the rest, and rewriting early would trip the
-    // duplicate-header bug in _persist()'s not-yet-flushed path.
-    const file = inner.getSessionFile?.();
-    if (file && fs.existsSync(file)) {
-      try {
-        inner._rewriteFile?.();
-      } catch {
-        /* best effort — link stays in-memory; not fatal */
-      }
-    }
-  }
+/** Persistent storage for delegate-only conversations. */
+export function getDelegateSessionDir(): string {
+  return join(getAgentDir(), "delegate-sessions");
 }
 
 /**
  * Create a session manager for a subagent run.
  *
- * Always creates a standalone session file in the target cwd.
- * Sets `parentSession` in the header so subagent work is discoverable
- * as a child of the parent session in `/resume`.
- *
- * Returns the concrete `SessionManager` (ready to hand to `createAgentSession`)
- * and its file path (for result reporting + pool bookkeeping).
+ * Delegate sessions are deliberately standalone and live in their own
+ * directory. They are not attached to the parent's session tree.
  */
 export function createSubagentSessionManager(
-  parentSessionManager: unknown,
   cwd: string,
 ): { manager: SessionManager; file: string } | undefined {
-  // Resolve parent session file path for linking.
-  const parentFile = (
-    parentSessionManager as
-      { getSessionFile?(): string | undefined } | undefined
-  )?.getSessionFile?.();
-
-  // Always persist subagent work so the main agent can search it later.
-  const sm = SessionManager.create(cwd);
+  // Always persist subagent work separately from the parent's session tree.
+  const sm = SessionManager.create(cwd, getDelegateSessionDir());
   const sessionFile = sm.getSessionFile();
   if (!sessionFile) return undefined;
 
-  // Link to parent session so subagent appears as a child in /resume.
-  if (parentFile) {
-    setParentSession(sm, parentFile);
-  }
-
   return { manager: sm, file: sessionFile };
 }
 

package/settings.ts

@@ -1,12 +1,18 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { VALID_THINKING } from "./constants.ts";
+
+export interface AgentOverride {
+  model?: string;
+  thinking?: ThinkingLevel;
+  tools?: string[];
+}
 
 export interface DelegateSettings {
-  agentOverrides?: Record<
-    string,
-    { model?: string; thinking?: string; tools?: string[]; skills?: string[] }
-  >;
+  agentOverrides?: Record<string, AgentOverride>;
+  agentOverridesByParentModel?: Record<string, Record<string, AgentOverride>>;
 }
 
 /** Read and validate a JSON settings object, returning null on I/O or parse errors. */
@@ -16,29 +22,192 @@ export function readDelegateSettingsFile(
   try {
     const raw = fs.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      console.warn(
+        `[delegate] ignoring malformed settings file ${filePath}: expected a JSON object.`,
+      );
       return null;
+    }
     return parsed as Record<string, unknown>;
-  } catch {
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return null;
+    }
+    console.warn(
+      `[delegate] could not read settings file ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
     return null;
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeOverride(
+  raw: unknown,
+  source: string,
+  agentName: string,
+): AgentOverride | null {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: expected an object.`,
+    );
+    return null;
+  }
+
+  const result: AgentOverride = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (key === "model") {
+      if (typeof value !== "string" || value.trim().length === 0) {
+        console.warn(
+          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: model must be a nonempty string.`,
+        );
+        return null;
+      }
+      result.model = value.trim();
+    } else if (key === "thinking") {
+      if (typeof value !== "string" || !VALID_THINKING.has(value)) {
+        console.warn(
+          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: thinking must be a supported level.`,
+        );
+        return null;
+      }
+      result.thinking = value as ThinkingLevel;
+    } else if (key === "tools") {
+      if (
+        !Array.isArray(value) ||
+        value.some((tool) => typeof tool !== "string")
+      ) {
+        console.warn(
+          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: tools must be a string array.`,
+        );
+        return null;
+      }
+      result.tools = [...value];
+    } else if (key === "skills") {
+      console.warn(
+        `[delegate] ignoring unsupported skills override for agent '${agentName}' in ${source}: per-agent skill filtering is not supported.`,
+      );
+      return null;
+    } else {
+      console.warn(
+        `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: unknown field '${key}'.`,
+      );
+      return null;
+    }
+  }
+  return result;
+}
+
+function normalizeOverrides(
+  raw: unknown,
+  source: string,
+): Record<string, AgentOverride> {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverrides in ${source}: expected an object.`,
+    );
+    return {};
+  }
+
+  const result: Record<string, AgentOverride> = {};
+  const seenNames = new Map<string, string>();
+  for (const [agentName, value] of Object.entries(raw)) {
+    const normalizedAgentName = agentName.trim();
+    if (normalizedAgentName.length === 0) {
+      console.warn(
+        `[delegate] ignoring malformed settings override in ${source}: agent name must be nonempty.`,
+      );
+      continue;
+    }
+    const previousName = seenNames.get(normalizedAgentName);
+    if (previousName !== undefined) {
+      console.warn(
+        `[delegate] ignoring duplicate settings override in ${source}: agent keys '${previousName}' and '${agentName}' both normalize to '${normalizedAgentName}'.`,
+      );
+      continue;
+    }
+    seenNames.set(normalizedAgentName, agentName);
+    const override = normalizeOverride(value, source, normalizedAgentName);
+    if (override) result[normalizedAgentName] = override;
+  }
+  return result;
+}
+
+function normalizeOverridesByParentModel(
+  raw: unknown,
+  source: string,
+): Record<string, Record<string, AgentOverride>> {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverridesByParentModel in ${source}: expected an object.`,
+    );
+    return {};
+  }
+
+  const result: Record<string, Record<string, AgentOverride>> = {};
+  const seenModels = new Map<string, string>();
+  for (const [parentModel, overrides] of Object.entries(raw)) {
+    const normalizedParentModel = parentModel.trim();
+    if (normalizedParentModel.length === 0) {
+      console.warn(
+        `[delegate] ignoring malformed parent-model override in ${source}: model key must be nonempty.`,
+      );
+      continue;
+    }
+    const previousModel = seenModels.get(normalizedParentModel);
+    if (previousModel !== undefined) {
+      console.warn(
+        `[delegate] ignoring duplicate parent-model override in ${source}: model keys '${previousModel}' and '${parentModel}' both normalize to '${normalizedParentModel}'.`,
+      );
+      continue;
+    }
+    seenModels.set(normalizedParentModel, parentModel);
+    result[normalizedParentModel] = normalizeOverrides(
+      overrides,
+      `${source} (parent model '${normalizedParentModel}')`,
+    );
+  }
+  return result;
+}
+
 function getDelegateSettings(filePath: string): DelegateSettings | null {
   const settings = readDelegateSettingsFile(filePath);
   if (
     !settings?.delegate ||
     typeof settings.delegate !== "object" ||
     Array.isArray(settings.delegate)
-  )
+  ) {
+    if (settings?.delegate !== undefined) {
+      console.warn(
+        `[delegate] ignoring malformed delegate settings in ${filePath}: expected an object.`,
+      );
+    }
     return null;
-  return settings.delegate as DelegateSettings;
+  }
+  const raw = settings.delegate as Record<string, unknown>;
+  const result: DelegateSettings = {};
+  if (raw.agentOverrides !== undefined) {
+    result.agentOverrides = normalizeOverrides(raw.agentOverrides, filePath);
+  }
+  if (raw.agentOverridesByParentModel !== undefined) {
+    result.agentOverridesByParentModel = normalizeOverridesByParentModel(
+      raw.agentOverridesByParentModel,
+      filePath,
+    );
+  }
+  return result;
 }
 
 const delegateSettingsCache = new Map<string, DelegateSettings | null>();
 
 /** Load merged delegate settings: project overrides user.
- * Result is cached per cwd for the lifetime of the delegate call. */
+ * Result is cached per cwd until the next delegate dispatch clears it. */
 export function loadDelegateSettings(cwd: string): DelegateSettings | null {
   const key = path.resolve(cwd);
   const cached = delegateSettingsCache.get(key);
@@ -68,11 +237,64 @@ export function loadDelegateSettings(cwd: string): DelegateSettings | null {
     return null;
   }
   const result: DelegateSettings = {
-    agentOverrides: {
-      ...(user?.agentOverrides ?? {}),
-      ...(project?.agentOverrides ?? {}),
-    },
+    ...(user?.agentOverrides || project?.agentOverrides
+      ? {
+          agentOverrides: mergeOverrides(
+            user?.agentOverrides,
+            project?.agentOverrides,
+          ),
+        }
+      : {}),
+    ...(user?.agentOverridesByParentModel ||
+    project?.agentOverridesByParentModel
+      ? {
+          agentOverridesByParentModel: mergeParentModelOverrides(
+            user?.agentOverridesByParentModel,
+            project?.agentOverridesByParentModel,
+          ),
+        }
+      : {}),
   };
   delegateSettingsCache.set(key, result);
   return result;
 }
+
+function mergeOverride(
+  base: AgentOverride | undefined,
+  override: AgentOverride | undefined,
+): AgentOverride {
+  return { ...(base ?? {}), ...(override ?? {}) };
+}
+
+function mergeOverrides(
+  user: Record<string, AgentOverride> | undefined,
+  project: Record<string, AgentOverride> | undefined,
+): Record<string, AgentOverride> {
+  const result: Record<string, AgentOverride> = {};
+  for (const name of new Set([
+    ...Object.keys(user ?? {}),
+    ...Object.keys(project ?? {}),
+  ])) {
+    result[name] = mergeOverride(user?.[name], project?.[name]);
+  }
+  return result;
+}
+
+function mergeParentModelOverrides(
+  user: Record<string, Record<string, AgentOverride>> | undefined,
+  project: Record<string, Record<string, AgentOverride>> | undefined,
+): Record<string, Record<string, AgentOverride>> {
+  const result: Record<string, Record<string, AgentOverride>> = {};
+  for (const model of new Set([
+    ...Object.keys(user ?? {}),
+    ...Object.keys(project ?? {}),
+  ])) {
+    result[model] = mergeOverrides(user?.[model], project?.[model]);
+  }
+  return result;
+}
+
+/** Clear settings read from earlier delegate calls so edits are visible. */
+export function clearDelegateSettingsCache(): void {
+  delegateSettingsCache.clear();
+}

package/task-resolution.ts

@@ -1,6 +1,7 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import {
+  BUILTIN_AGENT_NAMES,
   DEFAULT_AGENT_NAME,
   DEFAULT_TOOLS,
   VALID_THINKING,
@@ -8,7 +9,7 @@ import {
 import { TOOL_FACTORIES, resolveToolGroups } from "./tools.ts";
 import { configFor } from "./pool.ts";
 import { isSessionBusy } from "./tickets.ts";
-import { buildSubagentSystemPrompt } from "./agents.ts";
+import { BUILTIN_AGENT_CONFIGS, buildSubagentSystemPrompt } from "./agents.ts";
 import { buildParentTranscript } from "./parent-context.ts";
 import { findAvailableAlternative, resolveModelRequest } from "./model.ts";
 import { resolveModelSpec } from "./config.ts";
@@ -91,6 +92,52 @@ export function validateTasks(
   agents: Map<string, AgentConfig>,
   parentModelId: string | undefined,
 ): DelegateToolResult | null {
+  const unknown: string[] = [];
+  for (const task of tasks) {
+    if (
+      task.agent &&
+      !(BUILTIN_AGENT_NAMES as readonly string[]).includes(task.agent) &&
+      !agents.has(task.agent)
+    ) {
+      unknown.push(task.agent);
+    }
+  }
+  if (unknown.length) {
+    const names = [...new Set([...BUILTIN_AGENT_NAMES, ...agents.keys()])];
+    return noticeResult(
+      `Unknown agent(s): ${unknown.join(", ")}. Available: ${names.join(", ") || "(none)"}. Call delegate with an empty tasks array for help.`,
+      tasks,
+      parentModelId,
+    );
+  }
+
+  // Scratch sessions are deliberately one-shot. This check uses the
+  // effective workspace, so reviewer gets the same protection even when the
+  // caller omits workspace. Explicit scratch is never silently promoted to
+  // shared.
+  for (const [index, task] of tasks.entries()) {
+    const agent = task.agent
+      ? (agents.get(task.agent) ?? BUILTIN_AGENT_CONFIGS[task.agent])
+      : undefined;
+    const workspace = task.workspace ?? agent?.workspace ?? "shared";
+    const sessionAction = task.sessionAction ?? task.action;
+    if (
+      workspace === "scratch" &&
+      (task.sessionId || task.resumeFrom || sessionAction !== undefined)
+    ) {
+      const defaultText =
+        task.workspace === undefined && agent?.workspace === "scratch"
+          ? "defaults to workspace `scratch`"
+          : "uses workspace `scratch`";
+      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}.`,
+        tasks,
+        parentModelId,
+      );
+    }
+  }
+
   // Disallow same sessionId across multiple parallel tasks (one agent can't serve two prompts concurrently).
   const sessionIds = tasks.map((t) => t.sessionId).filter(Boolean) as string[];
   const duplicateSessions = sessionIds.filter(
@@ -136,21 +183,6 @@ export function validateTasks(
     return noticeResult(duplicateIds.join(" "), tasks, parentModelId);
   }
 
-  const unknown: string[] = [];
-  for (const t of tasks) {
-    if (t.agent && t.agent !== DEFAULT_AGENT_NAME && !agents.has(t.agent)) {
-      unknown.push(t.agent);
-    }
-  }
-  if (unknown.length) {
-    const names = [DEFAULT_AGENT_NAME, ...agents.keys()];
-    return noticeResult(
-      `Unknown agent(s): ${unknown.join(", ")}. Available: ${names.join(", ") || "(none)"}. Call delegate with an empty tasks array for help.`,
-      tasks,
-      parentModelId,
-    );
-  }
-
   return null;
 }
 
@@ -187,11 +219,21 @@ export function resolveTasks(
 
   return tasks.map((t, i) => {
     const isDefaultAgent = t.agent === DEFAULT_AGENT_NAME;
-    const agent = t.agent && !isDefaultAgent ? agents.get(t.agent) : undefined;
+    const agent = t.agent
+      ? (agents.get(t.agent) ?? BUILTIN_AGENT_CONFIGS[t.agent])
+      : undefined;
+    const isBuiltinAgent = agent?.builtin === true;
     const cwd = resolveCwd(t.cwd ?? ctx.cwd, ctx.cwd);
 
     // Load settings-based overrides for this agent
     const settings = loadDelegateSettings(cwd);
+    const parentModelKey = ctx.model
+      ? `${ctx.model.provider}/${ctx.model.id}`
+      : undefined;
+    const parentModelOverride =
+      t.agent && !isDefaultAgent && parentModelKey
+        ? settings?.agentOverridesByParentModel?.[parentModelKey]?.[t.agent]
+        : undefined;
     const agentOverride =
       t.agent && !isDefaultAgent && settings?.agentOverrides?.[t.agent]
         ? settings.agentOverrides[t.agent]
@@ -208,7 +250,8 @@ export function resolveTasks(
     );
     let tools: string[] = [];
     const warnings: string[] = [];
-    if (t.workspace === "scratch") {
+    const workspace = t.workspace ?? agent?.workspace ?? "shared";
+    if (workspace === "scratch") {
       warnings.push(
         "Scratch workspace: relative file changes run in a disposable CoW copy and are discarded.",
       );
@@ -233,9 +276,11 @@ export function resolveTasks(
     if (t.sessionAction !== "close" && t.sessionAction !== "list") {
       tools = resolveToolGroups(
         t.tools ??
+          parentModelOverride?.tools ??
           agentOverride?.tools ??
-          agent?.tools ??
           (isDefaultAgent ? parentNativeTools : undefined) ??
+          (isBuiltinAgent ? agent?.tools : undefined) ??
+          agent?.tools ??
           (isPoolHit ? pooledConfig?.tools : undefined) ??
           DEFAULT_TOOLS,
       );
@@ -318,20 +363,32 @@ export function resolveTasks(
     let thinking: ThinkingLevel = "off";
 
     if (t.sessionAction !== "close" && t.sessionAction !== "list") {
+      const agentType = t.agent ?? "inline";
+      // The built-in `default` profile bypasses delegate/settings model
+      // overrides for backwards compatibility. The other built-ins accept
+      // task and settings.json model overrides, but deliberately ignore the
+      // legacy delegate.json agent model map so they inherit the parent unless
+      // an explicit modern override wins.
+      const modelSpec = isDefaultAgent
+        ? t.model
+        : isBuiltinAgent
+          ? (t.model ?? parentModelOverride?.model ?? agentOverride?.model)
+          : resolveModelSpec({
+              taskModel:
+                t.model ?? parentModelOverride?.model ?? agentOverride?.model,
+              agentType,
+              frontmatterModel: agent?.model,
+            });
+
       // A pool hit always runs its frozen model, but an explicitly requested
       // task/profile model still has to be resolved so checkout can reject a
       // contradictory request rather than silently discarding it. Naming the
       // built-in `default` profile is also explicit: it requests the live
       // parent model, so reuse fails clearly if the pool was frozen differently.
       if (pooledConfig) {
-        const requestedModelSpec =
-          t.model ??
-          (t.agent && !isDefaultAgent
-            ? (agentOverride?.model ?? agent?.model)
-            : undefined);
-        if (requestedModelSpec) {
+        if (modelSpec) {
           const requested = resolveModelRequest(
-            requestedModelSpec,
+            modelSpec,
             ctx.modelRegistry,
             ctx.model,
           );
@@ -339,7 +396,7 @@ export function resolveTasks(
           modelSuffix = requested.strippedSuffix;
           if (!requestedModel) {
             throw new Error(
-              `${formatTaskRef(i, t.id)}: requested model '${requestedModelSpec}' is not available. Check provider config or remove the model field to continue the pooled session.`,
+              `${formatTaskRef(i, t.id)}: requested model '${modelSpec}' is not available. Check provider config or remove the model field to continue the pooled session.`,
             );
           }
         } else if (isDefaultAgent) {
@@ -347,17 +404,6 @@ export function resolveTasks(
         }
         model = pooledConfig.model;
       } else {
-        // The built-in `default` profile bypasses delegate.json and settings:
-        // absent a task override, it means this exact live parent Model object.
-        // Other tasks retain the normal task > config > frontmatter chain.
-        const agentType = t.agent ?? "inline";
-        const modelSpec = isDefaultAgent
-          ? t.model
-          : resolveModelSpec({
-              taskModel: t.model ?? agentOverride?.model,
-              agentType,
-              frontmatterModel: agent?.model,
-            });
         const resolvedRequest = modelSpec
           ? resolveModelRequest(modelSpec, ctx.modelRegistry, ctx.model)
           : undefined;
@@ -376,7 +422,7 @@ export function resolveTasks(
           );
         }
 
-        model = isDefaultAgent
+        model = isBuiltinAgent
           ? (resolvedModel ?? ctx.model)
           : (resolvedModel ??
             findAvailableAlternative(ctx.model, ctx.modelRegistry) ??
@@ -398,15 +444,28 @@ export function resolveTasks(
       // changed, rather than silently reusing a stale frozen value. The final
       // pooled fallback is reachable only when parentDefaults.thinking is
       // undefined (headless parent without a thinking level).
-      const thinkingRaw =
-        t.thinking ??
-        agentOverride?.thinking ??
-        agent?.thinking ??
-        (isPoolHit && !isDefaultAgent ? pooledConfig?.thinking : undefined) ??
-        modelSuffix ??
-        (isDefaultAgent ? parentDefaults.thinking : undefined) ??
-        (isPoolHit ? pooledConfig?.thinking : undefined) ??
-        "off";
+      const thinkingRaw = isBuiltinAgent
+        ? isDefaultAgent
+          ? (t.thinking ??
+            parentModelOverride?.thinking ??
+            agentOverride?.thinking ??
+            modelSuffix ??
+            parentDefaults.thinking ??
+            (isPoolHit ? pooledConfig?.thinking : undefined) ??
+            "off")
+          : (t.thinking ??
+            parentModelOverride?.thinking ??
+            agentOverride?.thinking ??
+            (isPoolHit ? pooledConfig?.thinking : undefined) ??
+            modelSuffix ??
+            parentDefaults.thinking ??
+            "off")
+        : (t.thinking ??
+          agentOverride?.thinking ??
+          agent?.thinking ??
+          (isPoolHit ? pooledConfig?.thinking : undefined) ??
+          modelSuffix ??
+          "off");
       thinking = VALID_THINKING.has(thinkingRaw)
         ? (thinkingRaw as ThinkingLevel)
         : "off";
@@ -423,7 +482,7 @@ export function resolveTasks(
       ...t,
       id: t.id,
       cwd,
-      workspace: t.workspace ?? "shared",
+      workspace,
       systemPrompt,
       model: model!,
       tools,
@@ -433,9 +492,7 @@ export function resolveTasks(
       prompt: prompt ?? "",
       // Keep the built-in selector visible in progress/results. Omitted-agent
       // inline tasks retain the established `ad-hoc` label and config namespace.
-      agentName: isDefaultAgent
-        ? DEFAULT_AGENT_NAME
-        : (agent?.name ?? "ad-hoc"),
+      agentName: agent?.name ?? "ad-hoc",
       warnings,
       reuseIntent: {
         model: requestedModel,

package/types.ts

@@ -18,9 +18,15 @@ export interface AgentConfig {
   name: string;
   description: string;
   model?: string;
-  thinking: ThinkingLevel;
+  /** Markdown agents default invalid/omitted values to "off". Built-ins omit
+   *  this field so they can inherit the parent's thinking level. */
+  thinking?: ThinkingLevel;
   tools: string[];
   systemPrompt: string;
+  /** Built-in profiles are immutable and cannot be shadowed by Markdown. */
+  builtin?: boolean;
+  /** Default workspace for a built-in profile. Custom agents use shared. */
+  workspace?: WorkspaceMode;
   /** Origin of the profile. `claude` denotes imported .claude/agents files. */
   scope?: "project" | "global" | "claude";
 }
@@ -251,8 +257,6 @@ export interface TaskRunEnv {
   /** Abort signal — parent's for sync, ticket's for async. May be undefined when no parent signal is available. */
   signal: AbortSignal | undefined;
   modelRegistry: ModelRegistry;
-  /** Parent session manager — used to link subagent sessions for /resume. */
-  parentSessionManager: { getSessionFile?(): string | undefined } | undefined;
   /** Ticket id for busy-guard self-checks. undefined for sync. */
   ticketId?: string;
   /** When the delegate started. Used for close/list progress (elapsed time). */