@demicodes/agent 0.18.0 → 0.19.1

package/dist/client-entry.d.mts

@@ -1,4 +1,4 @@
-import { b as AgentMetadata, d as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike } from "./transport-DtBCCS_A.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-DdfGgBjO.mjs";
+import { f as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, x as AgentMetadata } from "./transport-BRqZoaeo.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C6Y5CeLG.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 export { type AgentActionOptions, AgentClient, type AgentClientListener, type AgentClientTransport, type AgentMetadata, type AgentServerTransport, type AgentTransport, type ClientFrame, type ClientSessionEvent, type JsonWebSocket, type ProviderSelection, type ServerFrame, type ShellCommandStatusLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/client-entry.mjs

@@ -1,2 +1,2 @@
-import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-c6P3NBuf.mjs";
+import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-CIOotpd-.mjs";
 export { AgentClient, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { A as AgentTool, B as TranscriptLog, C as AgentSessionCheckpoint, D as AgentSessionRestoreParams, E as AgentSessionParams, F as ModelSwitchApply, G as isRetryableCode, H as estimateTranscriptBlockTokens, I as SessionEvent, K as resolveRetryPolicy, L as SessionEventListener, M as AgentToolInvokeContext, N as AgentToolInvokeResult, O as AgentSessionStore, P as ExternalMutationReservation, R as CompactionWindow, S as AgentReferenceResolveContext, T as AgentSessionOptions, U as DEFAULT_TURN_RETRY_POLICY, V as TranscriptOptions, W as TurnRetryPolicy, _ as AgentHarnessRuntime, a as createInProcessTransportPair, b as AgentMetadata, c as ConversationSummary, d as TranscriptPatch, f as AbortResult, g as AgentHarnessContext, h as AgentHarness, i as InProcessTransportPair, j as AgentToolContext, k as AgentSystemPromptContext, l as ServerFrame, m as AgentDisposeContext, n as AgentServerTransport, o as ClientFrame, p as AbortTarget, q as retryDelayMs, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, v as AgentHostContext, w as AgentSessionCloneParams, x as AgentPromptContext, y as AgentLifecycleEvent, z as DrainedTranscriptPatches } from "./transport-DtBCCS_A.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-DdfGgBjO.mjs";
-import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
+import { A as AgentSystemPromptContext, B as CompactionWindow, C as AgentReferenceResolveContext, D as AgentSessionParams, E as AgentSessionOptions, F as ExternalMutationReservation, G as DEFAULT_TURN_RETRY_POLICY, H as TranscriptLog, I as ModelSwitchApply, J as resolveRetryPolicy, K as TurnRetryPolicy, L as SessionEvent, M as AgentToolContext, N as AgentToolInvokeContext, O as AgentSessionRestoreParams, P as AgentToolInvokeResult, R as SessionEventListener, S as AgentPromptContext, T as AgentSessionCloneParams, U as TranscriptOptions, V as DrainedTranscriptPatches, W as estimateTranscriptBlockTokens, Y as retryDelayMs, _ as AgentHarnessContext, a as createInProcessTransportPair, b as AgentLifecycleEvent, c as ConversationSummary, d as SubagentJob, f as TranscriptPatch, g as AgentHarness, h as AgentDisposeContext, i as InProcessTransportPair, j as AgentTool, k as AgentSessionStore, l as ServerFrame, m as AbortTarget, n as AgentServerTransport, o as ClientFrame, p as AbortResult, q as isRetryableCode, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, v as AgentHarnessRuntime, w as AgentSessionCheckpoint, x as AgentMetadata, y as AgentHostContext, z as SubagentProfile } from "./transport-BRqZoaeo.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C6Y5CeLG.mjs";
+import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, Command, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
 import { AgentProvider, Provider } from "@demicodes/provider";
 import { Block, Model, ModelMediaKind, ModelSelection, ProviderErrorDiagnostics, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
 //#region src/recovery.d.ts
@@ -149,6 +149,13 @@ declare class AgentSession<State> {
   state(): State;
   id(): string;
   phase(): SessionPhase;
+  /** Granular in-turn phase for observers (null when no turn is active). */
+  turnPhase(): ActiveTurnPhase | null;
+  hasPendingYields(): boolean;
+  /** Metadata of the currently executing action, if any. */
+  actionMetadata(): AgentMetadata | null;
+  /** Independent provider runtime with this session's configuration (for child sessions). */
+  cloneProviderRuntime(): AgentProvider;
   queuedMessages(): QueuedMessage[];
   dequeueMessage(id: string): boolean;
   sendQueuedMessage(id: string): boolean;
@@ -264,6 +271,14 @@ interface AgentServerOptions {
   providers: Provider[];
   shell?: Omit<BashEnvironmentOptions, 'host' | 'commands'>;
   session?: AgentServerSessionOptions;
+  subagents?: {
+    /**
+     * When false, a child closing never wakes an idle parent with an automatic
+     * user send; the host app observes the `subagent closed` frame and drives
+     * the parent itself. Defaults to true.
+     */
+    notifyParentOnIdle?: boolean;
+  };
   /**
    * Optional host-side shell prep (env, PATH, etc.). Implementation-agnostic —
    * command bridge wiring lives in `@demicodes/host-local`, not here.
@@ -307,6 +322,7 @@ declare class AgentServer {
   private readonly shellOptions;
   private readonly sessionOptions;
   private readonly prepareShell;
+  private readonly notifyParentOnIdle;
   private readonly bindings;
   private readonly sessionOwnership;
   constructor(options: AgentServerOptions);
@@ -321,6 +337,94 @@ declare class AgentServer {
   runCommandLine(shellId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
 }
 //#endregion
+//#region src/subagent.d.ts
+declare const MAX_LIVE_SUBAGENTS = 8;
+declare const SUBAGENT_RESULT_MAX_BYTES: number;
+type SubagentExecution = 'idle' | 'provider_streaming' | 'tool_executing' | 'compacting' | 'finalizing' | 'pending_yield';
+interface ChildSupervisorOptions<State> {
+  agent: AgentHarness<State>;
+  cwd: string;
+  /** Harness-configured profiles; null means the implicit `default` only. */
+  profiles: SubagentProfile<State>[] | null;
+  /** Parent registered commands (harness list, before the `demi agent` injection). */
+  parentCommands: Command[];
+  shellOptions: Omit<BashEnvironmentOptions, 'host' | 'commands'>;
+  prepareShell: PrepareShell | null;
+  sessionOptions: AgentServerSessionOptions;
+  /** When false, a child closing never wakes an idle parent; the host app orchestrates the wakeup from the `subagent closed` frame. */
+  notifyParentOnIdle: boolean;
+  emit(frame: ServerFrame): void;
+}
+/**
+ * Per-parent subagent supervisor. Owns every child `AgentSession` this parent
+ * spawns: lifecycle (spawn / steer / abort / natural end), the `demi agent`
+ * command tree, child shell environments, and the `subagent*` protocol frames
+ * on the parent connection. Children are in-memory only: no store, no
+ * checkpoint, gone with the parent.
+ */
+declare class ChildSupervisor<State = unknown> {
+  private readonly options;
+  private readonly jobs;
+  private parentSession;
+  private isDisposed;
+  constructor(options: ChildSupervisorOptions<State>);
+  attachParent(session: AgentSession<State>): void;
+  /** The `agent` node AgentServer grafts under the parent registry's `demi` root. */
+  rootCommandNode(): Command;
+  hasShell(shellId: string): boolean;
+  /** Resolves the child scope owning a shell, for the command bridge dispatch. */
+  environmentScopeForShell(shellId: string): {
+    environment: BashEnvironment;
+    commandNames: ReadonlySet<string>;
+    agentSessionId: string;
+  } | null;
+  /** Re-emits `subagent started` + transcript reset for every running child (transcript resync). */
+  replay(): void;
+  dispose(): Promise<void>;
+  abortSubtree(id: string): Promise<void>;
+  private spawn;
+  /** Delivers one steer to a child: mid-turn as a steer, idle as a new user turn. */
+  private steerChild;
+  private pumpStdinSteers;
+  private watchChild;
+  /** Tracks one child turn to session quiescence, then closes the job with its outcome. */
+  private watchTurn;
+  /** Resolves when the child is idle with no pending yield wakeups (or the job closed). */
+  private waitForQuiescence;
+  private closeJob;
+  /** Wakes an idle parent with a user send; a parent blocked in the spawn gets the tool result instead. */
+  private notifyIdleParent;
+  private createChildAgentNode;
+  private deliverToParent;
+  private childEnvironment;
+  private createChildEnvironment;
+  private resolveProfile;
+  private configuredProfileNames;
+  private subagentPreamble;
+  private recordTelemetry;
+  private executionOf;
+  private activityOf;
+  private executionForMs;
+  private snapshot;
+  private renderListLine;
+  private renderShow;
+  private wireJob;
+}
+/**
+ * Grafts the `agent` node under a `demi` root: onto an existing harness `demi`
+ * tree, or as a new `demi` root when the harness has none.
+ */
+declare function injectSubagentCommand(commands: Command[], agentNode: Command): Command[];
+/**
+ * Host wrapper for read-only subagent profiles: filesystem mutation is
+ * rejected outside the shell's own command-artifacts tree, and process spawn
+ * is rejected outright (a real process cannot be write-restricted).
+ *
+ * Every facet delegates method by method: Host facets are class instances
+ * whose methods live on the prototype, so object spread would drop them.
+ */
+declare function createReadonlyHost(host: Host): Host;
+//#endregion
 //#region src/tools.d.ts
 interface StandardAgentToolOptions<State = unknown> {
   environment: BashEnvironment | ((ctx: AgentToolInvokeContext<State>, handle: {
@@ -387,4 +491,4 @@ interface ShellToolView {
 declare function finishShellToolResult<State>(environment: BashEnvironment, result: ShellCommandStatus, ctx: AgentToolInvokeContext<State>): Promise<AgentToolInvokeResult>;
 declare function shellCommandHandleRequired(result: ShellCommandStatus, budgetTokens: number): boolean;
 //#endregion
-export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionCloneParams, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, ModelSwitchApply, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionCloneParams, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ChildSupervisor, ChildSupervisorOptions, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, MAX_LIVE_SUBAGENTS, ModelSwitchApply, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, SubagentExecution, SubagentJob, SubagentProfile, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/index.mjs

@@ -1,8 +1,9 @@
-import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, o as ProviderStreamError, r as AgentClient, s as isContextLengthExceeded, t as createWebSocketClientTransport } from "./websocket-transport-c6P3NBuf.mjs";
-import { AbortError, abortable, asError, asRecord, asString, bytesToBase64, createId, delay, isAbortError, isRecord, noop, parseJsonOrString, safeJsonStringify, sliceHead, sliceTail, throwIfAborted, toWellFormedText, truncate } from "@demicodes/utils";
+import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, o as ProviderStreamError, r as AgentClient, s as isContextLengthExceeded, t as createWebSocketClientTransport } from "./websocket-transport-CIOotpd-.mjs";
+import { AbortError, abortable, asError, asRecord, asString, bytesToBase64, createId, decodeUtf8, delay, errorMessage, isAbortError, isRecord, noop, parseJsonOrString, safeJsonStringify, sliceHead, sliceTail, throwIfAborted, toWellFormedText, truncate, utf8Slice } from "@demicodes/utils";
 import { BashEnvironment, CommandRegistry, MAX_TIMEOUT_MS, heredocDelimiter, shellQuote } from "@demicodes/shell";
 import { providerRuntime } from "@demicodes/provider";
 import { modelAcceptsMediaType, sniffModelMediaType } from "@demicodes/core";
+import { z } from "zod";
 //#region src/transcript.ts
 const DEFAULT_MODEL_TEXT_HEAD_CHARS = 8e3;
 const DEFAULT_MODEL_TEXT_TAIL_CHARS = 8e3;
@@ -912,7 +913,7 @@ var CompactionController = class {
 				text: COMPACTION_SUMMARY_INSTRUCTION
 			}]);
 			throwIfAborted(parentSignal);
-			return lastAssistantText(clone.transcript(), baseBlockCount).trim();
+			return lastAssistantText$1(clone.transcript(), baseBlockCount).trim();
 		} finally {
 			parentSignal.removeEventListener("abort", abortClone);
 			unsubscribe();
@@ -920,7 +921,7 @@ var CompactionController = class {
 		}
 	}
 };
-function lastAssistantText(transcript, startIndex) {
+function lastAssistantText$1(transcript, startIndex) {
 	for (let index = transcript.blocks.length - 1; index >= startIndex; index -= 1) {
 		const block = transcript.blocks[index];
 		if (block?.type === "text") return block.text;
@@ -1583,6 +1584,21 @@ var AgentSession = class AgentSession {
 	phase() {
 		return this.currentPhase;
 	}
+	/** Granular in-turn phase for observers (null when no turn is active). */
+	turnPhase() {
+		return this.activeTurnPhase;
+	}
+	hasPendingYields() {
+		return this.yields.hasPending;
+	}
+	/** Metadata of the currently executing action, if any. */
+	actionMetadata() {
+		return this.activeMetadata;
+	}
+	/** Independent provider runtime with this session's configuration (for child sessions). */
+	cloneProviderRuntime() {
+		return this.provider.clone();
+	}
 	queuedMessages() {
 		return this.queued.map((message) => ({
 			...message,
@@ -2635,6 +2651,767 @@ function shellCommandHandleRequired(result, budgetTokens) {
 	return preview.truncated || result.output.truncated || result.output.bytes > maxChars || result.stdout.truncated || result.stderr.truncated;
 }
 //#endregion
+//#region src/subagent.ts
+const MAX_LIVE_SUBAGENTS = 8;
+const SUBAGENT_RESULT_MAX_BYTES = 32768;
+const SHOW_RECENT_TOOLS = 8;
+const SPAWN_PROMPT_DESCRIPTION = "The child's first user message and only task brief. The child starts with an empty transcript and cannot see this conversation: do not refer to prior turns, and do not paste this conversation or the product user's message unchanged. Include the goal for this child, applicable decisions and constraints, whether to edit or only report, how to verify, and every concrete identifier it needs (paths, ids, error text, commands already tried and their key results). State the exact shape of the last assistant text it should return.";
+/**
+* Per-parent subagent supervisor. Owns every child `AgentSession` this parent
+* spawns: lifecycle (spawn / steer / abort / natural end), the `demi agent`
+* command tree, child shell environments, and the `subagent*` protocol frames
+* on the parent connection. Children are in-memory only: no store, no
+* checkpoint, gone with the parent.
+*/
+var ChildSupervisor = class {
+	options;
+	jobs = /* @__PURE__ */ new Map();
+	parentSession = null;
+	isDisposed = false;
+	constructor(options) {
+		this.options = options;
+	}
+	attachParent(session) {
+		this.parentSession = session;
+	}
+	/** The `agent` node AgentServer grafts under the parent registry's `demi` root. */
+	rootCommandNode() {
+		const profileNames = this.configuredProfileNames();
+		return {
+			name: "agent",
+			summary: "Start an isolated child agent session and wait for its result. The command stays running until the child session ends; stdout is the child's last assistant text. While it is the foreground job, shell_write steers the child and shell_abort aborts it. Run several in separate shell_exec calls with short timeoutMs to fan out.",
+			successOutput: "first stderr line is \"subagentId: <id>\" at start; stdout is the child's last assistant text (empty is valid), written only at exit",
+			failureOutput: "non-zero exit with the abort or failure reason on stderr",
+			input: {
+				prompt: z.string().optional().describe(SPAWN_PROMPT_DESCRIPTION),
+				profile: z.string().optional().describe(`Named subagent profile configured at harness assembly. Available: ${profileNames.join(", ")}.`),
+				description: z.string().optional().describe("Short UI title distinguishing concurrent children.")
+			},
+			positionals: ["prompt"],
+			stdinField: "prompt",
+			output: { json: z.object({
+				subagentId: z.string(),
+				text: z.string()
+			}) },
+			run: async ({ parsed, io, signal, stdinStream }) => {
+				const prompt = String(parsed.values.prompt ?? "").trim();
+				if (!prompt) {
+					await io.stderr("demi agent: prompt must not be empty\n");
+					return { exitCode: 1 };
+				}
+				let job;
+				try {
+					job = await this.spawn({
+						prompt,
+						profileName: parsed.values.profile === void 0 ? void 0 : String(parsed.values.profile),
+						description: parsed.values.description === void 0 ? "" : String(parsed.values.description)
+					});
+				} catch (error) {
+					await io.stderr(`demi agent: ${errorMessage(error)}\n`);
+					return { exitCode: 1 };
+				}
+				await io.stderr(`subagentId: ${job.id}\n`);
+				const onAbort = () => {
+					this.abortSubtree(job.id).catch(noop);
+				};
+				if (signal.aborted) onAbort();
+				else signal.addEventListener("abort", onAbort, { once: true });
+				this.pumpStdinSteers(job.id, stdinStream);
+				const close = await job.closed;
+				signal.removeEventListener("abort", onAbort);
+				if (close.phase === "completed") {
+					const text = close.result ?? "";
+					if (parsed.json) await io.stdout(`${JSON.stringify({
+						subagentId: job.id,
+						text
+					})}\n`);
+					else if (text.length > 0) await io.stdout(text.endsWith("\n") ? text : `${text}\n`);
+					return { exitCode: 0 };
+				}
+				if (close.phase === "aborted") {
+					await io.stderr(`demi agent: subagent ${job.id} aborted\n`);
+					return { exitCode: 130 };
+				}
+				await io.stderr(`demi agent: subagent ${job.id} failed: ${close.failure ?? "unknown error"}\n`);
+				return { exitCode: 1 };
+			},
+			subcommands: [
+				{
+					name: "steer",
+					summary: "Send a user steer to a running child. Queues until the child can take it; does not wait.",
+					input: {
+						id: z.string().describe("subagentId from spawn stderr"),
+						message: z.string().optional().describe("Message body; positional, or stdin/heredoc when omitted.")
+					},
+					positionals: ["id", "message"],
+					stdinField: "message",
+					output: { json: z.object({
+						id: z.string(),
+						accepted: z.boolean()
+					}) },
+					run: async ({ parsed, io }) => {
+						const id = String(parsed.values.id);
+						const message = String(parsed.values.message ?? "").trim();
+						if (!message) {
+							await io.stderr("demi agent steer: message must not be empty\n");
+							return { exitCode: 1 };
+						}
+						const job = this.jobs.get(id);
+						if (!job) {
+							await io.stderr(`demi agent steer: no running subagent "${id}"\n`);
+							return { exitCode: 1 };
+						}
+						await this.steerChild(job, message);
+						await io.stdout(parsed.json ? `${JSON.stringify({
+							id,
+							accepted: true
+						})}\n` : `steered ${id}\n`);
+						return { exitCode: 0 };
+					}
+				},
+				{
+					name: "abort",
+					summary: "Abort a running child and its subtree. Siblings are untouched.",
+					input: { id: z.string().describe("subagentId from spawn stderr") },
+					positionals: ["id"],
+					output: { json: z.object({
+						id: z.string(),
+						aborted: z.boolean()
+					}) },
+					run: async ({ parsed, io }) => {
+						const id = String(parsed.values.id);
+						if (!this.jobs.has(id)) {
+							await io.stderr(`demi agent abort: no running subagent "${id}"\n`);
+							return { exitCode: 1 };
+						}
+						await this.abortSubtree(id);
+						await io.stdout(parsed.json ? `${JSON.stringify({
+							id,
+							aborted: true
+						})}\n` : `aborted ${id}\n`);
+						return { exitCode: 0 };
+					}
+				},
+				{
+					name: "list",
+					summary: "Snapshot roster of this session's running children (finished children are absent). One line per child with ages relative to now. A read, not a wait — not for polling loops.",
+					output: { json: z.object({ agents: z.array(z.unknown()) }) },
+					run: async ({ parsed, io }) => {
+						const jobs = [...this.jobs.values()];
+						if (parsed.json) {
+							await io.stdout(`${JSON.stringify({ agents: jobs.map((job) => this.snapshot(job, false)) })}\n`);
+							return { exitCode: 0 };
+						}
+						if (jobs.length === 0) {
+							await io.stdout("no running subagents\n");
+							return { exitCode: 0 };
+						}
+						for (const job of jobs) await io.stdout(`${this.renderListLine(job)}\n`);
+						return { exitCode: 0 };
+					}
+				},
+				{
+					name: "show",
+					summary: "Bounded snapshot of one running child: execution state, recent tool titles with durations, last assistant text. Every duration is relative to now — use the ages to tell motion from stall. Omits tool outputs, file contents, and older turns. A read, not a wait — not for polling loops.",
+					input: { id: z.string().describe("subagentId from spawn stderr") },
+					positionals: ["id"],
+					output: { json: z.object({ agent: z.unknown() }) },
+					run: async ({ parsed, io }) => {
+						const id = String(parsed.values.id);
+						const job = this.jobs.get(id);
+						if (!job) {
+							await io.stderr(`demi agent show: no running subagent "${id}"\n`);
+							return { exitCode: 1 };
+						}
+						if (parsed.json) await io.stdout(`${JSON.stringify({ agent: this.snapshot(job, true) })}\n`);
+						else await io.stdout(this.renderShow(job));
+						return { exitCode: 0 };
+					}
+				}
+			]
+		};
+	}
+	hasShell(shellId) {
+		return this.environmentScopeForShell(shellId) !== null;
+	}
+	/** Resolves the child scope owning a shell, for the command bridge dispatch. */
+	environmentScopeForShell(shellId) {
+		for (const job of this.jobs.values()) for (const environment of job.environments.values()) if (environment.getShell(shellId)) return {
+			environment,
+			commandNames: new Set(job.commandNames),
+			agentSessionId: job.id
+		};
+		return null;
+	}
+	/** Re-emits `subagent started` + transcript reset for every running child (transcript resync). */
+	replay() {
+		for (const job of this.jobs.values()) {
+			this.options.emit({
+				type: "subagent",
+				event: "started",
+				job: this.wireJob(job)
+			});
+			const transcript = job.session.transcript();
+			this.options.emit({
+				type: "subagent_transcript_reset",
+				subagentId: job.id,
+				blocks: structuredClone(transcript.blocks),
+				revision: transcript.revision
+			});
+		}
+	}
+	async dispose() {
+		this.isDisposed = true;
+		for (const job of [...this.jobs.values()]) await this.closeJob(job, "aborted");
+	}
+	async abortSubtree(id) {
+		const job = this.jobs.get(id);
+		if (!job) return;
+		await this.closeJob(job, "aborted");
+	}
+	async spawn(input) {
+		const parent = this.parentSession;
+		if (!parent) throw new Error("subagent supervisor has no parent session");
+		if (this.isDisposed) throw new Error("parent session is closing");
+		if (this.jobs.size >= 8) throw new Error(`at most 8 running subagents per session; abort one or wait for a result`);
+		const profile = this.resolveProfile(input.profileName);
+		const id = createId();
+		const metadata = parent.actionMetadata();
+		const agentNode = this.createChildAgentNode(id, input.description);
+		const commands = injectSubagentCommand(profile.commands ? profile.commands([...this.options.parentCommands]) : [...this.options.parentCommands], agentNode);
+		const commandRegistry = new CommandRegistry();
+		for (const command of commands) commandRegistry.register(command);
+		const commandNames = commandRegistry.list().map((command) => command.name);
+		const commandsPrompt = commandRegistry.renderHelp();
+		let settleClosed;
+		const closed = new Promise((resolve) => {
+			settleClosed = resolve;
+		});
+		const job = {
+			id,
+			description: input.description,
+			profile,
+			profileName: input.profileName ?? (this.options.profiles ? profile.name : null),
+			metadata,
+			session: null,
+			commandRegistry,
+			commandNames,
+			environments: /* @__PURE__ */ new Map(),
+			pendingEnvironments: /* @__PURE__ */ new Map(),
+			readonlyHosts: /* @__PURE__ */ new WeakMap(),
+			spawnedAt: Date.now(),
+			lastEventAt: Date.now(),
+			tools: [],
+			lastAssistantTextAt: null,
+			phase: "running",
+			failure: null,
+			unsubscribe: noop,
+			closed,
+			settleClosed,
+			isClosing: false
+		};
+		const agent = this.options.agent;
+		const preamble = this.subagentPreamble(id);
+		const runtime = {
+			harnessName: agent.name,
+			initialState: () => agent.initialState(),
+			systemPrompt: (ctx) => (profile.systemPrompt ?? agent.systemPrompt).call(agent, {
+				...ctx,
+				commandsPrompt
+			}),
+			preamble: async (ctx) => {
+				const inheritedPreamble = profile.systemPrompt ? null : await agent.preamble?.(ctx) ?? null;
+				return inheritedPreamble ? `${inheritedPreamble}\n\n${preamble}` : preamble;
+			},
+			tools: () => createStandardAgentTools({
+				environment: (ctx) => this.childEnvironment(job, ctx),
+				scheduleYield: (ctx, durationMs) => job.session.scheduleYieldWakeup(durationMs, ctx.metadata)
+			})
+		};
+		job.session = new AgentSession({
+			provider: parent.cloneProviderRuntime(),
+			model: profile.model ?? structuredClone(parent.modelSelection),
+			cwd: this.options.cwd,
+			runtime,
+			state: agent.initialState()
+		}, {
+			agentSessionId: id,
+			...this.options.sessionOptions
+		});
+		job.unsubscribe = job.session.subscribe((event) => {
+			if (event.type !== "transcript_changed") return;
+			this.recordTelemetry(job, event.patches);
+			this.options.emit({
+				type: "subagent_transcript_patch",
+				subagentId: id,
+				patches: event.patches,
+				revision: event.revision
+			});
+		});
+		this.jobs.set(id, job);
+		this.options.emit({
+			type: "subagent",
+			event: "started",
+			job: this.wireJob(job)
+		});
+		this.options.emit({
+			type: "subagent_transcript_reset",
+			subagentId: id,
+			blocks: [],
+			revision: 0
+		});
+		this.watchChild(job, input.prompt);
+		return job;
+	}
+	/** Delivers one steer to a child: mid-turn as a steer, idle as a new user turn. */
+	async steerChild(job, message) {
+		const content = [{
+			type: "text",
+			text: message
+		}];
+		if (job.session.phase() !== "idle") try {
+			await job.session.steer(content);
+			return;
+		} catch {}
+		this.watchTurn(job, job.session.send(content));
+	}
+	async pumpStdinSteers(id, stdinStream) {
+		try {
+			for await (const chunk of stdinStream) {
+				const job = this.jobs.get(id);
+				if (!job) return;
+				const message = decodeUtf8(chunk).trim();
+				if (message) await this.steerChild(job, message);
+			}
+		} catch {}
+	}
+	watchChild(job, prompt) {
+		const opening = job.session.send([{
+			type: "text",
+			text: prompt
+		}], job.metadata ? { metadata: job.metadata } : {});
+		this.watchTurn(job, opening);
+	}
+	/** Tracks one child turn to session quiescence, then closes the job with its outcome. */
+	async watchTurn(job, turn) {
+		try {
+			await turn;
+		} catch (error) {
+			job.failure = errorMessage(error);
+			await this.closeJob(job, "error");
+			return;
+		}
+		await this.waitForQuiescence(job);
+		if (job.phase === "running" && !job.isClosing) await this.closeJob(job, "completed");
+	}
+	/** Resolves when the child is idle with no pending yield wakeups (or the job closed). */
+	async waitForQuiescence(job) {
+		while (!job.isClosing && (job.session.phase() !== "idle" || job.session.hasPendingYields())) await new Promise((resolve) => {
+			let settled = false;
+			const finish = () => {
+				if (settled) return;
+				settled = true;
+				unsubscribe();
+				resolve();
+			};
+			const unsubscribe = job.session.subscribe((event) => {
+				if (event.type === "phase_changed") finish();
+			});
+			job.closed.then(finish);
+		});
+	}
+	async closeJob(job, phase) {
+		if (job.isClosing) return;
+		job.isClosing = true;
+		job.phase = phase;
+		job.unsubscribe();
+		this.jobs.delete(job.id);
+		const result = phase === "completed" ? boundedResultText(lastAssistantText(job.session.transcript().blocks)) : void 0;
+		await job.session.dispose().catch(noop);
+		const environments = /* @__PURE__ */ new Set([...job.environments.values()]);
+		for (const pending of job.pendingEnvironments.values()) {
+			const environment = await pending.catch(() => null);
+			if (environment) environments.add(environment);
+		}
+		for (const environment of environments) await environment.disposeAllShells().catch(noop);
+		const close = {
+			phase,
+			...result !== void 0 ? { result } : {},
+			...job.failure ? { failure: job.failure } : {}
+		};
+		this.options.emit({
+			type: "subagent",
+			event: "closed",
+			job: this.wireJob(job, result)
+		});
+		job.settleClosed(close);
+		this.notifyIdleParent(job, close);
+	}
+	/** Wakes an idle parent with a user send; a parent blocked in the spawn gets the tool result instead. */
+	notifyIdleParent(job, close) {
+		if (this.isDisposed || !this.options.notifyParentOnIdle) return;
+		const parent = this.parentSession;
+		if (!parent || parent.phase() !== "idle") return;
+		const label = `subagent ${job.id}${job.description ? ` — ${job.description}` : ""}`;
+		const body = close.phase === "completed" ? `[${label}] completed.\nResult:\n${close.result || "(empty)"}` : close.phase === "aborted" ? `[${label}] aborted.` : `[${label}] failed: ${close.failure ?? "unknown error"}`;
+		parent.send([{
+			type: "text",
+			text: body
+		}], job.metadata ? { metadata: job.metadata } : {}).catch(noop);
+	}
+	createChildAgentNode(childId, description) {
+		return {
+			name: "agent",
+			summary: "Subagent bridge to the parent session.",
+			subcommands: [{
+				name: "send-parent",
+				summary: "Send an interim user message to the parent session. The parent sees it only when it is not blocked waiting on this session. Your result is still the last assistant text when this session ends, not this message.",
+				input: { message: z.string().optional().describe("Message body; positional, or stdin/heredoc when omitted.") },
+				positionals: ["message"],
+				stdinField: "message",
+				output: { json: z.object({ accepted: z.boolean() }) },
+				run: async ({ parsed, io }) => {
+					const message = String(parsed.values.message ?? "").trim();
+					if (!message) {
+						await io.stderr("demi agent send-parent: message must not be empty\n");
+						return { exitCode: 1 };
+					}
+					this.deliverToParent(childId, description, message);
+					await io.stdout(parsed.json ? `${JSON.stringify({ accepted: true })}\n` : "sent\n");
+					return { exitCode: 0 };
+				}
+			}]
+		};
+	}
+	deliverToParent(childId, description, message) {
+		const parent = this.parentSession;
+		if (!parent || this.isDisposed) return;
+		const content = [{
+			type: "text",
+			text: `[subagent ${childId}${description ? ` — ${description}` : ""}] ${message}`
+		}];
+		const metadata = this.jobs.get(childId)?.metadata ?? null;
+		const sendOptions = metadata ? { metadata } : {};
+		if (parent.phase() !== "idle") {
+			parent.steer(content).catch(() => {
+				parent.send(content, sendOptions).catch(noop);
+			});
+			return;
+		}
+		parent.send(content, sendOptions).catch(noop);
+	}
+	async childEnvironment(job, ctx) {
+		const resolved = await this.options.agent.host({
+			agentSessionId: job.id,
+			state: ctx.state,
+			cwd: this.options.cwd,
+			metadata: ctx.metadata
+		});
+		let host = resolved;
+		if (job.profile.readonly) {
+			const wrapped = job.readonlyHosts.get(resolved) ?? createReadonlyHost(resolved);
+			job.readonlyHosts.set(resolved, wrapped);
+			host = wrapped;
+		}
+		const existing = job.environments.get(host);
+		if (existing) return existing;
+		const pending = job.pendingEnvironments.get(host);
+		if (pending) return pending;
+		const creation = this.createChildEnvironment(job, host);
+		job.pendingEnvironments.set(host, creation);
+		try {
+			const environment = await creation;
+			job.environments.set(host, environment);
+			return environment;
+		} finally {
+			job.pendingEnvironments.delete(host);
+		}
+	}
+	async createChildEnvironment(job, host) {
+		const prepared = this.options.prepareShell && !job.profile.readonly ? await this.options.prepareShell({
+			agentSessionId: job.id,
+			host,
+			commandNames: job.commandNames,
+			shell: this.options.shellOptions
+		}) : this.options.shellOptions;
+		return new BashEnvironment({
+			...prepared,
+			initialEnv: {
+				...prepared.initialEnv,
+				DEMI_SUBAGENT_ID: job.id,
+				DEMI_PARENT_SESSION_ID: this.parentSession?.id() ?? "",
+				DEMI_SUBAGENT_DEPTH: "1"
+			},
+			host,
+			commands: job.commandRegistry
+		});
+	}
+	resolveProfile(name) {
+		const profiles = this.options.profiles;
+		const implicitDefault = {
+			name: "default",
+			description: "Inherits the parent harness, model, Host, and commands."
+		};
+		if (!profiles || profiles.length === 0) {
+			if (name !== void 0 && name !== "default") throw new Error(`unknown profile "${name}" (available: default)`);
+			return implicitDefault;
+		}
+		const target = name ?? "default";
+		const profile = profiles.find((candidate) => candidate.name === target);
+		if (profile) return profile;
+		if (name === void 0) return implicitDefault;
+		throw new Error(`unknown profile "${name}" (available: ${this.configuredProfileNames().join(", ")})`);
+	}
+	configuredProfileNames() {
+		const names = (this.options.profiles ?? []).map((profile) => profile.name);
+		return names.includes("default") ? names : ["default", ...names];
+	}
+	subagentPreamble(childId) {
+		return [
+			`You are a subagent: an isolated child agent session (id ${childId}) spawned by a parent agent session. Your transcript starts empty; the task brief in the first user message is your entire context.`,
+			"When you end your turn with no scheduled wakeups, the session ends and your last assistant text is returned to the parent as the result. Write it for the parent agent, in the shape the task brief asked for.",
+			"`demi agent send-parent <message>` sends an interim user message to the parent; it is seen only when the parent is not blocked waiting on this session.",
+			"You are not talking to the product user; do not address them."
+		].join("\n");
+	}
+	recordTelemetry(job, patches) {
+		const now = Date.now();
+		for (const patch of patches) {
+			if (patch.op === "add") {
+				const block = patch.value;
+				if (block.type === "tool_call") {
+					job.tools.push({
+						toolUseId: block.toolUseId,
+						title: toolCallTitle(block),
+						startedAt: now,
+						endedAt: null,
+						status: "executing"
+					});
+					trimToolRecords(job.tools);
+					job.lastEventAt = now;
+				} else if (block.type === "text") {
+					job.lastAssistantTextAt = now;
+					job.lastEventAt = now;
+				}
+				continue;
+			}
+			if (patch.op === "append_text") {
+				if (job.session.transcript().blocks[patch.path[1]]?.type === "text") {
+					job.lastAssistantTextAt = now;
+					job.lastEventAt = now;
+				}
+				continue;
+			}
+			if (patch.op === "replace_block") {
+				const block = patch.value;
+				if (block.type !== "tool_call" || block.status === "executing") continue;
+				const record = job.tools.find((tool) => tool.toolUseId === block.toolUseId && tool.endedAt === null);
+				if (record) {
+					record.endedAt = now;
+					record.status = block.status === "error" ? "error" : "completed";
+				}
+				job.lastEventAt = now;
+			}
+		}
+	}
+	executionOf(job) {
+		const phase = job.session.phase();
+		if (phase === "compacting") return "compacting";
+		if (phase === "idle") return job.session.hasPendingYields() ? "pending_yield" : "idle";
+		return job.session.turnPhase() ?? "provider_streaming";
+	}
+	activityOf(job, execution) {
+		const inflight = [...job.tools].reverse().find((tool) => tool.endedAt === null);
+		if (execution === "tool_executing" && inflight) return inflight.title;
+		if (execution === "provider_streaming") return "streaming";
+		return execution;
+	}
+	executionForMs(job, execution, now) {
+		if (execution === "tool_executing") {
+			const inflight = [...job.tools].reverse().find((tool) => tool.endedAt === null);
+			if (inflight) return now - inflight.startedAt;
+		}
+		return now - job.lastEventAt;
+	}
+	snapshot(job, detailed) {
+		const now = Date.now();
+		const execution = this.executionOf(job);
+		const base = {
+			subagentId: job.id,
+			description: job.description,
+			profile: job.profileName,
+			phase: job.phase,
+			elapsedMs: now - job.spawnedAt,
+			lastEventMs: now - job.lastEventAt,
+			execution,
+			activity: this.activityOf(job, execution)
+		};
+		if (!detailed) return base;
+		const text = lastAssistantText(job.session.transcript().blocks);
+		return {
+			...base,
+			executionForMs: this.executionForMs(job, execution, now),
+			tools: job.tools.slice(-8).map((tool) => ({
+				title: tool.title,
+				status: tool.status,
+				durationMs: (tool.endedAt ?? now) - tool.startedAt,
+				endedAgoMs: tool.endedAt === null ? null : now - tool.endedAt
+			})),
+			lastAssistantText: boundedResultText(text),
+			lastAssistantTextAgoMs: job.lastAssistantTextAt === null ? null : now - job.lastAssistantTextAt
+		};
+	}
+	renderListLine(job) {
+		const now = Date.now();
+		const execution = this.executionOf(job);
+		return [
+			job.id,
+			job.phase,
+			`up ${formatDuration(now - job.spawnedAt)}`,
+			`last-event ${formatDuration(now - job.lastEventAt)} ago`,
+			`profile=${job.profileName ?? "default"}`,
+			job.description ? `"${job.description}"` : "(no description)",
+			`execution=${execution}`,
+			`activity=${this.activityOf(job, execution)}`
+		].join("  ");
+	}
+	renderShow(job) {
+		const now = Date.now();
+		const execution = this.executionOf(job);
+		const lines = [
+			`id: ${job.id}`,
+			`description: ${job.description || "(none)"}`,
+			`profile: ${job.profileName ?? "default"}`,
+			`phase: ${job.phase}`,
+			`elapsed: ${formatDuration(now - job.spawnedAt)}`,
+			`execution: ${execution} (for ${formatDuration(this.executionForMs(job, execution, now))})`,
+			`last-event: ${formatDuration(now - job.lastEventAt)} ago`,
+			`activity: ${this.activityOf(job, execution)}`
+		];
+		const recent = job.tools.slice(-8);
+		if (recent.length > 0) {
+			lines.push(`recent tool calls (last ${recent.length}):`);
+			for (const tool of recent) if (tool.endedAt === null) lines.push(`  [executing for ${formatDuration(now - tool.startedAt)}] ${tool.title}`);
+			else lines.push(`  [${tool.status} in ${formatDuration(tool.endedAt - tool.startedAt)}, ended ${formatDuration(now - tool.endedAt)} ago] ${tool.title}`);
+		}
+		const text = boundedResultText(lastAssistantText(job.session.transcript().blocks));
+		if (text && job.lastAssistantTextAt !== null) {
+			lines.push(`last assistant text (${formatDuration(now - job.lastAssistantTextAt)} ago):`);
+			lines.push(text);
+		} else lines.push("last assistant text: (none yet)");
+		return `${lines.join("\n")}\n`;
+	}
+	wireJob(job, result) {
+		return {
+			subagentId: job.id,
+			parentSessionId: this.parentSession?.id() ?? "",
+			description: job.description,
+			profile: job.profileName,
+			phase: job.phase,
+			...result !== void 0 ? { result } : {}
+		};
+	}
+};
+/**
+* Grafts the `agent` node under a `demi` root: onto an existing harness `demi`
+* tree, or as a new `demi` root when the harness has none.
+*/
+function injectSubagentCommand(commands, agentNode) {
+	const demiIndex = commands.findIndex((command) => command.name === "demi");
+	if (demiIndex === -1) return [...commands, {
+		name: "demi",
+		summary: "Demi agent runtime commands.",
+		subcommands: [agentNode]
+	}];
+	const demi = commands[demiIndex];
+	const subcommands = [...(demi.subcommands ?? []).filter((command) => command.name !== "agent"), agentNode];
+	const next = [...commands];
+	next[demiIndex] = {
+		...demi,
+		subcommands
+	};
+	return next;
+}
+/**
+* Host wrapper for read-only subagent profiles: filesystem mutation is
+* rejected outside the shell's own command-artifacts tree, and process spawn
+* is rejected outright (a real process cannot be write-restricted).
+*
+* Every facet delegates method by method: Host facets are class instances
+* whose methods live on the prototype, so object spread would drop them.
+*/
+function createReadonlyHost(host) {
+	const artifactsRoot = host.commandArtifactsDir.replace(/\/+$/, "");
+	const isArtifactPath = (path, cwd) => {
+		const resolved = path.startsWith("/") ? path : `${(cwd ?? host.defaultCwd).replace(/\/+$/, "")}/${path}`;
+		return resolved === artifactsRoot || resolved.startsWith(`${artifactsRoot}/`);
+	};
+	const deny = (operation) => Promise.reject(/* @__PURE__ */ new Error(`read-only subagent: ${operation} is not permitted on this Host`));
+	return {
+		defaultCwd: host.defaultCwd,
+		commandArtifactsDir: host.commandArtifactsDir,
+		identity: host.identity,
+		store: host.store,
+		fs: {
+			readFile: (path, options) => host.fs.readFile(path, options),
+			exists: (path, options) => host.fs.exists(path, options),
+			stat: (path, options) => host.fs.stat(path, options),
+			lstat: (path, options) => host.fs.lstat(path, options),
+			readdir: ((path, options) => host.fs.readdir(path, options)),
+			readlink: (path, options) => host.fs.readlink(path, options),
+			realpath: (path, options) => host.fs.realpath(path, options),
+			writeFile: (path, data, options) => isArtifactPath(path, options?.cwd) ? host.fs.writeFile(path, data, options) : deny(`write ${path}`),
+			appendFile: (path, data, options) => isArtifactPath(path, options?.cwd) ? host.fs.appendFile(path, data, options) : deny(`append ${path}`),
+			mkdir: (path, options) => isArtifactPath(path, options?.cwd) ? host.fs.mkdir(path, options) : deny(`mkdir ${path}`),
+			rm: (path) => deny(`rm ${path}`),
+			cp: (path, destination, options) => isArtifactPath(destination, options?.cwd) ? host.fs.cp(path, destination, options) : deny(`cp to ${destination}`),
+			mv: (path, destination) => deny(`mv ${path} ${destination}`),
+			chmod: (path) => deny(`chmod ${path}`),
+			symlink: (_target, path) => deny(`symlink ${path}`),
+			link: (_existingPath, path) => deny(`link ${path}`),
+			utimes: (path) => deny(`utimes ${path}`)
+		},
+		process: {
+			openCwd: (path) => host.process.openCwd(path),
+			spawn: () => deny("process spawn")
+		}
+	};
+}
+function trimToolRecords(tools) {
+	while (tools.length > SHOW_RECENT_TOOLS) {
+		const index = tools.findIndex((tool) => tool.endedAt !== null);
+		if (index === -1) return;
+		tools.splice(index, 1);
+	}
+}
+function toolCallTitle(block) {
+	try {
+		const input = JSON.parse(block.input);
+		if (typeof input.description === "string" && input.description.trim()) return input.description.trim();
+	} catch {}
+	return block.toolName;
+}
+function lastAssistantText(blocks) {
+	for (let i = blocks.length - 1; i >= 0; i -= 1) {
+		const block = blocks[i];
+		if (block.type === "text") return block.text;
+	}
+	return "";
+}
+function boundedResultText(text) {
+	return utf8Slice(text, 0, SUBAGENT_RESULT_MAX_BYTES);
+}
+function formatDuration(ms) {
+	const totalSeconds = Math.max(0, Math.round(ms / 1e3));
+	if (totalSeconds < 60) return `${totalSeconds}s`;
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	if (minutes < 60) return seconds > 0 ? `${minutes}m${seconds}s` : `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const remMinutes = minutes % 60;
+	return remMinutes > 0 ? `${hours}h${remMinutes}m` : `${hours}h`;
+}
+//#endregion
 //#region src/server.ts
 var RunCommandLineShellNotFoundError = class extends Error {
 	shellId;
@@ -2670,6 +3447,7 @@ var AgentServer = class {
 	shellOptions;
 	sessionOptions;
 	prepareShell;
+	notifyParentOnIdle;
 	bindings = /* @__PURE__ */ new Set();
 	sessionOwnership = new SessionOwnershipRegistry();
 	constructor(options) {
@@ -2678,6 +3456,7 @@ var AgentServer = class {
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
 		this.prepareShell = options.prepareShell ?? null;
+		this.notifyParentOnIdle = options.subagents?.notifyParentOnIdle ?? true;
 	}
 	client() {
 		const transports = createInProcessTransportPair();
@@ -2692,6 +3471,7 @@ var AgentServer = class {
 			shell: this.shellOptions,
 			session: this.sessionOptions,
 			prepareShell: this.prepareShell,
+			notifyParentOnIdle: this.notifyParentOnIdle,
 			sessions: this.sessionOwnership
 		});
 		this.bindings.add(binding);
@@ -2741,6 +3521,7 @@ var AgentTransportBindingImpl = class {
 	shellOptions;
 	sessionOptions;
 	prepareShell;
+	notifyParentOnIdle;
 	sessions;
 	session = null;
 	currentAgent = null;
@@ -2751,6 +3532,7 @@ var AgentTransportBindingImpl = class {
 	currentProviderId = null;
 	currentSessionId = null;
 	currentCommandNames = /* @__PURE__ */ new Set();
+	supervisor = null;
 	unsubscribeSession = null;
 	unsubscribeTransport = null;
 	closed = false;
@@ -2761,6 +3543,7 @@ var AgentTransportBindingImpl = class {
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
 		this.prepareShell = options.prepareShell;
+		this.notifyParentOnIdle = options.notifyParentOnIdle;
 		this.sessions = options.sessions;
 		this.unsubscribeTransport = this.transport.onFrame((frame) => {
 			this.handleFrame(frame);
@@ -2928,6 +3711,7 @@ var AgentTransportBindingImpl = class {
 					const session = this.sessionFor("sync_transcript");
 					if (!session) return;
 					this.sendTranscriptReset(session);
+					this.supervisor?.replay();
 					return;
 				}
 				case "close":
@@ -2965,7 +3749,20 @@ var AgentTransportBindingImpl = class {
 			state,
 			cwd: frame.cwd
 		};
-		const commands = await agent.commands?.(harnessContext) ?? [];
+		const harnessCommands = await agent.commands?.(harnessContext) ?? [];
+		const profiles = await agent.agents?.(harnessContext) ?? null;
+		const supervisor = new ChildSupervisor({
+			agent,
+			cwd: frame.cwd,
+			profiles,
+			parentCommands: harnessCommands,
+			shellOptions: this.shellOptions,
+			prepareShell: this.prepareShell,
+			sessionOptions: this.sessionOptions,
+			notifyParentOnIdle: this.notifyParentOnIdle,
+			emit: (subagentFrame) => this.send(subagentFrame)
+		});
+		const commands = injectSubagentCommand(harnessCommands, supervisor.rootCommandNode());
 		const commandRegistry = new CommandRegistry();
 		for (const command of commands) commandRegistry.register(command);
 		const commandNames = commandRegistry.list().map((command) => command.name);
@@ -3014,6 +3811,8 @@ var AgentTransportBindingImpl = class {
 		});
 		sessionRef = session;
 		this.session = session;
+		supervisor.attachParent(session);
+		this.supervisor = supervisor;
 		this.currentAgent = agent;
 		this.currentCommandRegistry = commandRegistry;
 		this.currentCwd = frame.cwd;
@@ -3107,6 +3906,7 @@ var AgentTransportBindingImpl = class {
 		const agent = this.currentAgent;
 		const cwd = this.currentCwd;
 		try {
+			if (this.supervisor) await this.supervisor.dispose();
 			if (session) await session.dispose();
 			const pendingEnvironments = await Promise.allSettled(this.pendingEnvironmentsByHost.values());
 			const environments = new Set(this.environmentsByHost.values());
@@ -3122,6 +3922,7 @@ var AgentTransportBindingImpl = class {
 			this.unsubscribeSession?.();
 			this.unsubscribeSession = null;
 			this.session = null;
+			this.supervisor = null;
 			this.currentAgent = null;
 			this.environmentsByHost.clear();
 			this.pendingEnvironmentsByHost.clear();
@@ -3170,10 +3971,15 @@ var AgentTransportBindingImpl = class {
 	}
 	/** Backs `AgentServer.runCommandLine` — see its doc comment for the contract. */
 	async runCommandLine(shellId, name, args, opts) {
-		const environment = this.environmentForShell(shellId);
-		const agentSessionId = this.currentSessionId;
-		if (!environment || !agentSessionId) throw new Error("runCommandLine: session has no active shell environment");
-		if (!this.currentCommandNames.has(name)) throw new RunCommandLineCommandNotRegisteredError(name);
+		const parentEnvironment = this.environmentForShell(shellId);
+		const scope = parentEnvironment && this.currentSessionId ? {
+			environment: parentEnvironment,
+			commandNames: this.currentCommandNames,
+			agentSessionId: this.currentSessionId
+		} : this.supervisor?.environmentScopeForShell(shellId) ?? null;
+		if (!scope) throw new Error("runCommandLine: session has no active shell environment");
+		const { environment, agentSessionId } = scope;
+		if (!scope.commandNames.has(name)) throw new RunCommandLineCommandNotRegisteredError(name);
 		const words = [name, ...args].map(shellQuote).join(" ");
 		let script = words;
 		if (opts.stdin.length > 0) {
@@ -3213,7 +4019,7 @@ var AgentTransportBindingImpl = class {
 		}
 	}
 	hasShell(shellId) {
-		return this.environmentForShell(shellId) !== null;
+		return this.environmentForShell(shellId) !== null || (this.supervisor?.hasShell(shellId) ?? false);
 	}
 	async resolveEnvironment(ctx, handle) {
 		const agent = this.currentAgent;
@@ -3441,4 +4247,4 @@ function createProviderMap(providers) {
 	return map;
 }
 //#endregion
-export { AgentClient, AgentServer, AgentSession, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, ProviderStreamError, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AgentClient, AgentServer, AgentSession, ChildSupervisor, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, MAX_LIVE_SUBAGENTS, ProviderStreamError, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/stdio-transport.d.mts

@@ -1,4 +1,4 @@
-import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-DtBCCS_A.mjs";
+import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-BRqZoaeo.mjs";
 import { Readable, Writable } from "node:stream";
 //#region src/stdio-transport.d.ts
 declare function createStdioClientTransport(readable: Readable, writable: Writable): AgentClientTransport;

package/dist/{transport-DtBCCS_A.d.mts → transport-BRqZoaeo.d.mts}

@@ -180,12 +180,33 @@ interface AgentHostContext<State> extends AgentHarnessContext<State> {
   agentSessionId: string;
   metadata: AgentMetadata | null;
 }
+/**
+ * A named subagent configuration. Every field is an override on the parent's
+ * setup: omitted fields inherit the parent harness (system prompt), the
+ * parent's registered commands, the parent Host, and the parent model.
+ */
+interface SubagentProfile<State = unknown> {
+  name: string;
+  /** Shown in the spawn command help so the parent model can pick a profile. */
+  description: string;
+  systemPrompt?(ctx: AgentSystemPromptContext<State>): Promise<string> | string;
+  /** Derives the child's registered commands from the parent's list. */
+  commands?(parentCommands: Command[]): Command[];
+  /** Reject filesystem writes and process spawns on the child's Host. */
+  readonly?: boolean;
+  model?: ModelSelection;
+}
 interface AgentHarness<State = unknown> {
   name: string;
   initialState(): State;
   /** Return the same Host object for calls that target the same execution environment. */
   host(ctx: AgentHarnessContext<State> | AgentHostContext<State>): Host | Promise<Host>;
   commands?(ctx: AgentHarnessContext<State>): Promise<Command[]> | Command[];
+  /**
+   * Named subagent profiles for `demi agent`. Omitted: one implicit profile
+   * named `default` that fully inherits the parent's setup.
+   */
+  agents?(ctx: AgentHarnessContext<State>): Promise<SubagentProfile<State>[]> | SubagentProfile<State>[];
   systemPrompt(ctx: AgentSystemPromptContext<State>): Promise<string> | string;
   preamble?(ctx: AgentPromptContext<State>): Promise<string | null> | string | null;
   resolveReferences?(ctx: AgentReferenceResolveContext<State>, content: UserContentBlock[]): Promise<UserContentBlock[]> | UserContentBlock[];
@@ -370,6 +391,16 @@ interface ConversationSummary {
   createdAt: string;
   updatedAt: string;
 }
+/** One child agent session as seen on the parent connection. */
+interface SubagentJob {
+  subagentId: string;
+  parentSessionId: string;
+  description: string;
+  profile: string | null;
+  phase: 'running' | 'completed' | 'aborted' | 'error';
+  /** Present on `closed`: the child's last assistant text, at most 32 KiB. */
+  result?: string;
+}
 type ClientFrame = {
   type: 'open';
   provider: ProviderSelection;
@@ -489,6 +520,20 @@ type ServerFrame = {
   message: string;
   code?: string;
   diagnostics?: ProviderErrorDiagnostics;
+} | {
+  type: 'subagent';
+  event: 'started' | 'closed';
+  job: SubagentJob;
+} | {
+  type: 'subagent_transcript_reset';
+  subagentId: string;
+  blocks: Block[];
+  revision: number;
+} | {
+  type: 'subagent_transcript_patch';
+  subagentId: string;
+  patches: TranscriptPatch[];
+  revision: number;
 } | {
   type: 'closed';
 };
@@ -575,6 +620,18 @@ type ClientSessionEvent = {
   message: string;
   code?: string;
   diagnostics?: ProviderErrorDiagnostics;
+} | {
+  type: 'subagent';
+  event: 'started' | 'closed';
+  job: SubagentJob;
+} | {
+  type: 'subagent_transcript_reset';
+  subagentId: string;
+  blocks: Block[];
+} | {
+  type: 'subagent_transcript_patch';
+  subagentId: string;
+  patches: TranscriptPatch[];
 } | {
   type: 'opened';
 } | {
@@ -595,4 +652,4 @@ interface InProcessTransportPair {
 }
 declare function createInProcessTransportPair(): InProcessTransportPair;
 //#endregion
-export { AgentTool as A, TranscriptLog as B, AgentSessionCheckpoint as C, AgentSessionRestoreParams as D, AgentSessionParams as E, ModelSwitchApply as F, isRetryableCode as G, estimateTranscriptBlockTokens as H, SessionEvent as I, resolveRetryPolicy as K, SessionEventListener as L, AgentToolInvokeContext as M, AgentToolInvokeResult as N, AgentSessionStore as O, ExternalMutationReservation as P, CompactionWindow as R, AgentReferenceResolveContext as S, AgentSessionOptions as T, DEFAULT_TURN_RETRY_POLICY as U, TranscriptOptions as V, TurnRetryPolicy as W, AgentHarnessRuntime as _, createInProcessTransportPair as a, AgentMetadata as b, ConversationSummary as c, TranscriptPatch as d, AbortResult as f, AgentHarnessContext as g, AgentHarness as h, InProcessTransportPair as i, AgentToolContext as j, AgentSystemPromptContext as k, ServerFrame as l, AgentDisposeContext as m, AgentServerTransport as n, ClientFrame as o, AbortTarget as p, retryDelayMs as q, AgentTransport as r, ClientSessionEvent as s, AgentClientTransport as t, ShellCommandStatusLike as u, AgentHostContext as v, AgentSessionCloneParams as w, AgentPromptContext as x, AgentLifecycleEvent as y, DrainedTranscriptPatches as z };
+export { AgentSystemPromptContext as A, CompactionWindow as B, AgentReferenceResolveContext as C, AgentSessionParams as D, AgentSessionOptions as E, ExternalMutationReservation as F, DEFAULT_TURN_RETRY_POLICY as G, TranscriptLog as H, ModelSwitchApply as I, resolveRetryPolicy as J, TurnRetryPolicy as K, SessionEvent as L, AgentToolContext as M, AgentToolInvokeContext as N, AgentSessionRestoreParams as O, AgentToolInvokeResult as P, SessionEventListener as R, AgentPromptContext as S, AgentSessionCloneParams as T, TranscriptOptions as U, DrainedTranscriptPatches as V, estimateTranscriptBlockTokens as W, retryDelayMs as Y, AgentHarnessContext as _, createInProcessTransportPair as a, AgentLifecycleEvent as b, ConversationSummary as c, SubagentJob as d, TranscriptPatch as f, AgentHarness as g, AgentDisposeContext as h, InProcessTransportPair as i, AgentTool as j, AgentSessionStore as k, ServerFrame as l, AbortTarget as m, AgentServerTransport as n, ClientFrame as o, AbortResult as p, isRetryableCode as q, AgentTransport as r, ClientSessionEvent as s, AgentClientTransport as t, ShellCommandStatusLike as u, AgentHarnessRuntime as v, AgentSessionCheckpoint as w, AgentMetadata as x, AgentHostContext as y, SubagentProfile as z };

package/dist/{websocket-transport-DdfGgBjO.d.mts → websocket-transport-C6Y5CeLG.d.mts}

@@ -1,4 +1,4 @@
-import { F as ModelSwitchApply, b as AgentMetadata, c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-DtBCCS_A.mjs";
+import { I as ModelSwitchApply, c as ConversationSummary, n as AgentServerTransport, p as AbortResult, s as ClientSessionEvent, t as AgentClientTransport, x as AgentMetadata } from "./transport-BRqZoaeo.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 import { Block, UserContentBlock } from "@demicodes/core";
 //#region src/client.d.ts

package/dist/{websocket-transport-c6P3NBuf.mjs → websocket-transport-CIOotpd-.mjs}

@@ -304,8 +304,23 @@ var AgentClient = class {
 			case "shell_write_result":
 			case "audit":
 			case "retry_scheduled":
+			case "subagent":
 				this.emit(frame);
 				return;
+			case "subagent_transcript_reset":
+				this.emit({
+					type: "subagent_transcript_reset",
+					subagentId: frame.subagentId,
+					blocks: frame.blocks
+				});
+				return;
+			case "subagent_transcript_patch":
+				this.emit({
+					type: "subagent_transcript_patch",
+					subagentId: frame.subagentId,
+					patches: frame.patches
+				});
+				return;
 			case "conversations":
 				this.pendingConversationWaiters.shift()?.(frame.conversations);
 				return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,10 +19,11 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.18.0",
-    "@demicodes/provider": "^0.18.0",
-    "@demicodes/shell": "^0.18.0",
-    "@demicodes/utils": "^0.18.0"
+    "@demicodes/core": "^0.19.1",
+    "@demicodes/provider": "^0.19.1",
+    "@demicodes/shell": "^0.19.1",
+    "@demicodes/utils": "^0.19.1",
+    "zod": "^4.0.0"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",
@@ -43,8 +44,5 @@
     "directory": "packages/agent"
   },
   "homepage": "https://github.com/wspl/demi/tree/main/packages/agent#readme",
-  "bugs": "https://github.com/wspl/demi/issues",
-  "devDependencies": {
-    "zod": "^4.0.0"
-  }
+  "bugs": "https://github.com/wspl/demi/issues"
 }