killeros 1.5.6 → 1.5.8

package/killeros/subagents.ts

@@ -1,10 +1,9 @@
 import { spawn } from "node:child_process";
 import { closeSync, openSync, readSync, readdirSync, statSync } from "node:fs";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { getSupportedThinkingLevels, StringEnum, type Model, type ModelThinkingLevel } from "@earendil-works/pi-ai";
+import os from "node:os";
+import path from "node:path";
+import { getSupportedThinkingLevels, StringEnum, type Model, type ModelThinkingLevel } from "@earendil-works/pi-ai";
 import {
   CONFIG_DIR_NAME,
   getAgentDir,
@@ -29,9 +28,11 @@ export const SUBAGENT_LIMITS = {
   threadRetentionRecords: 64,
   threadRetentionBytes: 128 * 1024 * 1024,
   roleFileBytes: 64 * 1024,
-  taskCharacters: 20_000,
-  killGraceMs: 5_000,
-  defaultWallTimeMs: 1_800_000,
+  taskCharacters: 20_000,
+  killGraceMs: 5_000,
+  defaultMaxTurns: 64,
+  defaultQuotaTokens: 2_000_000,
+  defaultWallTimeMs: 1_800_000,
   processExitWaitMs: 10_000,
 } as const;
 
@@ -46,7 +47,7 @@ const ROLE_FIELDS = new Set(["name", "description", "access", "tools", "model",
 
 type ThinkingLevel = ModelThinkingLevel;
 export type AgentAccess = "read" | "write";
-export type AgentSource = "bundled" | "personal" | "project" | "inline";
+export type AgentSource = "bundled" | "personal" | "project" | "inline" | "legacy";
 export type AgentScope = "user" | "project" | "both";
 export type SubagentStatus = "queued" | "running" | "complete" | "failed" | "cancelled" | "limited" | "orphaned";
 
@@ -136,8 +137,9 @@ export interface SubagentDetails {
   threads?: SubagentThread[];
   activeThreads?: SubagentThread[];
   doneThreads?: SubagentThread[];
-  selectedThreadId?: string;
-  wait?: SubagentWaitSummary;
+  selectedThreadId?: string;
+  wait?: SubagentWaitSummary;
+  backgroundStarted?: boolean;
 }
 
 export interface SubagentWaitSummary {
@@ -192,9 +194,10 @@ interface SpawnedProcess {
   once(event: "close", listener: (code: number | null) => void): this;
 }
 
-type SubagentLimits = { [Key in keyof typeof SUBAGENT_LIMITS]: number } & {
-  wallTimeMs?: number;
-  jsonlLineBytes?: number;
+type SubagentLimits = { [Key in keyof typeof SUBAGENT_LIMITS]: number } & {
+  wallTimeMs?: number;
+  maxTurns?: number;
+  jsonlLineBytes?: number;
   traceBytes?: number;
   stderrBytes?: number;
   taskOutputBytes?: number;
@@ -202,9 +205,10 @@ type SubagentLimits = { [Key in keyof typeof SUBAGENT_LIMITS]: number } & {
   quotaUsd?: number;
 };
 
-export interface SubagentRuntimeOptions {
-  bundledAgentsDir?: string;
-  userAgentsDir?: string;
+export interface SubagentRuntimeOptions {
+  /** Explicit test or embedding role directory; KillerOS ships no bundled roles. */
+  bundledAgentsDir?: string;
+  userAgentsDir?: string;
   webExtension?: string;
   spawnProcess?: (args: string[], cwd: string, environment?: NodeJS.ProcessEnv) => SpawnedProcess;
   limits?: Partial<SubagentLimits>;
@@ -396,20 +400,21 @@ function findProjectAgentsDir(cwd: string): string | null {
   }
 }
 
-export function discoverAgentRoles(
-  cwd: string,
-  scope: AgentScope,
-  projectTrusted: boolean,
-  options: Pick<SubagentRuntimeOptions, "bundledAgentsDir" | "userAgentsDir" | "limits"> = {},
-): AgentDiscoveryResult {
-  const limits = { ...SUBAGENT_LIMITS, ...options.limits };
-  const bundledDir = options.bundledAgentsDir ?? fileURLToPath(new URL("../agents/", import.meta.url));
-  const userDir = options.userAgentsDir ?? path.join(getAgentDir(), "agents");
+export function discoverAgentRoles(
+  cwd: string,
+  scope: AgentScope,
+  projectTrusted: boolean,
+  options: Pick<SubagentRuntimeOptions, "bundledAgentsDir" | "userAgentsDir" | "limits"> = {},
+): AgentDiscoveryResult {
+  const limits = { ...SUBAGENT_LIMITS, ...options.limits };
+  const bundledDir = options.bundledAgentsDir;
+  const userDir = options.userAgentsDir ?? path.join(getAgentDir(), "agents");
   const wantsProject = scope === "project" || scope === "both";
   if (wantsProject && !projectTrusted) throw new Error("Project agents require a trusted project");
   const projectAgentsDir = wantsProject ? findProjectAgentsDir(cwd) : null;
 
-  const layers: Array<{ dir: string; source: AgentSource }> = [{ dir: bundledDir, source: "bundled" }];
+  const layers: Array<{ dir: string; source: AgentSource }> = [];
+  if (bundledDir) layers.push({ dir: bundledDir, source: "bundled" });
   if (scope === "user" || scope === "both") layers.push({ dir: userDir, source: "personal" });
   if (wantsProject && projectAgentsDir) layers.push({ dir: projectAgentsDir, source: "project" });
 
@@ -723,9 +728,10 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
       cwd: options.cwd,
       signal: options.signal,
       spawnProcess: options.spawnProcess,
-      limits: {
-        ...(options.timeoutMs === undefined ? {} : { wallTimeMs: options.timeoutMs }),
-        ...(limits.jsonlLineBytes === undefined ? {} : { jsonlLineBytes: limits.jsonlLineBytes }),
+      limits: {
+        ...(options.timeoutMs === undefined ? {} : { wallTimeMs: options.timeoutMs }),
+        ...(limits.maxTurns === undefined ? {} : { maxTurns: limits.maxTurns }),
+        ...(limits.jsonlLineBytes === undefined ? {} : { jsonlLineBytes: limits.jsonlLineBytes }),
         ...(limits.traceBytes === undefined ? {} : { traceBytes: limits.traceBytes }),
         ...(limits.stderrBytes === undefined ? {} : { stderrBytes: limits.stderrBytes }),
         ...(limits.taskOutputBytes === undefined ? {} : { outputBytes: limits.taskOutputBytes }),
@@ -811,11 +817,11 @@ type SpawnOptions = {
   agentScope?: AgentScope;
 };
 
-type SpawnSingleRequest = SpawnOptions & {
-  action?: "spawn";
-  agent: AgentSpec;
-  task: string;
-  name?: string;
+type SpawnSingleRequest = SpawnOptions & {
+  action?: "spawn";
+  agent?: AgentSpec;
+  task: string;
+  name?: string;
 };
 
 type SpawnParallelRequest = SpawnOptions & {
@@ -900,14 +906,15 @@ function requireOnlyFields(record: Record<string, unknown>, allowed: readonly st
   if (invalid) throw new Error(`Invalid subagent request: field ${JSON.stringify(invalid)} is not valid with action ${JSON.stringify(action)}.`);
 }
 
-function parseAgentSpec(value: unknown): AgentSpec {
-  if (typeof value === "string") {
-    if (!value.length) throw new Error("Invalid subagent request: agent must be a non-empty string or inline role.");
-    if ([...value].length > 64) throw new Error("Invalid subagent request: agent must be no longer than 64 characters.");
-    return value;
-  }
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("Invalid subagent request: agent must be a non-empty string or inline role.");
+function parseAgentSpec(value: unknown): AgentSpec | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") {
+    if (!value.length) throw new Error("Invalid subagent request: agent must be a non-empty role name or inline role.");
+    if ([...value].length > 64) throw new Error("Invalid subagent request: agent must be no longer than 64 characters.");
+    return value;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid subagent request: agent must be a role name, inline role, or omitted.");
   }
   const role = requireRecord(value, "inline role");
   for (const field of Object.keys(role)) {
@@ -943,28 +950,119 @@ function parseAgentSpec(value: unknown): AgentSpec {
   return { name, description, access, tools };
 }
 
-function inlineAgentRole(role: InlineAgentRole): AgentRole {
-  return {
-    ...role,
-    prompt: role.description,
-    source: "inline",
-    filePath: `inline:${role.name}`,
-  };
-}
-
-function parseTaskInputs(value: unknown, field: "tasks" | "chain", limits: Pick<SubagentLimits, "maxTasks" | "taskCharacters">): TaskInput[] {
+function inlineAgentRole(role: InlineAgentRole): AgentRole {
+  return {
+    ...role,
+    prompt: role.description,
+    source: "inline",
+    filePath: `inline:${role.name}`,
+  };
+}
+
+function activeParentTools(pi: ExtensionAPI): Set<string> | undefined {
+  const getActiveTools = (pi as unknown as { getActiveTools?: () => string[] }).getActiveTools;
+  return typeof getActiveTools === "function" ? new Set(getActiveTools.call(pi)) : undefined;
+}
+
+function validateAgentTools(agent: AgentRole, parentTools: ReadonlySet<string> | undefined): void {
+  if (!parentTools) return;
+  const unavailable = agent.tools.find((tool) => !parentTools.has(tool));
+  if (unavailable) throw new Error(`Role ${JSON.stringify(agent.name)} tool ${JSON.stringify(unavailable)} is not active for the parent`);
+}
+
+function genericAgentRole(parentTools: ReadonlySet<string> | undefined): AgentRole {
+  const tools = [...READ_TOOLS].filter((tool) => !parentTools || parentTools.has(tool));
+  if (tools.length === 0) throw new Error("No read-only child tools are active for the parent");
+  return {
+    name: "generic",
+    description: "Complete the assigned task and return the result to the parent.",
+    access: "read",
+    tools,
+    prompt: "Complete the assigned task and return the result to the parent.",
+    source: "inline",
+    filePath: "inline:generic",
+  };
+}
+
+function cloneAgentRole(agent: AgentRole): AgentRole {
+  return { ...agent, tools: [...agent.tools] };
+}
+
+function restorePersistedAgent(value: unknown): AgentRole | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const role = value as Record<string, unknown>;
+  const name = role.name;
+  const description = role.description;
+  const access = role.access;
+  const tools = role.tools;
+  const prompt = role.prompt;
+  const source = role.source;
+  const filePath = role.filePath;
+  if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/u.test(name)) return undefined;
+  if (typeof description !== "string" || !description.trim() || description.length > 500) return undefined;
+  if (access !== "read" && access !== "write") return undefined;
+  if (!Array.isArray(tools) || tools.length === 0 || tools.some((tool) => typeof tool !== "string" || !KNOWN_TOOLS.has(tool))) return undefined;
+  const uniqueTools = [...new Set(tools as string[])];
+  if (uniqueTools.length !== tools.length || access === "read" && uniqueTools.some((tool) => WRITE_TOOLS.has(tool))) return undefined;
+  if (typeof prompt !== "string" || !prompt.trim() || prompt.length > SUBAGENT_LIMITS.roleFileBytes) return undefined;
+  if (source !== "bundled" && source !== "personal" && source !== "project" && source !== "inline" && source !== "legacy") return undefined;
+  if (typeof filePath !== "string" || !filePath) return undefined;
+  const optionalString = (field: string): string | undefined => {
+    const item = role[field];
+    return item === undefined ? undefined : typeof item === "string" && item.trim() ? item : undefined;
+  };
+  const timeoutMs = role.timeoutMs;
+  if (timeoutMs !== undefined && (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_NODE_TIMER_MS)) return undefined;
+  return {
+    name,
+    description,
+    access,
+    tools: uniqueTools,
+    model: optionalString("model"),
+    thinking: optionalString("thinking"),
+    timeoutMs: typeof timeoutMs === "number" ? timeoutMs : undefined,
+    prompt,
+    source,
+    filePath,
+  };
+}
+
+function restoreLegacyAgent(thread: ThreadSnapshot, sourceHint?: SubagentTaskResult["agentSource"]): AgentRole | undefined {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/u.test(thread.role)) return undefined;
+  if (!Array.isArray(thread.tools) || thread.tools.length === 0) return undefined;
+  const tools = [...new Set(thread.tools)];
+  if (tools.length !== thread.tools.length || tools.some((tool) => !KNOWN_TOOLS.has(tool))) return undefined;
+  const access = thread.capabilityBoundary?.filesystem;
+  if (access !== "read" && access !== "write") return undefined;
+  if (access === "read" && tools.some((tool) => WRITE_TOOLS.has(tool))) return undefined;
+  const source = sourceHint === "bundled" || sourceHint === "personal" || sourceHint === "project"
+    ? sourceHint
+    : "legacy";
+  return {
+    name: thread.role,
+    description: "Persisted role contract from an earlier KillerOS release.",
+    access,
+    tools,
+    prompt: "Continue the saved child task. Use only the retained role tools and return a handoff to the parent.",
+    source,
+    filePath: `legacy:${source}:${thread.role}`,
+  };
+}
+
+function parseTaskInputs(value: unknown, field: "tasks" | "chain", limits: Pick<SubagentLimits, "maxTasks" | "taskCharacters">): TaskInput[] {
   if (!Array.isArray(value) || value.length === 0) {
     throw new Error(`Invalid subagent request: ${field} must be a non-empty array.`);
   }
   if (value.length > limits.maxTasks) throw new Error(`At most ${limits.maxTasks} subagent tasks are allowed`);
   return value.map((entry, index) => {
-    const task = requireRecord(entry, `${field}[${index}]`);
-    requireOnlyFields(task, ["agent", "task", "name"], `spawn ${field}`);
-    const name = optionalThreadName(task);
-    return {
-      agent: parseAgentSpec(task.agent),
-      task: requireTextField(task, "task", limits.taskCharacters),
-      ...(name === undefined ? {} : { name }),
+    const task = requireRecord(entry, `${field}[${index}]`);
+    requireOnlyFields(task, ["agent", "task", "name"], `spawn ${field}`);
+    const name = optionalThreadName(task);
+    const agent = parseAgentSpec(task.agent);
+    return {
+      ...(agent === undefined ? {} : { agent }),
+      task: requireTextField(task, "task", limits.taskCharacters),
+      ...(name === undefined ? {} : { name }),
     };
   });
 }
@@ -1141,25 +1239,25 @@ function prepareSubagentRequest(
 }
 
 function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "maxReadConcurrency" | "taskCharacters">) {
-  const inlineAgentSchema = Type.Object({
-    name: Type.String({ minLength: 1, maxLength: 64, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }),
-    description: Type.String({ minLength: 1, maxLength: 500 }),
-    access: StringEnum(["read", "write"] as const),
-    tools: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, uniqueItems: true }),
-  }, { additionalProperties: false, description: "Ephemeral role for this spawn only; tools must be active for the parent" });
-  const agentSchema = Type.Union([
-    Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
-    inlineAgentSchema,
-  ]);
-  const taskSchema = Type.Object({
-    agent: agentSchema,
-    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Bounded task for the role" }),
-    name: Type.Optional(Type.String({ minLength: 1, maxLength: 48, pattern: THREAD_NAME_PATTERN, description: "Parent-scoped child display name" })),
-  }, { additionalProperties: false });
-  const chainTaskSchema = Type.Object({
-    agent: agentSchema,
-    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task with optional {previous} handoff placeholder" }),
-    name: Type.Optional(Type.String({ minLength: 1, maxLength: 48, pattern: THREAD_NAME_PATTERN, description: "Parent-scoped child display name" })),
+  const inlineAgentSchema = Type.Object({
+    name: Type.String({ minLength: 1, maxLength: 64, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }),
+    description: Type.String({ minLength: 1, maxLength: 500 }),
+    access: StringEnum(["read", "write"] as const),
+    tools: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, uniqueItems: true }),
+  }, { additionalProperties: false, description: "Optional role definition for this spawn; tools must be active for the parent" });
+  const agentSchema = Type.Union([
+    Type.String({ minLength: 1, maxLength: 64, description: "Optional custom role name from an approved agents folder" }),
+    inlineAgentSchema,
+  ]);
+  const taskSchema = Type.Object({
+    agent: Type.Optional(agentSchema),
+    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Bounded task; omitted agent uses the generic read-only child" }),
+    name: Type.Optional(Type.String({ minLength: 1, maxLength: 48, pattern: THREAD_NAME_PATTERN, description: "Parent-scoped child display name" })),
+  }, { additionalProperties: false });
+  const chainTaskSchema = Type.Object({
+    agent: Type.Optional(agentSchema),
+    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task with optional {previous}; omitted agent uses the generic read-only child" }),
+    name: Type.Optional(Type.String({ minLength: 1, maxLength: 48, pattern: THREAD_NAME_PATTERN, description: "Parent-scoped child display name" })),
   }, { additionalProperties: false });
   const threadId = Type.String({ minLength: 1, maxLength: 128, description: "Existing child thread ID; omit when spawning because KillerOS creates it" });
   return Type.Object({
@@ -1174,12 +1272,12 @@ function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "maxRead
     tasks: Type.Optional(Type.Array(taskSchema, { minItems: 1, maxItems: limits.maxTasks, description: `Parallel role tasks: read-only batches run concurrently up to ${limits.maxReadConcurrency}; batches with writers use one shared slot by default. Set writerConcurrency to opt into a larger shared pool; concurrent writers share the parent worktree, so callers must prove path ownership` })),
     writerConcurrency: Type.Optional(Type.Integer({ minimum: 1, maximum: limits.maxTasks, description: `Optional shared-pool cap for parallel tasks that include writers. Defaults to 1 when writers are selected; values above 1 opt into concurrent shared-worktree writes. Concurrent writers must prove path ownership` })),
     chain: Type.Optional(Type.Array(chainTaskSchema, { minItems: 1, maxItems: limits.maxTasks, description: "Sequential role tasks; {previous} inserts the prior result" })),
-    model: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Model for every task as provider/model; inherit uses each role setting or the active parent" })),
-    thinking: Type.Optional(Type.String({ minLength: 1, maxLength: 16, description: "Thinking effort for every task: off, minimal, low, medium, high, xhigh, max, or inherit" })),
-    agentScope: Type.Optional(StringEnum(["user", "project", "both"] as const, {
-      default: "user",
-      description: "Role sources: user includes bundled and personal; project includes bundled and trusted project; both includes all",
-    })),
+    model: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Optional model for every task as provider/model; omitted or inherit uses the selected role default, then the active parent. Set this when the user requires one model for the batch" })),
+    thinking: Type.Optional(Type.String({ minLength: 1, maxLength: 16, description: "Optional thinking effort for every task: off, minimal, low, medium, high, xhigh, max, or inherit. Omitted or inherit uses the selected role default, then the active parent" })),
+    agentScope: Type.Optional(StringEnum(["user", "project", "both"] as const, {
+      default: "user",
+      description: "Custom role sources: user includes personal; project includes trusted project; both includes both",
+    })),
   }, { additionalProperties: false });
 }
 
@@ -1234,7 +1332,7 @@ function buildSteeredTask(task: string, steering: readonly string[], maxCharacte
   return `${taskText}${steeringLabel}${steeringText}`;
 }
 
-export type TaskInput = { agent: AgentSpec; task: string; name?: string };
+export type TaskInput = { agent?: AgentSpec; task: string; name?: string };
 
 function steeredTaskWouldExceedLimit(task: string, steering: readonly string[], maxCharacters: number): boolean {
   if (!steering.length) return false;
@@ -1298,12 +1396,14 @@ interface ChildSession {
   directory: string;
 }
 
-interface ThreadMetadata {
-  displayName: string;
-  attempt: number;
-  session: ChildSession;
-  persistentSession: boolean;
-}
+interface ThreadMetadata {
+  displayName: string;
+  attempt: number;
+  session: ChildSession;
+  persistentSession: boolean;
+  agent?: AgentRole;
+  thinking?: ThinkingLevel;
+}
 
 type ThreadSnapshot = SubagentThread & {
   displayName?: string;
@@ -1445,7 +1545,7 @@ function restorePersistedResult(value: unknown, thread: ThreadSnapshot): Subagen
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const source = value as Record<string, any>;
   const statuses = new Set<SubagentStatus>(["queued", "running", "complete", "failed", "cancelled", "limited"]);
-  const agentSources = new Set<SubagentTaskResult["agentSource"]>(["bundled", "personal", "project", "inline", "unknown"]);
+  const agentSources = new Set<SubagentTaskResult["agentSource"]>(["bundled", "personal", "project", "inline", "legacy", "unknown"]);
   if (typeof source.id !== "string" || source.id !== thread.id) return undefined;
   const status = source.status ?? (thread.state === "done" ? "complete" : thread.state === "failed" ? "failed" : "cancelled");
   if (typeof status !== "string" || !statuses.has(status as SubagentStatus)) return undefined;
@@ -1533,23 +1633,26 @@ function threadBoardRecord(result: SubagentTaskResult): ThreadBoardRecord {
 }
 
 export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeOptions = {}): SubagentControlApi {
-  const limits = { ...SUBAGENT_LIMITS, ...options.limits };
-  const spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
-  let threads = new SubagentThreadRegistry();
-  const activeRuntimes = new Map<string, ActiveThreadRuntime>();
-  const threadMetadata = new Map<string, ThreadMetadata>();
-  const threadResources = new Map<string, { directory: string; persistent: boolean; handles: Set<SubagentProcessHandle> }>();
-  const backgroundBatches = new Set<Promise<unknown>>();
-  const savedResults = new Map<string, SubagentTaskResult>();
-  const evictedThreadParents = new Map<string, string | undefined>();
-  let sessionGeneration = 0;
+  const limits = { ...SUBAGENT_LIMITS, ...options.limits };
+  const spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
+  let threads = new SubagentThreadRegistry();
+  const activeRuntimes = new Map<string, ActiveThreadRuntime>();
+  const threadMetadata = new Map<string, ThreadMetadata>();
+  type ThreadResource = { directory: string; persistent: boolean; handles: Set<SubagentProcessHandle> };
+  const threadResources = new Map<string, ThreadResource>();
+  const backgroundBatches = new Set<Promise<unknown>>();
+  const savedResults = new Map<string, SubagentTaskResult>();
+  const evictedThreadParents = new Map<string, string | undefined>();
+  let terminalCleanupQueue: Promise<void> = Promise.resolve();
+  let sessionGeneration = 0;
   let persistenceWarning: string | undefined;
 
-  const persistText = (value: string | undefined, maxBytes: number): string | undefined => {
-    if (value === undefined) return undefined;
-    return truncateUtf8(value, maxBytes).text;
-  };
-  const persistenceAppend = (record: Record<string, unknown>): void => {
+  const persistText = (value: string | undefined, maxBytes: number): string | undefined => {
+    if (value === undefined) return undefined;
+    return truncateUtf8(value, maxBytes).text;
+  };
+  const lifecycleOutput = (value: string | undefined): string | undefined => value?.trim() ? value : undefined;
+  const persistenceAppend = (record: Record<string, unknown>): void => {
     const appendEntry = (pi as unknown as { appendEntry?: (type: string, data: unknown) => void }).appendEntry;
     if (!appendEntry) return;
     try {
@@ -1558,9 +1661,11 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       persistenceWarning ??= `Subagent persistence is unavailable: ${error instanceof Error ? error.message : String(error)}`;
     }
   };
-  const persistedThread = (thread: ThreadSnapshot): Record<string, unknown> => {
-    const session = threadSession(thread, threadMetadata) ?? { id: `killeros-${safeSessionId(thread.id)}`, directory: "" };
-    return {
+  const persistedThread = (thread: ThreadSnapshot): Record<string, unknown> => {
+    const session = threadSession(thread, threadMetadata) ?? { id: `killeros-${safeSessionId(thread.id)}`, directory: "" };
+    const metadata = threadMetadata.get(thread.id);
+    const agent = metadata?.agent;
+    return {
       id: thread.id,
       parentId: thread.parentId,
       displayName: threadDisplayName(thread, threadMetadata),
@@ -1568,8 +1673,23 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       role: thread.role,
       prompt: clipCharacters(thread.prompt, limits.taskCharacters),
       model: thread.model,
-      tools: thread.tools.slice(0, 32).map((tool) => clipCharacters(tool, 64)),
-      capabilityBoundary: { ...thread.capabilityBoundary },
+      tools: thread.tools.slice(0, 32).map((tool) => clipCharacters(tool, 64)),
+      ...(agent ? {
+        roleDefinition: {
+          name: agent.name,
+          description: persistText(agent.description, 500),
+          access: agent.access,
+          tools: agent.tools.slice(0, 32).map((tool) => clipCharacters(tool, 64)),
+          model: agent.model,
+          thinking: agent.thinking,
+          timeoutMs: agent.timeoutMs,
+          prompt: persistText(agent.prompt, limits.roleFileBytes),
+          source: agent.source,
+          filePath: persistText(agent.filePath, 4_000),
+        },
+        thinking: metadata?.thinking,
+      } : {}),
+      capabilityBoundary: { ...thread.capabilityBoundary },
       session: { ...session },
       state: thread.state,
       usage: { ...thread.usage },
@@ -1638,12 +1758,12 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     });
   };
 
-  const restoreRecords = (
-    entries: readonly unknown[],
-    parentId: string,
-    expectedSession?: (threadId: string) => ChildSession | undefined,
-  ): Array<{ thread: ThreadSnapshot; result?: SubagentTaskResult }> => {
-    const records = new Map<string, { thread: ThreadSnapshot; result?: SubagentTaskResult }>();
+  const restoreRecords = (
+    entries: readonly unknown[],
+    parentId: string,
+    expectedSession?: (threadId: string) => ChildSession | undefined,
+  ): Array<{ thread: ThreadSnapshot; result?: SubagentTaskResult; agent?: AgentRole; thinking?: ThinkingLevel }> => {
+    const records = new Map<string, { thread: ThreadSnapshot; result?: SubagentTaskResult; agent?: AgentRole; thinking?: ThinkingLevel }>();
     for (const entry of entries) {
       try {
         if (!entry || typeof entry !== "object") continue;
@@ -1654,10 +1774,14 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         const record = data as Record<string, any>;
         if (record.version !== 1 || typeof record.parentId !== "string" || record.parentId !== parentId) continue;
         if (record.event === "spawn" || record.event === "snapshot") {
-          const rawThread = record.thread;
+          const rawThread = record.thread;
           if (!rawThread || typeof rawThread !== "object" || typeof rawThread.id !== "string" || rawThread.parentId !== parentId) continue;
           if (typeof rawThread.role !== "string" || typeof rawThread.prompt !== "string" || typeof rawThread.model !== "string") continue;
-          const thread = { ...rawThread } as ThreadSnapshot;
+          const thread = { ...rawThread } as ThreadSnapshot;
+          const thinking = rawThread.thinking === undefined
+            ? undefined
+            : typeof rawThread.thinking === "string" && rawThread.thinking.trim() ? rawThread.thinking as ThinkingLevel : undefined;
+          if (rawThread.thinking !== undefined && thinking === undefined) continue;
           thread.prompt = clipCharacters(thread.prompt, limits.taskCharacters);
           thread.result = typeof rawThread.result === "string" ? persistText(rawThread.result, 256 * 1024) : rawThread.result;
           thread.tools = Array.isArray(rawThread.tools) ? rawThread.tools.slice(0, 32) : [];
@@ -1674,13 +1798,17 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             id: `killeros-${safeSessionId(thread.id)}`,
             directory: "",
           };
-          if (thread.state === "queued" || thread.state === "active") {
-            thread.state = "orphaned" as SubagentThreadState;
-            thread.stopReason = "parent_restarted";
-          }
-          const result = record.result === undefined ? undefined : restorePersistedResult(record.result, thread);
-          if (record.result !== undefined && !result) continue;
-          records.set(thread.id, { thread, result });
+          if (thread.state === "queued" || thread.state === "active") {
+            thread.state = "orphaned" as SubagentThreadState;
+            thread.stopReason = "parent_restarted";
+          }
+          const result = record.result === undefined ? undefined : restorePersistedResult(record.result, thread);
+          if (record.result !== undefined && !result) continue;
+          const agent = rawThread.roleDefinition === undefined
+            ? restoreLegacyAgent(thread, result?.agentSource)
+            : restorePersistedAgent(rawThread.roleDefinition);
+          if (rawThread.roleDefinition !== undefined && !agent) continue;
+          records.set(thread.id, { thread, result, agent, thinking });
         } else if (record.event === "close" && typeof record.id === "string") {
           const previous = records.get(record.id);
           if (!previous) continue;
@@ -1703,7 +1831,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     return [...records.values()];
   };
 
-  const installRestoredThreads = (restored: Array<{ thread: ThreadSnapshot; result?: SubagentTaskResult }>): void => {
+  const installRestoredThreads = (restored: Array<{ thread: ThreadSnapshot; result?: SubagentTaskResult; agent?: AgentRole; thinking?: ThinkingLevel }>): void => {
     if (!restored.length) return;
     const ids = [...restored.map(({ thread }) => thread.id)];
     let idIndex = 0;
@@ -1727,17 +1855,20 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             attempt: thread.attempt,
             session: thread.session,
           } as any);
-        threadMetadata.set(created.id, {
-          displayName: thread.displayName ?? thread.role,
-          attempt: thread.attempt ?? 1,
-          session: thread.session ?? { id: `killeros-${safeSessionId(thread.id)}`, directory: "" },
-          persistentSession: Boolean(thread.session?.directory),
-        });
-        if (entry.result) saveResult(created.id, entry.result);
-        if (!(threads as any).hydrate) {
-          if (thread.state === "done") {
-            threads.begin(created.id);
-            threads.complete(created.id, { result: thread.result ?? entry.result?.output });
+        threadMetadata.set(created.id, {
+          displayName: thread.displayName ?? thread.role,
+          attempt: thread.attempt ?? 1,
+          session: thread.session ?? { id: `killeros-${safeSessionId(thread.id)}`, directory: "" },
+          persistentSession: Boolean(thread.session?.directory),
+          ...(entry.agent ? { agent: cloneAgentRole(entry.agent) } : {}),
+          ...(entry.thinking ? { thinking: entry.thinking } : {}),
+        });
+        if (entry.result) saveResult(created.id, entry.result);
+        if (!(threads as any).hydrate) {
+          if (thread.state === "done") {
+            threads.begin(created.id);
+            const output = lifecycleOutput(thread.result ?? entry.result?.output);
+            threads.complete(created.id, { result: output });
           } else if (thread.state === "failed") {
             threads.begin(created.id);
             threads.fail(created.id, { message: thread.failure?.message ?? entry.result?.errorMessage ?? "restored failure" });
@@ -1772,8 +1903,11 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     }
   };
 
-  const rememberEvictedThreads = (threadsToRemember: readonly SubagentThread[]): void => {
-    for (const thread of threadsToRemember) evictedThreadParents.set(thread.id, thread.parentId);
+  const rememberEvictedThreads = (threadsToRemember: readonly SubagentThread[]): void => {
+    for (const thread of threadsToRemember) {
+      evictedThreadParents.set(thread.id, thread.parentId);
+      threadMetadata.delete(thread.id);
+    }
     while (evictedThreadParents.size > maxClosedThreads) {
       const oldest = evictedThreadParents.keys().next().value;
       if (oldest === undefined) break;
@@ -1785,23 +1919,62 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     rememberEvictedThreads(threads.pruneClosed(maxClosedThreads));
   };
 
-  const resultBytes = (result: SubagentTaskResult): number => Buffer.byteLength([
-    result.task,
-    ...result.trace,
+  const resultBytes = (result: SubagentTaskResult): number => Buffer.byteLength([
+    result.task,
+    ...result.trace,
     result.stderr,
     result.output,
-    result.errorMessage ?? "",
-  ].join("\n"), "utf8");
-  const trimSavedResults = (): void => {
+    result.errorMessage ?? "",
+  ].join("\n"), "utf8");
+  const cleanupTerminalThread = async (
+    threadId: string,
+    resource: ThreadResource | undefined,
+    metadata: ThreadMetadata | undefined,
+  ): Promise<boolean> => {
+    const exits = resource
+      ? await Promise.all([...resource.handles].map((handle) => waitForConfirmedProcessExit(handle, limits.processExitWaitMs)))
+      : [];
+    if (!exits.every(Boolean)) {
+      for (const handle of resource?.handles ?? []) {
+        if (!handle.hasExited) {
+          void handle.exited.then(() => queueTerminalCleanup(threadId)).catch(() => {});
+        }
+      }
+      return false;
+    }
+    const directory = resource?.directory ?? metadata?.session.directory;
+    if ((resource?.persistent || metadata?.persistentSession) && directory) {
+      await rm(directory, { recursive: true, force: true });
+    }
+    if (threadResources.get(threadId) === resource) threadResources.delete(threadId);
+    return true;
+  };
+  const queueTerminalCleanup = (threadId: string): Promise<boolean> => {
+    const resource = threadResources.get(threadId);
+    const metadata = threadMetadata.get(threadId);
+    const generation = sessionGeneration;
+    const cleanup = terminalCleanupQueue.then(() => generation === sessionGeneration
+      ? cleanupTerminalThread(threadId, resource, metadata)
+      : false);
+    terminalCleanupQueue = cleanup.then(() => undefined, () => undefined);
+    return cleanup;
+  };
+  const waitForTerminalCleanup = async (): Promise<void> => {
+    await terminalCleanupQueue;
+  };
+  const trimSavedResults = (): void => {
     const candidates = threads.listAll()
       .filter((thread) => ["done", "failed", "stopped"].includes(thread.state))
       .sort((left, right) => left.timestamps.createdAt - right.timestamps.createdAt);
     const retainedBytes = (): number => [...savedResults.values()].reduce((total, result) => total + resultBytes(result), 0);
     while ((savedResults.size > limits.threadRetentionRecords || retainedBytes() > limits.threadRetentionBytes) && candidates.length) {
       const candidate = candidates.shift()!;
-      savedResults.delete(candidate.id);
-      const current = threads.inspect(candidate.id);
-      if (current && ["done", "failed", "stopped"].includes(current.state)) threads.close(candidate.id);
+      savedResults.delete(candidate.id);
+      const current = threads.inspect(candidate.id);
+      if (current && ["done", "failed", "stopped"].includes(current.state)) {
+        threads.close(candidate.id);
+        void queueTerminalCleanup(candidate.id).catch(() => {});
+      }
     }
     pruneClosedThreads();
   };
@@ -1896,27 +2069,28 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       }
     }
     if (runtime) runtime.traceCount = next.trace.length;
-    const handoff = effective.output ? { summary: effective.output } : undefined;
-    thread = threads.patch(threadId, { usage: threadUsage(effective.usage), result: effective.output || undefined, handoff });
-    const restartPending = runtime?.restarting === true && ["cancelled", "complete"].includes(next.status);
-    if (restartPending) return effective;
-    if (effective.status === "complete") {
-      threads.complete(threadId, { usage: threadUsage(effective.usage), result: effective.output || undefined, handoff });
-    } else if (effective.status === "failed") {
-      threads.fail(threadId, {
-        usage: threadUsage(effective.usage),
-        result: effective.output || undefined,
-        handoff,
-        message: effective.errorMessage ?? effective.terminationReason ?? "child failed",
-        code: effective.terminationReason,
-      });
-    } else if (effective.status === "cancelled" || effective.status === "limited") {
-      threads.stop(threadId, {
-        usage: threadUsage(effective.usage),
-        result: effective.output || undefined,
-        handoff,
-        reason: effective.terminationReason ?? (effective.status === "limited" ? "resource_limit" : "interrupted"),
-      });
+    const output = lifecycleOutput(effective.output);
+    const handoff = output ? { summary: output } : undefined;
+    thread = threads.patch(threadId, { usage: threadUsage(effective.usage), result: output, handoff });
+    const restartPending = runtime?.restarting === true && ["cancelled", "complete"].includes(next.status);
+    if (restartPending) return effective;
+    if (effective.status === "complete") {
+      threads.complete(threadId, { usage: threadUsage(effective.usage), result: output, handoff });
+    } else if (effective.status === "failed") {
+      threads.fail(threadId, {
+        usage: threadUsage(effective.usage),
+        result: output,
+        handoff,
+        message: effective.errorMessage ?? effective.terminationReason ?? "child failed",
+        code: effective.terminationReason,
+      });
+    } else if (effective.status === "cancelled" || effective.status === "limited") {
+      threads.stop(threadId, {
+        usage: threadUsage(effective.usage),
+        result: output,
+        handoff,
+        reason: effective.terminationReason ?? (effective.status === "limited" ? "resource_limit" : "interrupted"),
+      });
     }
     return effective;
   };
@@ -2097,16 +2271,16 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     });
   }
 
-  const toolDefinition: Parameters<ExtensionAPI["registerTool"]>[0] = {
-    name: "subagent",
-    label: "Subagents",
-    description: `Spawn and manage named child threads. Bundled roles: debugger, documenter, planner, reviewer, scout, security, tester, worker. Agent accepts a role name or an inline { name, description, access, tools } role. On spawn, message aliases task. Parallel tasks with write-capable roles use one shared slot; read-only batches run concurrently up to ${limits.maxReadConcurrency}. Write-capable tasks are serialized in the shared parent worktree. Use action list, inspect, wait, steer, interrupt, collect, resume, and close to manage child handoffs.`,
-    promptSnippet: "Delegate bounded specialist work to isolated KillerOS subagents",
-    promptGuidelines: [
-      "Use subagent for clearly separable specialist work; prefer read-only scout, planner, reviewer, or security roles before a writer.",
-      "Parallel tasks with write-capable roles use one shared slot because all children share the parent worktree.",
+  const toolDefinition: Parameters<ExtensionAPI["registerTool"]>[0] = {
+    name: "subagent",
+    label: "Subagents",
+    description: `Spawn and manage named child threads. A task-only spawn creates a generic read-only child; agent may name an optional custom role from an approved agents folder or provide an inline { name, description, access, tools } role. On spawn, message aliases task. Parallel tasks with write-capable roles use one shared slot; read-only batches run concurrently up to ${limits.maxReadConcurrency}. Write-capable tasks are serialized in the shared parent worktree. Use action list, inspect, wait, steer, interrupt, collect, resume, and close to manage child handoffs.`,
+    promptSnippet: "Delegate bounded work to isolated KillerOS subagents",
+    promptGuidelines: [
+      "Omit agent for a generic read-only child; use an approved custom role name or inline role when the task needs a specific prompt or write access.",
+      "Parallel tasks with write-capable roles use one shared slot because all children share the parent worktree.",
       "Every child can load relevant skills with read and can use web_search, source_check, fetch_content, and get_search_content for external research.",
-      "When the user names a model or thinking effort, pass model and thinking separately; use inherit when the active parent or role setting should decide.",
+      "Default model and thinking are inherited. If the user requires one model for the batch, pass model; set thinking only when requested, and use inherit to follow the selected role default or active parent.",
       "Keep completed and stopped threads inspectable until the parent explicitly closes them.",
     ],
     parameters: createSubagentParams(limits),
@@ -2230,10 +2404,8 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         if (thread.state === "queued" || thread.state === "active") {
           throw new Error(`Cannot close thread ${thread.id} from ${thread.state}`);
         }
-        const resource = threadResources.get(thread.id);
-        const exits = resource ? await Promise.all([...resource.handles].map((handle) => waitForConfirmedProcessExit(handle, limits.processExitWaitMs))) : [];
-        const exitConfirmed = exits.every(Boolean);
-        if (!exitConfirmed) {
+        const exitConfirmed = await queueTerminalCleanup(thread.id);
+        if (!exitConfirmed) {
           const current = savedResults.get(thread.id);
           if (current) {
             const failed = cloneResult(current);
@@ -2244,83 +2416,101 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             saveResult(thread.id, failed);
             recordSnapshot(thread, failed);
           }
-        } else {
-          const session = threadSession(thread, threadMetadata);
-          const directory = resource?.directory ?? session?.directory;
-          const expectedDirectory = childSessionPath(ctx, thread.id)?.directory;
-          const trustedRestoredDirectory = !resource && directory && expectedDirectory
-            && path.resolve(directory) === path.resolve(expectedDirectory);
-          if ((resource?.persistent || trustedRestoredDirectory) && directory) {
-            await rm(directory, { recursive: true, force: true });
-          }
-        }
-        threads.close(thread.id as SubagentThreadId);
-        if (exitConfirmed) threadResources.delete(thread.id);
-        savedResults.delete(thread.id);
+        }
+        threads.close(thread.id as SubagentThreadId);
+        savedResults.delete(thread.id);
         pruneClosedThreads();
         return actionResult(exitConfirmed
           ? `Closed ${threadDisplayName(thread, threadMetadata)} (${thread.id}). Heavy trace and handoff data were evicted; a tombstone remains inspectable.`
           : `Closed ${threadDisplayName(thread, threadMetadata)} (${thread.id}); process exit was not confirmed, so its session directory was retained.`, thread.id);
       }
 
-      let resumeTarget: ThreadSnapshot | undefined;
-      let resumePrompt: string | undefined;
-      const isResume = request.kind === "resume";
+      let resumeTarget: ThreadSnapshot | undefined;
+      let resumePrompt: string | undefined;
+      let resumeAgent: AgentRole | undefined;
+      const parentTools = activeParentTools(pi);
+      const isResume = request.kind === "resume";
       if (isResume) {
         const target = resolveOwnedThread(request.input.threadId, parentId);
         if (!target) throw new Error(`Unknown child thread ${JSON.stringify(request.input.threadId)}`);
         if (!terminalThread(target) || target.state === "closed") {
           throw new Error(`Cannot resume thread ${target.id} from ${target.state}`);
         }
-        if (savedResults.get(target.id)?.agentSource === "inline") {
+        resumeAgent = threadMetadata.get(target.id)?.agent;
+        if (!resumeAgent && target.role === "generic") resumeAgent = genericAgentRole(parentTools);
+        if (!resumeAgent && savedResults.get(target.id)?.agentSource === "inline") {
           throw new Error(`Cannot resume inline role ${JSON.stringify(target.role)}; inline roles are scoped to one spawn`);
         }
         resumePrompt = request.input.task;
         resumeTarget = target;
-      }
-      const spawnRequest = (isResume
-        ? { kind: "spawn-single", input: { agent: resumeTarget!.role, task: resumePrompt ?? resumeTarget!.prompt } }
-        : request) as Extract<NormalizedSubagentRequest, { kind: "spawn-single" | "spawn-parallel" | "spawn-chain" }>;
+      }
+      const spawnRequest = (isResume
+        ? {
+          kind: "spawn-single",
+          input: {
+            agent: resumeAgent ?? resumeTarget!.role,
+            task: resumePrompt ?? resumeTarget!.prompt,
+            model: resumeTarget!.model,
+            ...(threadMetadata.get(resumeTarget!.id)?.thinking
+              ? { thinking: threadMetadata.get(resumeTarget!.id)!.thinking }
+              : {}),
+          },
+        }
+        : request) as Extract<NormalizedSubagentRequest, { kind: "spawn-single" | "spawn-parallel" | "spawn-chain" }>;
       const params = spawnRequest.input;
-      const scope: AgentScope = params.agentScope ?? "user";
-      const hasParallel = spawnRequest.kind === "spawn-parallel";
-      const hasChain = spawnRequest.kind === "spawn-chain";
-      const writerConcurrencyOverride = hasParallel ? spawnRequest.input.writerConcurrency : undefined;
-
-      const discovery = discoverAgentRoles(ctx.cwd, scope, ctx.isProjectTrusted(), options);
-      const roles = new Map(discovery.agents.map((agent) => [agent.name, agent]));
+      const scope: AgentScope = params.agentScope ?? (isResume && resumeAgent?.source === "project" ? "project" : "user");
+      const hasParallel = spawnRequest.kind === "spawn-parallel";
+      const hasChain = spawnRequest.kind === "spawn-chain";
+      const writerConcurrencyOverride = hasParallel ? spawnRequest.input.writerConcurrency : undefined;
+
+      const discovery = discoverAgentRoles(ctx.cwd, scope, ctx.isProjectTrusted(), options);
+      const roles = new Map(discovery.agents.map((agent) => [agent.name, agent]));
       const rawInputs: TaskInput[] = spawnRequest.kind === "spawn-single"
         ? [{ agent: spawnRequest.input.agent, task: spawnRequest.input.task, ...(spawnRequest.input.name ? { name: spawnRequest.input.name } : {}) }]
         : spawnRequest.kind === "spawn-parallel" ? spawnRequest.input.tasks : spawnRequest.input.chain;
       const rolesForInputs = rawInputs.map((input) => {
-        if (typeof input.agent !== "string") {
-          const parentTools = new Set(pi.getActiveTools());
-          for (const tool of input.agent.tools) {
-            if (!parentTools.has(tool)) throw new Error(`Inline role ${JSON.stringify(input.agent.name)} tool ${JSON.stringify(tool)} is not active for the parent`);
-          }
-          return inlineAgentRole(input.agent);
+        if (isResume && resumeAgent && input.agent === resumeAgent) {
+          const role = cloneAgentRole(resumeAgent);
+          validateAgentTools(role, parentTools);
+          return role;
+        }
+        if (input.agent === undefined) return genericAgentRole(parentTools);
+        if (typeof input.agent !== "string") {
+          const role = inlineAgentRole(input.agent);
+          validateAgentTools(role, parentTools);
+          return role;
         }
         const selected = roles.get(input.agent);
         if (selected) return selected;
         const available = discovery.agents.map((agent) => `${agent.name} (${agent.source})`).join(", ") || "none";
-        throw new Error(`Unknown subagent ${JSON.stringify(input.agent)}. Available: ${available}`);
-      });
+        throw new Error(`Unknown custom subagent ${JSON.stringify(input.agent)}. Available: ${available}`);
+      });
+      rolesForInputs.forEach((role) => validateAgentTools(role, parentTools));
       const inputs: Array<Omit<TaskInput, "agent"> & { agent: string }> = rawInputs.map((input, index) => ({
         ...input,
         agent: rolesForInputs[index]!.name,
       }));
 
       const projectRoles = [...new Set(rolesForInputs.filter((role) => role.source === "project"))];
-      if (projectRoles.length) {
+      if (projectRoles.length) {
         if (!ctx.hasUI) throw new Error("Project-local subagents require interactive confirmation");
         const approved = await ctx.ui.confirm(
           "Run project-local subagents?",
           `Roles: ${projectRoles.map((role) => role.name).join(", ")}\nSources:\n${projectRoles.map((role) => role.filePath).join("\n")}\n\nThese trusted repository files control child prompts and tools.`,
         );
-        if (!approved) throw new Error("Project-local subagents were not approved");
-      }
-
-      const resolvedModels = rolesForInputs.map((role) => resolveAgentModel(role, ctx, params.model, params.thinking));
+        if (!approved) throw new Error("Project-local subagents were not approved");
+      }
+      const legacyRoles = [...new Set(rolesForInputs.filter((role) => role.source === "legacy"))];
+      if (legacyRoles.length) {
+        if (!ctx.hasUI) throw new Error("Legacy persisted subagents require interactive confirmation");
+        const approved = await ctx.ui.confirm(
+          "Resume legacy subagents?",
+          `Roles: ${legacyRoles.map((role) => role.name).join(", ")}\nThese saved roles came from an earlier KillerOS release and their original source is unavailable.`,
+        );
+        if (!approved) throw new Error("Legacy persisted subagents were not approved");
+      }
+
+      const resolvedModels = rolesForInputs.map((role) => resolveAgentModel(role, ctx, params.model, params.thinking));
 
       const mode: SubagentDetails["mode"] = hasParallel ? "parallel" : hasChain ? "chain" : "single";
       if (inputs.length > limits.maxTasks) throw new Error(`At most ${limits.maxTasks} subagent tasks are allowed`);
@@ -2350,9 +2540,16 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         throw new Error(`At most ${limits.maxTasks} child threads may be active at once`);
       }
 
-      const existingThreads = threads.listAll().filter((thread) => thread.parentId === parentId).map((thread) => threadView(thread, threadMetadata));
-      const allocatedNames = new Set<string>();
-      if (isResume) resumeTarget = resumeThread(resumeTarget!, resumePrompt);
+      const existingThreads = threads.listAll().filter((thread) => thread.parentId === parentId).map((thread) => threadView(thread, threadMetadata));
+      const allocatedNames = new Set<string>();
+      if (isResume) {
+        resumeTarget = resumeThread(resumeTarget!, resumePrompt);
+        const metadata = threadMetadata.get(resumeTarget.id);
+        if (metadata) {
+          metadata.agent = cloneAgentRole(rolesForInputs[0]!);
+          metadata.thinking = resolvedModels[0]!.thinking;
+        }
+      }
       const threadRecords = isResume
         ? [resumeTarget!]
         : inputs.map((input, index) => {
@@ -2375,7 +2572,14 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           session: { id: "killeros-pending", directory: path.join(os.tmpdir(), "killeros-subagent-pending") },
         } as any);
         const session = childSessionPath(ctx, thread.id) ?? { id: `killeros-${safeSessionId(thread.id)}`, directory: "" };
-        threadMetadata.set(thread.id, { displayName, attempt: 1, session, persistentSession: Boolean(session.directory) });
+        threadMetadata.set(thread.id, {
+          displayName,
+          attempt: 1,
+          session,
+          persistentSession: Boolean(session.directory),
+          agent: cloneAgentRole(rolesForInputs[index]!),
+          thinking: resolvedModels[index]!.thinking,
+        });
         recordSpawn(thread);
         return thread;
       });
@@ -2575,13 +2779,14 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           runtime.aggregate = limited;
           results[index] = cloneResult(limited);
           saveResult(threadId, limited);
-          if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
-            threads.stop(threadId, {
-              usage: threadUsage(limited.usage),
-              result: limited.output || undefined,
-              handoff: limited.output ? { summary: limited.output } : undefined,
-              reason,
-            });
+          if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
+            const output = lifecycleOutput(limited.output);
+            threads.stop(threadId, {
+              usage: threadUsage(limited.usage),
+              result: output,
+              handoff: output ? { summary: output } : undefined,
+              reason,
+            });
           }
           emit();
         };
@@ -2592,9 +2797,12 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             const remainingWallTimeMs = wallTimeMs === undefined ? undefined : wallTimeMs - (Date.now() - runtime.startedAt);
             const usedTraceBytes = (aggregate?.traceBytes ?? 0) + (aggregate?.traceTruncatedBytes ?? 0);
             const usedStderrBytes = aggregate?.stderrBytes ?? 0;
-            const usedOutputBytes = aggregate?.outputBytes ?? 0;
-            const usedTokens = aggregate?.usage.totalTokens ?? 0;
-            const usedCost = aggregate?.usage.cost.total ?? 0;
+            const usedOutputBytes = aggregate?.outputBytes ?? 0;
+            const usedTokens = aggregate?.usage.totalTokens ?? 0;
+            const usedCost = aggregate?.usage.cost.total ?? 0;
+            const usedTurns = aggregate?.usage.turns ?? 0;
+            const maxTurns = limits.maxTurns ?? limits.defaultMaxTurns;
+            const quotaTokens = limits.quotaTokens ?? limits.defaultQuotaTokens;
             if (remainingWallTimeMs !== undefined && remainingWallTimeMs <= 0) {
               stopForBudget("wall_time_limit", `Child thread exceeds ${wallTimeMs} ms`);
               break;
@@ -2611,10 +2819,14 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               stopForBudget("output_limit", `Child thread emits more than ${limits.taskOutputBytes} output bytes`);
               break;
             }
-            if (limits.quotaTokens !== undefined && usedTokens >= limits.quotaTokens) {
-              stopForBudget("quota_tokens", `Child thread exceeds ${limits.quotaTokens} tokens`);
-              break;
-            }
+            if (usedTurns >= maxTurns) {
+              stopForBudget("turn_limit", `Child thread reaches ${maxTurns} turns`);
+              break;
+            }
+            if (usedTokens >= quotaTokens) {
+              stopForBudget("quota_tokens", `Child thread reaches ${quotaTokens} tokens`);
+              break;
+            }
             if (limits.quotaUsd !== undefined && usedCost >= limits.quotaUsd) {
               stopForBudget("quota_cost", `Child thread exceeds $${limits.quotaUsd}`);
               break;
@@ -2638,10 +2850,11 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               limits: {
                 ...limits,
                 ...(limits.traceBytes === undefined ? {} : { traceBytes: limits.traceBytes - usedTraceBytes }),
-                ...(limits.stderrBytes === undefined ? {} : { stderrBytes: limits.stderrBytes - usedStderrBytes }),
-                ...(limits.taskOutputBytes === undefined ? {} : { taskOutputBytes: limits.taskOutputBytes - usedOutputBytes }),
-                ...(limits.quotaTokens === undefined ? {} : { quotaTokens: limits.quotaTokens - usedTokens }),
-                ...(limits.quotaUsd === undefined ? {} : { quotaUsd: limits.quotaUsd - usedCost }),
+                ...(limits.stderrBytes === undefined ? {} : { stderrBytes: limits.stderrBytes - usedStderrBytes }),
+                ...(limits.taskOutputBytes === undefined ? {} : { taskOutputBytes: limits.taskOutputBytes - usedOutputBytes }),
+                maxTurns: maxTurns - usedTurns,
+                quotaTokens: quotaTokens - usedTokens,
+                ...(limits.quotaUsd === undefined ? {} : { quotaUsd: limits.quotaUsd - usedCost }),
               },
               timeoutMs: remainingWallTimeMs,
               onHandle: (handle) => {
@@ -2676,14 +2889,15 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
                 runtime.aggregate = cancelled;
                 results[index] = cloneResult(cancelled);
                 if (runtime.sessionGeneration === sessionGeneration) {
-                  saveResult(threadId, cancelled);
-                  if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
-                    threads.stop(threadId, {
-                      usage: threadUsage(cancelled.usage),
-                      result: cancelled.output || undefined,
-                      handoff: cancelled.output ? { summary: cancelled.output } : undefined,
-                      reason: cancelled.terminationReason,
-                    });
+                  saveResult(threadId, cancelled);
+                  if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
+                    const output = lifecycleOutput(cancelled.output);
+                    threads.stop(threadId, {
+                      usage: threadUsage(cancelled.usage),
+                      result: output,
+                      handoff: output ? { summary: output } : undefined,
+                      reason: cancelled.terminationReason,
+                    });
                   }
                   emit();
                 }
@@ -2697,13 +2911,14 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               runtime.aggregate = unconfirmed;
               results[index] = cloneResult(unconfirmed);
               if (runtime.sessionGeneration === sessionGeneration) saveResult(threadId, unconfirmed);
-              if (runtime.sessionGeneration === sessionGeneration && !threads.isDisposed && threads.inspect(threadId)?.state === "active") {
-                threads.fail(threadId, {
-                  usage: threadUsage(unconfirmed.usage),
-                  result: unconfirmed.output || undefined,
-                  handoff: unconfirmed.output ? { summary: unconfirmed.output } : undefined,
-                  message,
-                  code: "process_exit_unconfirmed",
+              if (runtime.sessionGeneration === sessionGeneration && !threads.isDisposed && threads.inspect(threadId)?.state === "active") {
+                const output = lifecycleOutput(unconfirmed.output);
+                threads.fail(threadId, {
+                  usage: threadUsage(unconfirmed.usage),
+                  result: output,
+                  handoff: output ? { summary: output } : undefined,
+                  message,
+                  code: "process_exit_unconfirmed",
                 });
               }
               emit();
@@ -2711,14 +2926,15 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             }
             if (runtime.sessionGeneration !== sessionGeneration || controller.signal.aborted || threads.isDisposed) break;
             const steering = runtime.steering.splice(0);
-            runtime.restarting = false;
-            runtime.requestedReason = undefined;
-            if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
-              threads.patch(threadId, {
-                usage: threadUsage(runtime.aggregate.usage),
-                result: runtime.aggregate.output || undefined,
-                handoff: runtime.aggregate.output ? { summary: runtime.aggregate.output } : undefined,
-              });
+            runtime.restarting = false;
+            runtime.requestedReason = undefined;
+            if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
+              const output = lifecycleOutput(runtime.aggregate.output);
+              threads.patch(threadId, {
+                usage: threadUsage(runtime.aggregate.usage),
+                result: output,
+                handoff: output ? { summary: output } : undefined,
+              });
             }
             if (steeredTaskWouldExceedLimit(task, steering, limits.taskCharacters)) {
               const failed = cloneResult(runtime.aggregate ?? results[index]!);
@@ -2727,15 +2943,16 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               failed.errorMessage = `Expanded task plus steering exceeds ${limits.taskCharacters} characters`;
               runtime.aggregate = failed;
               results[index] = cloneResult(failed);
-              if (runtime.sessionGeneration === sessionGeneration) {
-                saveResult(threadId, failed);
-                if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
-                  threads.fail(threadId, {
-                    usage: threadUsage(failed.usage),
-                    result: failed.output || undefined,
-                    handoff: failed.output ? { summary: failed.output } : undefined,
-                    message: failed.errorMessage,
-                    code: failed.terminationReason,
+              if (runtime.sessionGeneration === sessionGeneration) {
+                saveResult(threadId, failed);
+                if (!threads.isDisposed && threads.inspect(threadId)?.state === "active") {
+                  const output = lifecycleOutput(failed.output);
+                  threads.fail(threadId, {
+                    usage: threadUsage(failed.usage),
+                    result: output,
+                    handoff: output ? { summary: output } : undefined,
+                    message: failed.errorMessage,
+                    code: failed.terminationReason,
                   });
                 }
                 emit();
@@ -2765,14 +2982,15 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             if (runtime.sessionGeneration === sessionGeneration) {
               saveResult(threadId, unconfirmed);
               const current = threads.inspect(threadId);
-              if (current?.state === "active") {
-                if (unconfirmed.status === "failed") {
-                  threads.fail(threadId, {
-                    usage: threadUsage(unconfirmed.usage),
-                    result: unconfirmed.output || undefined,
-                    handoff: unconfirmed.output ? { summary: unconfirmed.output } : undefined,
-                    message: unconfirmed.errorMessage ?? "Child process exit was not confirmed before cleanup",
-                    code: unconfirmed.terminationReason,
+              if (current?.state === "active") {
+                if (unconfirmed.status === "failed") {
+                  const output = lifecycleOutput(unconfirmed.output);
+                  threads.fail(threadId, {
+                    usage: threadUsage(unconfirmed.usage),
+                    result: output,
+                    handoff: output ? { summary: output } : undefined,
+                    message: unconfirmed.errorMessage ?? "Child process exit was not confirmed before cleanup",
+                    code: unconfirmed.terminationReason,
                   });
                 } else {
                   threads.stop(threadId, { reason: unconfirmed.terminationReason ?? "process_exit_unconfirmed" });
@@ -2780,14 +2998,15 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               }
               emit();
             }
-          } else if (!persistentSession) {
-            try {
-              await rm(sessionDirectory, { recursive: true, force: true });
-            } catch {
-              // Temporary child session cleanup is best effort after process termination.
-            }
-          }
-        }
+          } else if (!persistentSession) {
+            try {
+              await rm(sessionDirectory, { recursive: true, force: true });
+            } catch {
+              // Temporary child session cleanup is best effort after process termination.
+            }
+          }
+          if (allExited && runtime.sessionGeneration === sessionGeneration) threadResources.delete(threadId);
+        }
         emit();
       };
 
@@ -2843,11 +3062,12 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           } finally {
             settleQueued("parallel_stopped");
           }
-        } else {
-          await runAt(0, inputs[0]!.task);
-        }
-
-        const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir, isResume ? resumeTarget?.id : undefined);
+        } else {
+          await runAt(0, inputs[0]!.task);
+        }
+
+        await waitForTerminalCleanup();
+        const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir, isResume ? resumeTarget?.id : undefined);
         const currentResults = results.map(cloneResult);
         const details: SubagentDetails = { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
         const toolContent = buildToolContent(mode, details.results, limits.toolOutputBytes);
@@ -2876,9 +3096,10 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
 
       const queuedBoard = detailsFor(parentId, mode, scope, discovery.projectAgentsDir, isResume ? resumeTarget?.id : undefined);
       const queuedResults = results.map(cloneResult);
-      const queuedDetails: SubagentDetails = {
-        ...queuedBoard,
-        executionNote,
+      const queuedDetails: SubagentDetails = {
+        ...queuedBoard,
+        backgroundStarted: true,
+        executionNote,
         results: queuedResults,
         aggregateUsage: aggregateUsage(queuedResults),
       };
@@ -2954,17 +3175,28 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `parallel ${spawnRequest.input.tasks.length} · ${schedule}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
       }
       if (spawnRequest.kind === "spawn-chain") return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `chain ${spawnRequest.input.chain.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
-      const agentName = typeof spawnRequest.input.agent === "string" ? spawnRequest.input.agent : spawnRequest.input.agent.name;
+      const agentName = spawnRequest.input.agent === undefined
+        ? "generic"
+        : typeof spawnRequest.input.agent === "string" ? spawnRequest.input.agent : spawnRequest.input.agent.name;
       return new Text(`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", agentName)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
     },
 
     renderResult(result, { expanded }, theme) {
       const details = result.details as SubagentDetails | undefined;
-      if (!details?.results.length) {
-        const first = result.content[0];
-        return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
-      }
-      const board = formatThreadBoard({
+      if (!details?.results.length) {
+        const first = result.content[0];
+        return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
+      }
+      if (details.backgroundStarted) {
+        const lines = [
+          theme.fg("toolTitle", theme.bold(`Started in background (${details.results.length})`)),
+          ...details.results.map((task) => `${theme.fg("toolTitle", theme.bold(task.name ?? task.agent))}${theme.fg("dim", ` · role ${task.agent} · ${task.id} · attempt ${task.attempt ?? 1}`)}`),
+        ];
+        if (details.executionNote) lines.push(theme.fg("dim", details.executionNote));
+        lines.push(theme.fg("dim", "Live status appears below while child threads run."));
+        return new Text(lines.join("\n"), 0, 0);
+      }
+      const board = formatThreadBoard({
         title: `Subagents · ${details.mode}`,
         threads: details.results.map(threadBoardRecord),
         selectedThreadId: details.selectedThreadId,