killeros 1.4.5 → 1.4.6

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to KillerOS are documented here.
 
+## [1.4.6] - 2026-08-01
+
+### Fixed
+
+- Made the registered task schema use the same ten-task limit as runtime validation.
+- Kept one isolated Pi session ID and session directory across steering restarts so a child retains its conversation.
+- Bound retained trace, stderr, and returned text, and spooled large JSONL lines to temporary storage without stopping the child or reporting a retention cutoff as `limited`.
+- Kept explicit embedding resource guards and user stops visible as terminal states.
+
 ## [1.4.5] - 2026-08-01
 
 ### Fixed

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-  pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.5
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.6
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -103,7 +103,7 @@ The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `
 {"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
 ```
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as ephemeral `pi --mode json -p --no-session` processes with explicit local tools plus `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output quota. The parent still limits each request to eight tasks and four parallel readers and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Esc cancellation terminates active children and escalates after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output execution quota. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks and four parallel readers and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Esc cancellation terminates active children and escalates after five seconds.
 
 ### Thread lifecycle
 
@@ -163,7 +163,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For release `1.4.5`, publish after the validation checks pass:
+For release `1.4.6`, publish after the validation checks pass:
 
 ```bash
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [

package/subagent-process.ts

@@ -1,11 +1,19 @@
 import { spawn } from "node:child_process";
-import { statSync } from "node:fs";
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 export const SUBAGENT_PROCESS_LIMITS = {
   killGraceMs: 5_000,
 } as const;
 
+export const SUBAGENT_PROCESS_RETENTION = {
+  jsonlMemoryBytes: 1 * 1024 * 1024,
+  traceBytes: 2 * 1024 * 1024,
+  stderrBytes: 64 * 1024,
+  outputBytes: 1 * 1024 * 1024,
+} as const;
+
 export type SubagentProcessStatus = "running" | "complete" | "failed" | "cancelled" | "limited";
 
 export interface SubagentProcessUsage {
@@ -56,11 +64,12 @@ export interface SubagentProcessChild {
 }
 
 export interface SubagentProcessOptions {
-  /** Exact Pi arguments. Include `--mode json` and `--no-session`. */
+  /** Exact Pi arguments. Include `--mode json` and either `--no-session` or an isolated session id and directory. */
   args: readonly string[];
   cwd: string;
   signal?: AbortSignal;
   limits?: Partial<SubagentProcessLimits>;
+  retention?: Partial<SubagentProcessRetention>;
   environment?: NodeJS.ProcessEnv;
   onUpdate?: (result: Readonly<SubagentProcessResult>) => void;
   /** Test or embed hook. It receives the exact Pi arguments supplied above. */
@@ -78,6 +87,13 @@ export interface SubagentProcessLimits {
   killGraceMs: number;
 }
 
+export interface SubagentProcessRetention {
+  jsonlMemoryBytes: number;
+  traceBytes: number;
+  stderrBytes: number;
+  outputBytes: number;
+}
+
 export interface SubagentProcessHandle {
   readonly pid: number | undefined;
   readonly result: Promise<SubagentProcessResult>;
@@ -188,6 +204,13 @@ function hasJsonMode(args: readonly string[]): boolean {
   return args.some((arg, index) => arg === "--mode=json" || arg === "--mode" && args[index + 1] === "json");
 }
 
+function hasIsolatedSession(args: readonly string[]): boolean {
+  const sessionId = args.indexOf("--session-id");
+  const sessionDir = args.indexOf("--session-dir");
+  return sessionId >= 0 && typeof args[sessionId + 1] === "string"
+    && sessionDir >= 0 && typeof args[sessionDir + 1] === "string";
+}
+
 function normalizeLimits(overrides: Partial<SubagentProcessLimits> | undefined): SubagentProcessLimits {
   const limits = { ...SUBAGENT_PROCESS_LIMITS, ...overrides };
   for (const name of ["wallTimeMs", "jsonlLineBytes", "traceBytes", "stderrBytes", "outputBytes", "killGraceMs"] as const) {
@@ -201,6 +224,15 @@ function normalizeLimits(overrides: Partial<SubagentProcessLimits> | undefined):
   return limits;
 }
 
+function normalizeRetention(overrides: Partial<SubagentProcessRetention> | undefined): SubagentProcessRetention {
+  const retention = { ...SUBAGENT_PROCESS_RETENTION, ...overrides };
+  for (const name of ["jsonlMemoryBytes", "traceBytes", "stderrBytes", "outputBytes"] as const) {
+    const value = retention[name];
+    if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+  }
+  return retention;
+}
+
 function getPiInvocation(args: string[]): { command: string; args: string[] } {
   const currentScript = process.argv[1];
   const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
@@ -268,8 +300,11 @@ function terminateProcess(child: SubagentProcessChild, force: boolean): void {
 export function runSubagentProcess(options: SubagentProcessOptions): SubagentProcessHandle {
   const args = [...options.args];
   if (!hasJsonMode(args)) throw new Error("Subagent Pi arguments must include --mode json");
-  if (!args.includes("--no-session")) throw new Error("Subagent Pi arguments must include --no-session");
+  if (!args.includes("--no-session") && !hasIsolatedSession(args)) {
+    throw new Error("Subagent Pi arguments must include --no-session or an isolated --session-id and --session-dir");
+  }
   const limits = normalizeLimits(options.limits);
+  const retention = normalizeRetention(options.retention);
   const startedAt = Date.now();
   const state: SubagentProcessResult = {
     status: "running",
@@ -295,6 +330,8 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   let requestedReason: string | undefined;
   let stdoutLine = Buffer.alloc(0);
   let stdoutLineBytes = 0;
+  let stdoutLineSpoolDirectory: string | undefined;
+  let stdoutLineSpoolDescriptor: number | undefined;
   let stderr = Buffer.alloc(0);
   let outputBytesSeen = 0;
   let forceTimer: NodeJS.Timeout | undefined;
@@ -303,16 +340,53 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   let resolveResult!: (result: SubagentProcessResult) => void;
   const result = new Promise<SubagentProcessResult>((resolve) => { resolveResult = resolve; });
 
+  const clearStdoutLine = (): void => {
+    if (stdoutLineSpoolDescriptor !== undefined) {
+      try {
+        closeSync(stdoutLineSpoolDescriptor);
+      } catch (error) {
+        state.errorMessage ??= `Could not close child JSONL spool: ${error instanceof Error ? error.message : String(error)}`;
+      }
+      stdoutLineSpoolDescriptor = undefined;
+    }
+    if (stdoutLineSpoolDirectory) {
+      try {
+        rmSync(stdoutLineSpoolDirectory, { recursive: true, force: true });
+      } catch (error) {
+        state.errorMessage ??= `Could not remove child JSONL spool: ${error instanceof Error ? error.message : String(error)}`;
+      }
+      stdoutLineSpoolDirectory = undefined;
+    }
+    stdoutLine = Buffer.alloc(0);
+    stdoutLineBytes = 0;
+  };
+  const readStdoutLine = (): string => {
+    if (stdoutLineSpoolDirectory) {
+      const filePath = path.join(stdoutLineSpoolDirectory, "line.jsonl");
+      try {
+        if (stdoutLineSpoolDescriptor !== undefined) {
+          closeSync(stdoutLineSpoolDescriptor);
+          stdoutLineSpoolDescriptor = undefined;
+        }
+        return readFileSync(filePath, "utf8");
+      } catch (error) {
+        state.errorMessage ??= `Could not read child JSONL spool: ${error instanceof Error ? error.message : String(error)}`;
+        return "";
+      } finally {
+        clearStdoutLine();
+      }
+    }
+    const line = stdoutLine.toString("utf8", 0, stdoutLineBytes);
+    clearStdoutLine();
+    return line;
+  };
+
   const publish = (): void => options.onUpdate?.(cloneResult(state));
   const finish = (code: number | null): void => {
     if (closed || finishing) return;
     finishing = true;
-    if (stdoutLineBytes && !requestedStatus) {
-      const finalLine = stdoutLine.toString("utf8", 0, stdoutLineBytes);
-      stdoutLine = Buffer.alloc(0);
-      stdoutLineBytes = 0;
-      processLine(finalLine);
-    }
+    if (stdoutLineBytes && !requestedStatus) processLine(readStdoutLine());
+    else clearStdoutLine();
     closed = true;
     if (forceTimer) clearTimeout(forceTimer);
     if (settleTimer) clearTimeout(settleTimer);
@@ -383,17 +457,20 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       } else if (limits.quotaUsd !== undefined && state.usage.cost.total > limits.quotaUsd) {
         requestTermination("limited", "quota_cost", `Child cost exceeds $${limits.quotaUsd}`);
       }
-      if (appendTrace(state, traceMessage(message), limits.traceBytes)) {
+      const traceTruncatedBefore = state.traceTruncatedBytes;
+      appendTrace(state, traceMessage(message), Math.min(retention.traceBytes, limits.traceBytes ?? retention.traceBytes));
+      if (limits.traceBytes !== undefined && state.traceTruncatedBytes > traceTruncatedBefore && state.traceBytes >= limits.traceBytes) {
         requestTermination("limited", "trace_limit", `Retained child trace exceeds ${limits.traceBytes} bytes`);
       }
       const output = textContent(message);
       if (output) {
-        const capped = truncateUtf8(output, limits.outputBytes ?? Buffer.byteLength(output, "utf8"));
+        const outputLimit = Math.min(retention.outputBytes, limits.outputBytes ?? retention.outputBytes);
+        const capped = truncateUtf8(output, outputLimit);
         state.output = capped.text;
         state.outputTruncatedBytes = capped.omittedBytes;
         outputBytesSeen += Buffer.byteLength(output, "utf8");
         state.outputBytes = outputBytesSeen;
-        state.outputTruncatedBytes = Math.max(state.outputTruncatedBytes, limits.outputBytes === undefined ? 0 : outputBytesSeen - limits.outputBytes);
+        state.outputTruncatedBytes = Math.max(state.outputTruncatedBytes, outputBytesSeen - (limits.outputBytes ?? retention.outputBytes));
         if (limits.outputBytes !== undefined && outputBytesSeen > limits.outputBytes) requestTermination("limited", "output_limit", `Child output exceeds ${limits.outputBytes} bytes`);
       }
       if (typeof message.model === "string") state.model = message.provider ? `${message.provider}/${message.model}` : message.model;
@@ -406,7 +483,9 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       publish();
     } else if (event?.type === "tool_result_end" && event.message) {
       const name = typeof event.message.toolName === "string" ? event.message.toolName : "tool";
-      if (appendTrace(state, [`${name} result${event.message.isError ? " (error)" : ""}`], limits.traceBytes)) {
+      const traceTruncatedBefore = state.traceTruncatedBytes;
+      appendTrace(state, [`${name} result${event.message.isError ? " (error)" : ""}`], Math.min(retention.traceBytes, limits.traceBytes ?? retention.traceBytes));
+      if (limits.traceBytes !== undefined && state.traceTruncatedBytes > traceTruncatedBefore && state.traceBytes >= limits.traceBytes) {
         requestTermination("limited", "trace_limit", `Retained child trace exceeds ${limits.traceBytes} bytes`);
       }
       publish();
@@ -418,6 +497,22 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       requestTermination("limited", "jsonl_line_limit", `Child JSONL line exceeds ${limits.jsonlLineBytes} bytes`);
       return false;
     }
+    if (nextBytes > retention.jsonlMemoryBytes) {
+      try {
+        if (stdoutLineSpoolDescriptor === undefined) {
+          stdoutLineSpoolDirectory = mkdtempSync(path.join(os.tmpdir(), "killeros-jsonl-"));
+          stdoutLineSpoolDescriptor = openSync(path.join(stdoutLineSpoolDirectory, "line.jsonl"), "w");
+          if (stdoutLineBytes) writeSync(stdoutLineSpoolDescriptor, stdoutLine);
+          stdoutLine = Buffer.alloc(0);
+        }
+        if (fragment.length) writeSync(stdoutLineSpoolDescriptor, fragment);
+      } catch (error) {
+        requestTermination("failed", "jsonl_spool_error", `Could not spool child JSONL: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+      }
+      stdoutLineBytes = nextBytes;
+      return true;
+    }
     if (nextBytes > stdoutLine.length) {
       const nextCapacity = limits.jsonlLineBytes === undefined
         ? Math.max(nextBytes, stdoutLine.length * 2, 4_096)
@@ -449,21 +544,19 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
           const end = newline < 0 ? buffer.length : newline;
           if (!appendStdout(buffer.subarray(offset, end))) return;
           if (newline < 0) return;
-          const line = stdoutLine.toString("utf8", 0, stdoutLineBytes);
-          stdoutLine = Buffer.alloc(0);
-          stdoutLineBytes = 0;
-          processLine(line);
+          processLine(readStdoutLine());
           offset = newline + 1;
         }
       });
       child.stderr.on("data", (chunk: Buffer | string) => {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        const retained = limits.stderrBytes === undefined
-          ? buffer
-          : buffer.subarray(0, Math.max(0, limits.stderrBytes - stderr.length));
+        const stderrLimit = Math.min(retention.stderrBytes, limits.stderrBytes ?? retention.stderrBytes);
+        const retained = buffer.subarray(0, Math.max(0, stderrLimit - stderr.length));
         if (retained.length) stderr = Buffer.concat([stderr, retained]);
         state.stderrTruncatedBytes += buffer.length - retained.length;
-        if (buffer.length > retained.length) requestTermination("limited", "stderr_limit", `Child stderr exceeds ${limits.stderrBytes} bytes`);
+        if (limits.stderrBytes !== undefined && stderr.length + state.stderrTruncatedBytes > limits.stderrBytes) {
+          requestTermination("limited", "stderr_limit", `Child stderr exceeds ${limits.stderrBytes} bytes`);
+        }
       });
       child.on("error", (error) => requestTermination("failed", "spawn_error", error.message));
       child.once("close", finish);

package/subagents.ts

@@ -20,9 +20,12 @@ import { runSubagentProcess, type SubagentProcessHandle, type SubagentProcessRes
 import { formatThreadBoard, formatThreadInspection, type ThreadRecord as ThreadBoardRecord } from "./subagent-ui.ts";
 
 export const SUBAGENT_LIMITS = {
-  maxTasks: 8,
+  maxTasks: 10,
   maxReadConcurrency: 4,
   toolOutputBytes: 50 * 1024,
+  traceRetentionBytes: 8 * 1024 * 1024,
+  stderrRetentionBytes: 1 * 1024 * 1024,
+  taskOutputRetentionBytes: 1 * 1024 * 1024,
   roleFileBytes: 64 * 1024,
   taskCharacters: 20_000,
   killGraceMs: 5_000,
@@ -511,7 +514,12 @@ function cloneResult(result: SubagentTaskResult): SubagentTaskResult {
   };
 }
 
-function mergeTaskResults(previous: SubagentTaskResult | undefined, next: SubagentTaskResult, maxTraceBytes?: number): SubagentTaskResult {
+function mergeTaskResults(
+  previous: SubagentTaskResult | undefined,
+  next: SubagentTaskResult,
+  maxTraceBytes?: number,
+  maxStderrBytes?: number,
+): SubagentTaskResult {
   if (!previous) return cloneResult(next);
   const merged = cloneResult(next);
   const trace: string[] = [];
@@ -527,9 +535,11 @@ function mergeTaskResults(previous: SubagentTaskResult | undefined, next: Subage
   merged.trace = trace;
   merged.traceBytes = traceBytes;
   merged.traceTruncatedBytes = traceTruncatedBytes;
-  merged.stderr = [previous.stderr, next.stderr].filter(Boolean).join("\n");
+  const stderr = [previous.stderr, next.stderr].filter(Boolean).join("\n");
+  const retainedStderr = truncateUtf8(stderr, maxStderrBytes === undefined ? Buffer.byteLength(stderr, "utf8") : maxStderrBytes);
+  merged.stderr = retainedStderr.text;
   merged.stderrBytes = previous.stderrBytes + next.stderrBytes;
-  merged.stderrTruncatedBytes = previous.stderrTruncatedBytes + next.stderrTruncatedBytes;
+  merged.stderrTruncatedBytes = previous.stderrTruncatedBytes + next.stderrTruncatedBytes + retainedStderr.omittedBytes;
   merged.output = next.output || previous.output;
   merged.outputBytes = previous.outputBytes + next.outputBytes;
   merged.outputTruncatedBytes = previous.outputTruncatedBytes + next.outputTruncatedBytes;
@@ -565,6 +575,8 @@ interface RunTaskOptions {
   webExtension?: string;
   projectTrusted: boolean;
   limits: SubagentLimits;
+  sessionDirectory: string;
+  sessionId: string;
   timeoutMs?: number;
   onChange: (result: SubagentTaskResult) => void;
   onHandle?: (handle: SubagentProcessHandle) => void;
@@ -631,7 +643,8 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
     const args = [
       "--mode", "json",
       "-p",
-      "--no-session",
+      "--session-dir", options.sessionDirectory,
+      "--session-id", options.sessionId,
       "--no-extensions",
       "--extension", options.webExtension ?? SUBAGENT_WEB_EXTENSION,
       "--no-prompt-templates",
@@ -657,6 +670,11 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
         ...(limits.quotaUsd === undefined ? {} : { quotaUsd: limits.quotaUsd }),
         killGraceMs: limits.killGraceMs,
       },
+      retention: {
+        traceBytes: limits.traceRetentionBytes,
+        stderrBytes: limits.stderrRetentionBytes,
+        outputBytes: limits.taskOutputRetentionBytes,
+      },
       onUpdate: (next) => applyProcessResult(result, next, startedAt, options.onChange),
     });
     options.onHandle?.(handle);
@@ -694,35 +712,35 @@ async function mapReadTasks<T>(items: T[], concurrency: number, run: (item: T, i
   await Promise.all(workers);
 }
 
-const TaskSchema = Type.Object({
-  agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
-  task: Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Bounded task for the role" }),
-});
-
-const ChainTaskSchema = Type.Object({
-  agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
-  task: Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Task with optional {previous} handoff placeholder" }),
-});
-
-const SubagentParams = Type.Object({
-  action: Type.Optional(StringEnum(["spawn", "list", "inspect", "steer", "interrupt", "collect", "close"] as const, {
-    default: "spawn",
-    description: "Thread lifecycle action",
-  })),
-  threadId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Stable child thread ID" })),
-  message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Bounded steering message" })),
-  all: Type.Optional(Type.Boolean({ description: "Interrupt every active child thread" })),
-  agent: Type.Optional(Type.String({ minLength: 1, maxLength: 64, description: "Agent role for single mode" })),
-  task: Type.Optional(Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Task for single mode" })),
-  tasks: Type.Optional(Type.Array(TaskSchema, { minItems: 1, maxItems: SUBAGENT_LIMITS.maxTasks, description: "Parallel role tasks" })),
-  chain: Type.Optional(Type.Array(ChainTaskSchema, { minItems: 1, maxItems: SUBAGENT_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",
-  })),
-});
+function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "taskCharacters">) {
+  const taskSchema = Type.Object({
+    agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
+    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Bounded task for the role" }),
+  });
+  const chainTaskSchema = Type.Object({
+    agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
+    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task with optional {previous} handoff placeholder" }),
+  });
+  return Type.Object({
+    action: Type.Optional(StringEnum(["spawn", "list", "inspect", "steer", "interrupt", "collect", "close"] as const, {
+      default: "spawn",
+      description: "Thread lifecycle action",
+    })),
+    threadId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Stable child thread ID" })),
+    message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Bounded steering message" })),
+    all: Type.Optional(Type.Boolean({ description: "Interrupt every active child thread" })),
+    agent: Type.Optional(Type.String({ minLength: 1, maxLength: 64, description: "Agent role for single mode" })),
+    task: Type.Optional(Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task for single mode" })),
+    tasks: Type.Optional(Type.Array(taskSchema, { minItems: 1, maxItems: limits.maxTasks, description: "Parallel role tasks" })),
+    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",
+    })),
+  });
+}
 
 type TaskInput = { agent: string; task: string };
 
@@ -739,16 +757,12 @@ function clipCharacters(text: string, maxCharacters: number, fromEnd = false): s
   return (fromEnd ? characters.slice(-maxCharacters) : characters.slice(0, maxCharacters)).join("");
 }
 
-function buildSteeredTask(task: string, steering: readonly string[], previousOutput: string | undefined, maxCharacters: number): string {
+function buildSteeredTask(task: string, steering: readonly string[], maxCharacters: number): string {
   const steeringLabel = "\n\nParent steering:\n";
   const steeringText = clipCharacters(steering.join("\n"), Math.max(0, maxCharacters - [...steeringLabel].length), true);
-  const previousLabel = previousOutput ? "\n\nPrevious child handoff:\n" : "";
-  const required = [...steeringLabel, ...steeringText, ...previousLabel].length;
+  const required = [...steeringLabel, ...steeringText].length;
   const taskText = clipCharacters(task, Math.max(0, maxCharacters - required));
-  const previousText = previousOutput
-    ? clipCharacters(previousOutput, Math.max(0, maxCharacters - [...taskText, ...steeringLabel, ...steeringText, ...previousLabel].length))
-    : "";
-  return `${taskText}${previousText ? `${previousLabel}${previousText}` : ""}${steeringLabel}${steeringText}`;
+  return `${taskText}${steeringLabel}${steeringText}`;
 }
 
 function formatUsage(usage: SubagentUsage): string {
@@ -953,7 +967,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   };
 
   const syncThread = (threadId: SubagentThreadId, next: SubagentTaskResult, runtime?: ActiveThreadRuntime): SubagentTaskResult => {
-    const effective = mergeTaskResults(runtime?.aggregate, next, limits.traceBytes);
+    const effective = mergeTaskResults(runtime?.aggregate, next, limits.traceRetentionBytes, limits.stderrRetentionBytes);
     if (runtime?.requestedReason && next.status === "cancelled") effective.terminationReason = runtime.requestedReason;
     savedResults.set(threadId, cloneResult(effective));
     let thread = threads.inspect(threadId);
@@ -966,9 +980,9 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     const from = runtime?.traceCount ?? 0;
     let retainedTraceBytes = thread.trace.reduce((total, entry) => total + Buffer.byteLength(entry.message ?? "", "utf8"), 0);
     for (const entry of next.trace.slice(from)) {
-      const retained = truncateUtf8(entry, limits.traceBytes === undefined
+      const retained = truncateUtf8(entry, limits.traceRetentionBytes === undefined
         ? Buffer.byteLength(entry, "utf8")
-        : Math.max(0, limits.traceBytes - retainedTraceBytes));
+        : Math.max(0, limits.traceRetentionBytes - retainedTraceBytes));
       if (retained.text) {
         threads.trace(threadId, { kind: "child", message: retained.text });
         retainedTraceBytes += Buffer.byteLength(retained.text, "utf8");
@@ -1015,7 +1029,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   pi.registerTool({
     name: "subagent",
     label: "Subagents",
-    description: "Spawn and manage named child threads. Children finish naturally; time, output, trace, stderr, quota, task count, and concurrency are the hard edges. Use action list, inspect, steer, interrupt, collect, and close to manage active and completed handoffs.",
+    description: "Spawn and manage named child threads. Children finish naturally; explicit execution guards, task count, and concurrency are the hard edges. Retention only bounds stored detail. Use action list, inspect, steer, interrupt, collect, and close to manage active and completed 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.",
@@ -1024,7 +1038,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       "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.",
       "Keep completed and stopped threads inspectable until the parent explicitly closes them.",
     ],
-    parameters: SubagentParams,
+    parameters: createSubagentParams(limits),
     executionMode: "parallel",
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -1214,6 +1228,23 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           emit();
           return;
         }
+        let sessionDirectory: string;
+        try {
+          sessionDirectory = await mkdtemp(path.join(os.tmpdir(), "killeros-subagent-session-"));
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          results[index] = {
+            ...results[index]!,
+            status: "failed",
+            terminationReason: "session_error",
+            errorMessage: message,
+          };
+          threads.fail(threadId, { message, code: "session_error" });
+          savedResults.set(threadId, cloneResult(results[index]!));
+          emit();
+          return;
+        }
+        const sessionId = `killeros-${threadId.replace(/[^A-Za-z0-9_.-]/gu, "_")}`;
         const controller = new AbortController();
         const abortParent = (): void => controller.abort();
         if (signal) {
@@ -1224,7 +1255,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         activeRuntimes.set(threadId, runtime);
         const agent = roles.get(input.agent)!;
         const queuedSteering = initialThread.steering.map((entry) => entry.message);
-        let currentTask = queuedSteering.length ? buildSteeredTask(task, queuedSteering, undefined, limits.taskCharacters) : task;
+        let currentTask = queuedSteering.length ? buildSteeredTask(task, queuedSteering, limits.taskCharacters) : task;
         const stopForBudget = (reason: string, message: string): void => {
           const limited = cloneResult(runtime.aggregate ?? results[index]!);
           limited.status = "limited";
@@ -1248,7 +1279,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             const aggregate = runtime.aggregate;
             const wallTimeMs = agent.timeoutMs ?? limits.wallTimeMs;
             const remainingWallTimeMs = wallTimeMs === undefined ? undefined : wallTimeMs - (Date.now() - runtime.startedAt);
-            const usedTraceBytes = aggregate?.traceBytes ?? 0;
+            const usedTraceBytes = (aggregate?.traceBytes ?? 0) + (aggregate?.traceTruncatedBytes ?? 0);
             const usedStderrBytes = aggregate?.stderrBytes ?? 0;
             const usedOutputBytes = aggregate?.outputBytes ?? 0;
             const usedTokens = aggregate?.usage.totalTokens ?? 0;
@@ -1257,15 +1288,15 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               stopForBudget("wall_time_limit", `Child thread exceeds ${wallTimeMs} ms`);
               break;
             }
-            if (limits.traceBytes !== undefined && (usedTraceBytes >= limits.traceBytes || aggregate?.traceTruncatedBytes)) {
+            if (limits.traceBytes !== undefined && usedTraceBytes >= limits.traceBytes) {
               stopForBudget("trace_limit", `Child thread retains more than ${limits.traceBytes} trace bytes`);
               break;
             }
-            if (limits.stderrBytes !== undefined && (usedStderrBytes >= limits.stderrBytes || aggregate?.stderrTruncatedBytes)) {
+            if (limits.stderrBytes !== undefined && usedStderrBytes >= limits.stderrBytes) {
               stopForBudget("stderr_limit", `Child thread emits more than ${limits.stderrBytes} stderr bytes`);
               break;
             }
-            if (limits.taskOutputBytes !== undefined && (usedOutputBytes >= limits.taskOutputBytes || aggregate?.outputTruncatedBytes)) {
+            if (limits.taskOutputBytes !== undefined && usedOutputBytes >= limits.taskOutputBytes) {
               stopForBudget("output_limit", `Child thread emits more than ${limits.taskOutputBytes} output bytes`);
               break;
             }
@@ -1289,6 +1320,8 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               webExtension: options.webExtension,
               projectTrusted: ctx.isProjectTrusted(),
               spawnProcess,
+              sessionDirectory,
+              sessionId,
               limits: {
                 ...limits,
                 ...(limits.traceBytes === undefined ? {} : { traceBytes: limits.traceBytes - usedTraceBytes }),
@@ -1305,7 +1338,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               },
             });
             next.task = task;
-            runtime.aggregate = mergeTaskResults(runtime.aggregate, next, limits.traceBytes);
+            runtime.aggregate = mergeTaskResults(runtime.aggregate, next, limits.traceRetentionBytes, limits.stderrRetentionBytes);
             runtime.aggregate.task = task;
             results[index] = cloneResult(runtime.aggregate);
             savedResults.set(threadId, cloneResult(runtime.aggregate));
@@ -1321,11 +1354,16 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
                 handoff: runtime.aggregate.output ? { summary: runtime.aggregate.output } : undefined,
               });
             }
-            currentTask = buildSteeredTask(task, steering, runtime.aggregate.output, limits.taskCharacters);
+            currentTask = buildSteeredTask(task, steering, limits.taskCharacters);
           }
         } finally {
           activeRuntimes.delete(threadId);
           signal?.removeEventListener("abort", abortParent);
+          try {
+            await rm(sessionDirectory, { recursive: true, force: true });
+          } catch {
+            // Temporary child session cleanup is best effort after process termination.
+          }
         }
         emit();
       };