@zvada/agent-server 0.3.11 → 0.3.13

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.3.13
+
+- Add opt-in `subagentMode: "turn"` for Claude Code and Codex app-server.
+  Native workers stay within the managed execution's lifetime and existing
+  permission broker. Unsupported harnesses reject this mode.
+- Preserve modern Claude Agent metadata and nested text, normalize Codex V1
+  task tools, and expose V2 native activity as a typed `SubagentPart`.
+- Require native cleanup before a managed Codex execution releases ownership,
+  including cancellation and failed startup. Unconfirmed cleanup prevents
+  session reuse. Managed Codex successors resume in a fresh native process.
+  Default interactive harness behavior remains unchanged.
+
+## 0.3.12
+
+- Report a Claude turn whose API call failed as an error. Claude Code ends it
+  as a `success` result flagged `is_error` (a rejected key, an exhausted quota,
+  an overloaded provider), with the failure as its text; it was reported as a
+  completed `end_turn` whose answer quoted the failure. The failure's text now
+  classifies the error (a 401 is `auth`).
+
 ## 0.3.11
 
 - Report a Claude turn stopped while a tool runs as `cancelled`. Claude Code

package/docs/harnesses.md

@@ -120,6 +120,13 @@ provide the cache breakdown without an additional native usage report.
 
 ## Known limitations (roadmap)
 
+- **Native subagents:** opt into `RunConfig.subagentMode: "turn"` for Claude
+  Code or Codex app-server. The parent collects results; native workers settle
+  before the engine releases the turn. Claude forwards nested worker text.
+  Codex emits task tools and typed `subagent` activity; it does not forward full
+  child transcripts. Managed Codex turns close the native process after cleanup
+  and resume saved context on the next turn. Default behavior is unchanged.
+  See [RFD 0002](rfds/0002-native-subagents.md) for the rehearsal and qualification.
 - **MCP servers** are supported by Claude and Codex app-server. Codex SDK
   passthrough remains unsupported. See [MCP configuration](consuming.md#configure-mcp-between-turns)
   for Codex home ownership, supported transports, and live-update behavior.

package/docs/rfds/0002-native-subagents.md

@@ -0,0 +1,197 @@
+# RFD 0002 — Native delegation within a managed turn
+
+**Status:** implemented; native Claude and Codex qualification passed on 2026-09-29.
+**Date:** 2026-09-29
+**Scope:** Claude Code and Codex app-server in agent-server and AGNT.
+**Baseline:** agent-server `7248c43`; AGNT `39df4fa9`.
+
+## Recommendation
+
+Support native delegation inside the existing logical engine turn. The parent
+assigns work, collects results and produces the final answer. The engine retains
+ownership until its native work finishes or is stopped. AGNT keeps using its
+existing turn-scoped credentials, permission bridge, persistence and cancellation.
+
+This is a smaller extension of [DESIGN D10](../../../../DESIGN.md#d10--built-in-turns-own-their-logical-session-through-cleanup).
+It does not require a second scheduler, child credential leases, a worker
+database, or a stream that remains active between managed turns. Independently
+running workers across later turns are outside this first contract.
+
+## What already works — observed
+
+Deus Machine already configures this engine with `forwardSubagentText: true`
+and renders nested subagent output. At `origin/main` `4e957a26c`, see
+`apps/agent-server/agents/core/engine.ts`,
+`apps/web/src/features/session/ui/blocks/SubagentGroupBlock.tsx` and
+`apps/backend/test/unit/services/event-persistence-integration.test.ts`.
+The last file tests nesting a worker message under its spawning tool. This is
+source evidence, not a new live execution.
+
+The engine already carries `ToolPart.subagent` and `parentToolCallId`; its
+`test/server/flows.test.ts` covers nested output. AGNT already round-trips these
+fields. Its two focused message suites passed **37 tests** during this rehearsal.
+
+[SessionAgent](../../src/core/agents/session-agent.ts) already reserves a session
+through `executeTurn` cleanup. AGNT's controller waits for its predecessor to
+drain before preparing a new credential and releases credentials in its existing
+`finally`. These are the owners to reuse.
+
+AGNT does not globally disable native delegation. Its explicit `toolAllowlist`
+rejects `Agent` and `Task`; QApp also omits them. AGNT's Claude SDK options omit
+Deus Machine's forwarding flag. Saying that the whole stack lacked subagents
+was too broad.
+
+## Pass 1 — the smallest apparent patch
+
+1. Enable Claude child-text forwarding in AGNT. Recognize modern `Agent` as
+   well as legacy `Task` in the Claude adapter.
+2. Normalize Codex's existing native delegation output.
+3. Permit delegation under AGNT's scoped tool policy.
+
+Steps 1–3 alone are insufficient. The following counterexamples determine the
+additional work; they do not justify a general background-worker platform.
+
+## Pass 2 — counterexamples and smallest corrections
+
+| Trigger and current path | Wrong result | Smallest correction and proof |
+| --- | --- | --- |
+| Claude returns its parent `result` while background work remains; `ClaudeGeneratorSession` closes the tap. | Late child output is lost or reaches the next tap after the host changes policy. | In the managed mode, enforce native foreground execution and qualify cleanup on the pinned SDK. Test cancellation plus a successor with changed policy. |
+| Codex emits root `turn/completed`; `executeTurn` ends its queue and removes listeners. | Child activity disappears; credentials can be released too early. | Track native descendants for this execution, separate parent completion from execution settlement, and retain the existing session reservation through cleanup. |
+| Merely delay Codex's queue end, leaving `turnEnded = true`. | `forceCancel` returns early, so cancellation can hang or falsely settle. | Make cancellation depend on execution settlement, target active owned native turns, and observe completion. Test cancel after the parent response. |
+| A Codex child requests approval. `bindRequests` currently declines every foreign thread id. | Owned children cannot use the existing permission broker. | Admit only descendants proven by native ownership; route them through the current turn's handler. Test an owned child and an unrelated thread. |
+| Treat `client.close()` or a stop request as proof of teardown. | Current `close()` marks itself closed before the OS process exits. | Await actual native completion or bounded subprocess teardown; qualify descendant tools too. Never report a clean stop from the local boolean alone. |
+| Set foreground behavior globally for all engine consumers. | Existing interactive Deus Machine behavior changes unintentionally. | Use one explicit managed-turn option, include it in native session configuration, and preserve the default for existing consumers. |
+| Wait for workers after the parent has already submitted its answer. | The final answer may never have used their results. | Require the parent to collect results. If it returns with outstanding work, stop that work and report incomplete execution; do not silently run another model turn. |
+
+The earlier synthetic probes reproduced omitted adapter events and late-tap
+routing, not a live permission escape. Artifacts remain under
+`.context/subagents-research/` and QApp's `.context/delegation-audit/`.
+
+## Pass 3 — revised implementation
+
+### Engine option and lifetime
+
+The opt-in `RunConfig.subagentMode: "turn"` preserves existing native behavior
+when omitted. Unsupported
+harnesses reject the request. Thread it through
+`src/protocol/config.ts`, `src/core/agents/base.ts`,
+`src/core/runtime/agent-runtime.ts` and native session configuration.
+A warm process must not silently retain an incompatible mode.
+
+The normal path remains one run: native workers execute, the parent receives
+their results, and the engine finishes after native cleanup. Multiple native
+workers may run concurrently where the pinned harness supports it; qualify that
+behavior rather than promising it from an SDK option.
+
+The adapter needs an execution-local record of owned native work, not a durable
+child-session service. Track starts, terminal outcomes and active native turn
+identifiers, including descendants. A spawn acknowledgement is not completion.
+On early parent exit or cancellation, stop remaining owned work before releasing
+ownership. Failure to establish cleanup must remain a failed/unconfirmed
+execution and prevent unsafe session reuse. Do not add automatic retries or
+background parent wake-ups.
+
+### Claude
+
+Use the native foreground control in managed mode and forward child text.
+The current [Claude documentation](https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background)
+documents `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`; verify the behavior against
+the pinned SDK **0.3.220**, including explicit background requests and
+cancellation. Reuse the existing message nesting.
+
+Changes belong in `claude-code/options.ts`, `claude-agent.ts`,
+`generator-session.ts` as required by that qualification, and the
+`subagentFromInput` branch in `claude-code/adapter.ts`. Do not build a separate
+Claude scheduler. If the native foreground control does not contain the pinned
+runtime, keep the managed capability disabled until that specific gap is fixed.
+
+### Codex
+
+The pinned CLI **0.153.4** emits V1 `collabAgentToolCall` and V2
+`subAgentActivity`. Both currently disappear in the adapters. V2 activity may
+arrive after its originating parent response. The
+[pinned app-server contract](https://github.com/openai/codex/blob/3d2ee51ca2d5db578f328aa75e20aa22c0197c9a/codex-rs/app-server/README.md)
+supports `turn/interrupt` for parent-owned V2 children too: use each child's
+active native turn, then observe its terminal outcome. Interrupting an already
+completed root is insufficient. Native background terminals have a separate
+cleanup operation; include child-owned terminals in cancellation qualification.
+
+Implement ownership, notification selection and drain behavior in
+`codex-app-server/codex-app-server-agent.ts`; add awaited process-exit fallback
+in `client.ts`. Use native parent links/read APIs to settle notification-order
+races, never permissive thread matching. Child approval handling stays on the
+existing broker.
+
+Normalize V1 calls in `codex-app-server/adapter.ts` and `codex-items.ts`.
+Preserve real native ids, results and task metadata. V2 is an activity, not a
+public tool invocation: add the small typed activity representation it needs to
+the existing Part/adapter/reducer path rather than inventing a tool call.
+Carry its native activity id, child thread id and observed kind. This is a
+persisted message part, not a new independently managed session. Full child
+transcript parity is not a prerequisite; unavailable transcripts stay explicit.
+
+### AGNT and review consumers
+
+AGNT enables the qualified managed mode in `AgentEngine.prepareTurn` and adds
+`forwardSubagentText`. Its existing controller and credential cleanup remain
+the owners. Extend existing part persistence only for the activity shape the
+engine actually emits; no new worker table is needed.
+
+Relax `Agent`/`Task` rejection only when child tools demonstrably obey the same
+Claude allowlist, including bypass mode. Gate this admission on an updated
+sidecar version. Codex's existing lack of custom `toolAllowlist` enforcement
+remains a separate limitation; this work must not claim to solve it.
+
+The parent decides what to test through skills, gives each worker the necessary
+context, waits for results and submits one report. Device workers share no
+simulator concurrently unless separate devices exist. QApp's evidence still
+comes through its trusted capture path. No review roles belong in the engine.
+
+## Checks that establish the feature
+
+- Adapter fixtures cover modern Claude `Agent`, legacy `Task`, Codex V1 and
+  V2, interleaved workers, native ids and honest outcomes.
+- Runtime tests cover early parent completion, child failure, cancellation while
+  waiting, owned/unrelated approvals, actual teardown, and a successor with
+  different credentials/MCP/policy. No old child reaches that successor.
+- Existing reducer, replay and AGNT JSON-part round trips retain nesting and
+  activity without a separate lifecycle database.
+- Live pinned Claude and Codex runs each delegate two tasks and incorporate both
+  results. Repeat through AGNT's real proxy/MCP path, including a denied child
+  tool for Claude. Prove stop behavior and absence of continued child execution.
+- Existing consumers without the managed option keep their native behavior.
+  A QApp review demonstrates worker evidence reaching the final report and
+  visible partial coverage on failure.
+
+## Implementation qualification
+
+The deterministic engine suite passes (907 tests). The opt-in live suite
+`test/core/live/subagents.live.test.ts` passes four real-model cases: Claude and
+Codex each delegate to two workers and incorporate both unique file values;
+each cancels a worker running a real shell command, confirms that PID stopped,
+and successfully runs a successor. Proof is retained in `.context/proof/subagents`.
+No simulator was used in these engine tests.
+
+Live testing found that Claude can return `error_during_execution` with
+`stop_reason: tool_use` on an acknowledged cancellation. The adapter now uses
+the confirmed interrupt marker to distinguish that from an execution failure.
+
+Codex can register a background terminal AFTER its thread becomes idle. An
+interrupt response and empty terminal list therefore cannot prove cleanup.
+Managed Codex turns close the app-server through stdin EOF after reconciliation,
+which invokes native thread/tool shutdown. Root SIGTERM alone left a real child
+command running on macOS. Forced exits or native cleanup warnings are unconfirmed
+and quarantine the logical session. A managed successor resumes persisted context
+in a fresh process; the default interactive mode retains its warm process.
+
+This contract covers native managed work. It does not turn arbitrary shell
+commands into an OS containment boundary; sandbox custody remains with the host.
+AGNT and QApp integration qualification is recorded in their own design documents.
+
+Repeated cancellation also consults persistent unconfirmed native cleanup after the wrapper turn has ended. The idle response of another harness must not erase that result in the host. AGNT cloud qualification additionally verified real child PID cleanup and a successful successor for both harnesses.
+
+Releasing a quarantined Codex session also refuses unconfirmed cleanup. A host
+must propagate that release failure before resetting the session or switching
+harnesses; otherwise a successor could bypass the same-harness admission guard.
+Deterministic regressions cover failure after normal parent completion, repeated
+release attempts, and successful release after confirmed cleanup.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.11",
+	"version": "0.3.13",
 	"description": "Harness-agnostic agent execution engine: run Claude Code, Codex (SDK/CLI + app-server), and any ACP agent behind one interface with a normalized event stream, multi-turn sessions, and resume. Root export is the wire contract; /core, /server, /client are the seats.",
 	"license": "MIT",
 	"type": "module",

package/src/core/agents/base.ts

@@ -54,6 +54,7 @@ export interface AgentExecuteOptions {
 	thinkingLevel?: ThinkingLevel;
 	permissionMode?: PermissionMode;
 	maxTurns?: number;
+	subagentMode?: "turn";
 	systemPromptAppend?: string;
 	resumeSessionId?: string;
 	resumeSessionAt?: string;

package/src/core/agents/claude-code/adapter.ts

@@ -97,6 +97,8 @@ type ClaudeMessage =
 			turn_cost_usd?: number | null;
 			stop_reason?: string | null;
 			is_error?: boolean;
+			/** On an `is_error` success, the API failure's text. */
+			result?: string;
 	  };
 
 type BlockKind = "text" | "reasoning" | "tool";
@@ -194,7 +196,7 @@ function toolResultContent(content: unknown): ToolResultContent[] | undefined {
 /**
  * SubagentMetadata from a spawning tool's input, shared by the streamed and
  * non-streaming paths. `subagent_type` in the input identifies a spawn on any
- * tool name; `Task` is Claude's own spawn tool and counts even before its
+ * tool name; Claude's `Agent` (formerly `Task`) also counts before its
  * input parses into anything useful (presence of `subagent` is what promotes
  * the part to `kind: "task"` — see protocol §3.5).
  */
@@ -205,7 +207,7 @@ function subagentFromInput(
 	const str = (key: string): string | undefined =>
 		typeof input[key] === "string" ? (input[key] as string) : undefined;
 	const type = str("subagent_type");
-	if (type === undefined && toolName !== "Task") return undefined;
+	if (type === undefined && toolName !== "Task" && toolName !== "Agent") return undefined;
 	const description = str("description");
 	const model = str("model");
 	return {
@@ -505,7 +507,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	}
 
 	private captureResult(msg: Extract<ClaudeMessage, { type: "result" }>): AdapterEvent[] {
-		this.succeeded = msg.subtype === "success";
+		this.succeeded = msg.subtype === "success" && !msg.is_error;
 		if (msg.usage) {
 			const creation = msg.usage.cache_creation;
 			this.usage = {
@@ -538,6 +540,11 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 			} else {
 				this.error = `Claude turn ended: ${msg.subtype}`;
 			}
+		} else if (msg.is_error) {
+			// A failed API call (a rejected key, an exhausted quota, an overloaded
+			// provider) ends the turn as a "success" whose text is the error. The
+			// text names the failure, so the runtime classifies it (401 -> auth).
+			this.error = msg.result || "Claude turn ended with an API error";
 		}
 		// Final authoritative gauge: the result knows the context-window size.
 		if (!msg.usage) return [];

package/src/core/agents/claude-code/claude-agent.ts

@@ -25,6 +25,7 @@ const CAPABILITIES: AgentCapabilities = {
 	images: true,
 	mcpServers: true,
 	permissionRequests: true,
+	turnScopedSubagents: true,
 };
 
 /** Convert our normalized input into Claude's message content. */
@@ -68,6 +69,7 @@ function sessionConfigFrom(
 		thinkingLevel: options.thinkingLevel,
 		permissionMode: options.permissionMode,
 		maxTurns: options.maxTurns,
+		subagentMode: options.subagentMode,
 		systemPromptAppend: options.systemPromptAppend,
 		resumeSessionId: options.resumeSessionId,
 		resumeSessionAt: options.resumeSessionAt,

package/src/core/agents/claude-code/options.ts

@@ -44,6 +44,7 @@ export interface ClaudeSessionConfig {
 	thinkingLevel?: ThinkingLevel;
 	permissionMode?: PermissionMode;
 	maxTurns?: number;
+	subagentMode?: "turn";
 	systemPromptAppend?: string;
 	resumeSessionId?: string;
 	resumeSessionAt?: string;
@@ -95,6 +96,7 @@ function buildEnv(config: ClaudeSessionConfig): Record<string, string | undefine
 		...process.env,
 		...(config.apiKey ? { ANTHROPIC_API_KEY: config.apiKey } : {}),
 		...config.env,
+		...(config.subagentMode === "turn" && { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1" }),
 	};
 }
 
@@ -156,6 +158,7 @@ export function buildClaudeOptions(
 	// this function returns, so those can never be clobbered (and the
 	// ClaudeSdkOptionOverrides type excludes them anyway).
 	if (overrides) Object.assign(options, overrides);
+	if (config.subagentMode === "turn") options.forwardSubagentText = true;
 
 	// Fable-class models withhold thinking plaintext by default: blocks stream
 	// structure + token estimates only, so every reasoning part arrives with

package/src/core/agents/claude-code/session-manager.ts

@@ -42,6 +42,7 @@ export function claudeSessionNeedsRestart(
 		(prev.maxTurns ?? 100) !== (next.maxTurns ?? 100) ||
 		(prev.idleTimeoutMs ?? 5 * 60_000) !== (next.idleTimeoutMs ?? 5 * 60_000) ||
 		Boolean(prev.disableTools) !== Boolean(next.disableTools) ||
+		prev.subagentMode !== next.subagentMode ||
 		configFingerprint(prev.env) !== configFingerprint(next.env)
 		// mcpServers deliberately absent: MCP changes hot-swap on the live
 		// session (`setMcpServers`) instead of restarting the subprocess.

package/src/core/agents/codex-app-server/adapter.ts

@@ -4,6 +4,7 @@ import {
 	type ReasoningPart,
 	type StopReason,
 	type StreamContext,
+	type SubagentPart,
 	type TextPart,
 	type TokenUsage,
 	type ToolPart,
@@ -11,6 +12,8 @@ import {
 	createReasoningPart,
 	createTextPart,
 	createToolPart,
+	generateUUIDv7,
+	setToolMeta,
 } from "../../../protocol/index.ts";
 import {
 	type CodexToolDescriptor,
@@ -31,6 +34,9 @@ import type { AdapterEvent, EventTransformer, TransformResult } from "../types.t
 interface CodexItem extends CodexToolItem {
 	type: string;
 	text?: string;
+	agentThreadId?: string;
+	agentPath?: string;
+	kind?: SubagentPart["activity"];
 }
 interface Notification {
 	method: string;
@@ -119,6 +125,8 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 
 	private openItem(item: CodexItem): AdapterEvent[] {
 		switch (item.type) {
+			case "subAgentActivity":
+				return this.activity(item);
 			case "agentMessage": {
 				const part = createTextPart(this.ctx, item.text ?? "", true);
 				this.partByItem.set(item.id, part);
@@ -142,6 +150,8 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	private completeItem(item: CodexItem): AdapterEvent[] {
 		const part = this.partByItem.get(item.id);
 		switch (item.type) {
+			case "subAgentActivity":
+				return this.activity(item);
 			case "agentMessage":
 			case "reasoning": {
 				const p = (part ??
@@ -161,12 +171,34 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 				const d = codexToolDescriptor(item.type);
 				if (!d) return [];
 				const tool = this.ensureTool(item, d);
+				setToolMeta(tool, d.meta(item));
 				completeToolPart(tool, d.result(item));
 				return [{ kind: "part-update", part: tool }];
 			}
 		}
 	}
 
+	private activity(item: CodexItem): AdapterEvent[] {
+		if (
+			!item.agentThreadId ||
+			!item.kind ||
+			!["started", "interacted", "interrupted", "completed"].includes(item.kind)
+		)
+			return [];
+		const existing = this.partByItem.get(item.id);
+		const part: SubagentPart = {
+			...this.ctx,
+			id: existing?.id ?? generateUUIDv7(),
+			type: "subagent",
+			nativeActivityId: item.id,
+			nativeThreadId: item.agentThreadId,
+			...(item.agentPath && { path: item.agentPath }),
+			activity: item.kind,
+		};
+		this.partByItem.set(item.id, part);
+		return [{ kind: existing ? "part-update" : "part-open", part }];
+	}
+
 	private textDelta(
 		itemId: string | undefined,
 		delta: string | undefined,

package/src/core/agents/codex-app-server/client.ts

@@ -51,6 +51,7 @@ export interface CodexAppServerClientOptions {
  */
 export class CodexAppServerClient {
 	private proc?: ChildProcess;
+	private shutdown?: Promise<boolean>;
 	private nextId = 1;
 	private buffer = "";
 	private readonly decoder = new StringDecoder("utf8");
@@ -62,6 +63,7 @@ export class CodexAppServerClient {
 	/** Bounded rolling tail of the subprocess's stderr — folded into the exit
 	 *  error so failures carry the CLI's own explanation. */
 	private stderrTail = "";
+	private nativeShutdownFailed = false;
 	/** Chunk-boundary-safe UTF-8 decoding for the stderr tail; reset per spawn. */
 	private stderrDecoder = new StringDecoder("utf8");
 
@@ -122,10 +124,13 @@ export class CodexAppServerClient {
 	}
 
 	close(): void {
+		if (this.shutdown) return;
 		const proc = this.proc;
 		const wasOpen = !this.exited;
 		this.proc = undefined;
 		this.exited = true;
+		// Forced process exit cannot attest that native child commands stopped.
+		this.shutdown = Promise.resolve(!proc);
 		for (const [id, p] of this.pending) {
 			if (p.timer) clearTimeout(p.timer);
 			p.reject(new Error(`codex app-server closed before '${p.method}'`));
@@ -135,6 +140,46 @@ export class CodexAppServerClient {
 		if (wasOpen) this.notifyClosed();
 	}
 
+	/** EOF invokes native thread/tool cleanup. Killing the server alone proves nothing about workers. */
+	closeAndWait(timeoutMs = 2_000): Promise<boolean> {
+		if (this.shutdown) return this.shutdown;
+		const proc = this.proc;
+		if (!proc) return Promise.resolve(true);
+		if (this.exited || proc.exitCode !== null || proc.signalCode !== null) {
+			this.shutdown = Promise.resolve(false);
+			return this.shutdown;
+		}
+		this.exited = true;
+		this.shutdown = new Promise<boolean>((resolve) => {
+			let forced = false;
+			const finish = (confirmed: boolean) => {
+				clearTimeout(killTimer);
+				clearTimeout(deadline);
+				proc.off("close", exited);
+				this.proc = undefined;
+				resolve(confirmed);
+			};
+			const exited = (code: number | null, signal: NodeJS.Signals | null) =>
+				finish(!forced && !this.nativeShutdownFailed && code === 0 && signal === null);
+			proc.once("close", exited);
+			const killTimer = setTimeout(() => {
+				forced = true;
+				proc.kill("SIGKILL");
+			}, timeoutMs);
+			const deadline = setTimeout(() => finish(false), timeoutMs * 2);
+			// In stdio mode SIGTERM bypasses Codex's async shutdown. EOF drains
+			// connection tasks and awaits shutdown_threads before a clean exit.
+			proc.stdin?.end();
+		});
+		for (const [id, p] of this.pending) {
+			if (p.timer) clearTimeout(p.timer);
+			p.reject(new Error(`codex app-server closed before '${p.method}'`));
+			this.pending.delete(id);
+		}
+		this.notifyClosed();
+		return this.shutdown;
+	}
+
 	private notifyClosed(error?: Error): void {
 		for (const handler of this.closeHandlers) handler(error);
 		this.closeHandlers.clear();
@@ -143,6 +188,7 @@ export class CodexAppServerClient {
 	private start(): void {
 		if (this.proc && !this.exited) return;
 		this.exited = false;
+		this.shutdown = undefined;
 		const spawnProcess = this.opts.spawnProcess ?? nodeSpawn;
 		const proc = spawnProcess(this.opts.codexPath ?? "codex", ["app-server"], {
 			cwd: this.opts.cwd,
@@ -151,6 +197,7 @@ export class CodexAppServerClient {
 		});
 		this.proc = proc;
 		this.stderrTail = "";
+		this.nativeShutdownFailed = false;
 		this.stderrDecoder = new StringDecoder("utf8");
 		proc.stdout?.on("data", (chunk: Buffer) => this.onStdout(chunk));
 		proc.stdin?.on("error", (err) => this.onExit(err));
@@ -161,7 +208,13 @@ export class CodexAppServerClient {
 		// from a crash for the integrator staring at the turn error. Decoded
 		// via StringDecoder so a UTF-8 sequence split across chunks survives.
 		proc.stderr?.on("data", (chunk: Buffer) => {
-			this.stderrTail = (this.stderrTail + this.stderrDecoder.write(chunk)).slice(-STDERR_TAIL_MAX);
+			const text = this.stderrTail + this.stderrDecoder.write(chunk);
+			// The pinned native server logs these cleanup failures but still exits 0.
+			if (
+				/failed to submit Shutdown|timed out waiting for .*shut down|shutdown timed out/.test(text)
+			)
+				this.nativeShutdownFailed = true;
+			this.stderrTail = text.slice(-STDERR_TAIL_MAX);
 		});
 		proc.on("error", (err) => this.onExit(err));
 		// Build the exit error on CLOSE, not exit: `exit` can fire before the

package/src/core/agents/codex-app-server/codex-app-server-agent.ts

@@ -30,6 +30,7 @@ import {
 	codexMcpServers,
 	writeCodexMcpServers,
 } from "./mcp.ts";
+import { CodexTurnSubagents } from "./subagents.ts";
 
 const CAPABILITIES: AgentCapabilities = {
 	multiTurn: true,
@@ -40,6 +41,7 @@ const CAPABILITIES: AgentCapabilities = {
 	images: true,
 	mcpServers: true,
 	permissionRequests: true,
+	turnScopedSubagents: true,
 };
 
 export interface AppServerSession {
@@ -49,6 +51,7 @@ export interface AppServerSession {
 	approvalPolicy: string;
 	sandbox: string;
 	systemPromptAppend?: string;
+	subagentMode?: "turn";
 	envFingerprint: string;
 	/** Native model connections retain the identity used at their first handshake. */
 	authFingerprint?: string;
@@ -63,6 +66,7 @@ interface AppServerTurn {
 	auth?: CodexAppServerAuth;
 	permissionHandler?: PermissionRequestHandler;
 	signal: AbortSignal;
+	subagents?: CodexTurnSubagents;
 }
 
 export function appServerSessionCompatible(
@@ -76,6 +80,7 @@ export function appServerSessionCompatible(
 			existing.approvalPolicy === approvalPolicyFor(options) &&
 			existing.sandbox === mapSandbox(options.permissionMode) &&
 			(existing.systemPromptAppend ?? "") === (options.systemPromptAppend ?? "") &&
+			existing.subagentMode === options.subagentMode &&
 			existing.envFingerprint === configFingerprint(options.env) &&
 			(!options.resumeSessionId || options.resumeSessionId === existing.threadId),
 	);
@@ -231,6 +236,7 @@ export class CodexAppServerAgent extends SessionAgent {
 	readonly capabilities = CAPABILITIES;
 	private readonly sessions = new SessionStore<AppServerSession>();
 	private readonly invalidatedClients = new WeakSet<CodexAppServerClient>();
+	private readonly unsettledSessions = new Map<string, CodexAppServerClient>();
 	/** Home ownership outlives idle process eviction and failed preparation. */
 	private readonly mcpHomes = new Map<string, string>();
 	/** A cancel acknowledgement belongs to one invocation, even after it drains. */
@@ -288,7 +294,9 @@ export class CodexAppServerAgent extends SessionAgent {
 				(await this.agentOptions.resolveCliPath?.()) ?? process.env.CODEX_CLI_PATH ?? "codex",
 			cwd: options.cwd,
 			env: options.env ? ({ ...process.env, ...options.env } as NodeJS.ProcessEnv) : process.env,
-			...(turn.auth?.type === "chatgptAuthTokens" && { experimentalApi: true }),
+			...((turn.auth?.type === "chatgptAuthTokens" || options.subagentMode === "turn") && {
+				experimentalApi: true,
+			}),
 		};
 		signal.throwIfAborted();
 		const client =
@@ -305,6 +313,7 @@ export class CodexAppServerAgent extends SessionAgent {
 			approvalPolicy,
 			sandbox,
 			systemPromptAppend: options.systemPromptAppend,
+			subagentMode: options.subagentMode,
 			envFingerprint: configFingerprint(options.env),
 			authFingerprint: identity,
 			turn,
@@ -327,6 +336,15 @@ export class CodexAppServerAgent extends SessionAgent {
 			if (options.model) startParams.model = options.model;
 			if (options.systemPromptAppend)
 				startParams.developerInstructions = options.systemPromptAppend;
+			if (options.subagentMode === "turn") {
+				startParams.config = { "features.multi_agent": true };
+				startParams.developerInstructions = [
+					options.systemPromptAppend,
+					"Collect the results of every subagent before ending your turn. Stop any worker you no longer need. Delegated work cannot continue after this task completes.",
+				]
+					.filter(Boolean)
+					.join("\n\n");
+			}
 
 			const method = resumeThreadId ? "thread/resume" : "thread/start";
 			const result = (await client
@@ -466,7 +484,14 @@ export class CodexAppServerAgent extends SessionAgent {
 			const requestThread = params.threadId ?? params.conversationId;
 			const v2 = method.startsWith("item/");
 			const decline = v2 ? { decision: "decline" } : { decision: "denied" };
-			if (requestThread && requestThread !== session.threadId) return decline;
+			if (requestThread && requestThread !== session.threadId) {
+				if (
+					typeof requestThread !== "string" ||
+					!turn?.subagents ||
+					!(await turn.subagents.owns(requestThread).catch(() => false))
+				)
+					return decline;
+			}
 			const handler = turn?.permissionHandler;
 			if (!handler || turn?.signal.aborted) return decline;
 			const decision = await handler(approvalToolCall(method, params));
@@ -511,8 +536,16 @@ export class CodexAppServerAgent extends SessionAgent {
 		const unsubscribe: Array<() => void> = [];
 		let session: AppServerSession | undefined;
 		let turnEnded = false;
+		let parentEnded = false;
+		let managedCompletion: Promise<boolean> | undefined;
 		try {
 			controller.signal.throwIfAborted();
+			const unsettled = this.unsettledSessions.get(options.sessionId);
+			if (unsettled) {
+				if (!(await unsettled.closeAndWait()))
+					throw new Error("Previous Codex execution has not stopped");
+				this.unsettledSessions.delete(options.sessionId);
+			}
 			const requestedMcp = codexMcpServers(snapshotMcpServers(options.mcpServers));
 			const mcpServers = this.managedMcpHome(options, Object.keys(requestedMcp).length > 0)
 				? requestedMcp
@@ -527,7 +560,17 @@ export class CodexAppServerAgent extends SessionAgent {
 			});
 			const threadId = session.threadId;
 			const client = session.client;
-			const abortPreparation = () => client.close();
+			if (options.subagentMode === "turn") {
+				turn.subagents = new CodexTurnSubagents(
+					client,
+					threadId,
+					this.agentOptions.cancelGraceMs ?? 2_000,
+				);
+			}
+			const abortPreparation = () => {
+				if (turn.subagents) void client.closeAndWait();
+				else client.close();
+			};
 			controller.signal.addEventListener("abort", abortPreparation, { once: true });
 			try {
 				controller.signal.throwIfAborted();
@@ -545,6 +588,47 @@ export class CodexAppServerAgent extends SessionAgent {
 			}
 
 			let turnId: string | undefined;
+			const finishManaged = (): Promise<boolean> => {
+				if (managedCompletion) return managedCompletion;
+				managedCompletion = (async () => {
+					let confirmed = true;
+					let failure: unknown;
+					const graceMs = this.agentOptions.cancelGraceMs ?? 2_000;
+					const deadline = setTimeout(() => {
+						void client.closeAndWait(graceMs);
+					}, graceMs * 5);
+					try {
+						if (!parentEnded) {
+							// A startup interrupt only acknowledges submission, not native settlement.
+							if (!turnId) throw new Error("Codex cancelled before turn admission was observed");
+							await client.request("turn/interrupt", { threadId, turnId }, graceMs);
+						}
+						const unfinished = await turn.subagents!.settle();
+						// Native terminal registration can land after turn/completed and
+						// after an empty terminal inventory. EOF awaits native thread/tool
+						// shutdown; an idle snapshot alone cannot release a managed turn.
+						confirmed = await client.closeAndWait(graceMs);
+						if (!confirmed) throw new Error("Codex native cleanup was not confirmed");
+						if (unfinished && !controller.signal.aborted) {
+							failure = new Error(
+								"Parent finished with outstanding subagent work; workers were stopped and the result is incomplete",
+							);
+						}
+					} catch (error) {
+						failure = error;
+						confirmed = await client.closeAndWait(graceMs);
+						if (!confirmed) this.unsettledSessions.set(options.sessionId, client);
+					} finally {
+						clearTimeout(deadline);
+					}
+					turnEnded = true;
+					if (controller.signal.aborted) queue.fail(new Error("turn aborted"));
+					else if (failure) queue.fail(failure);
+					else queue.end();
+					return confirmed;
+				})();
+				return managedCompletion;
+			};
 			const forceCancel = () => {
 				if (turnEnded) return;
 				queue.fail(new Error("turn aborted"));
@@ -553,6 +637,10 @@ export class CodexAppServerAgent extends SessionAgent {
 			const onAbort = () => {
 				clearStall();
 				if (interruptState.acknowledgement) return;
+				if (turn.subagents) {
+					interruptState.acknowledgement = finishManaged();
+					return;
+				}
 				if (!turnId) {
 					interruptState.acknowledgement = Promise.resolve(false);
 					forceCancel();
@@ -574,6 +662,7 @@ export class CodexAppServerAgent extends SessionAgent {
 
 			unsubscribe.push(
 				client.onNotification((n) => {
+					turn.subagents?.observe(n);
 					if (n.params.threadId && n.params.threadId !== threadId) return;
 					if (n.method === "turn/started") {
 						const turn = n.params.turn as { id?: string } | undefined;
@@ -581,6 +670,12 @@ export class CodexAppServerAgent extends SessionAgent {
 							turnId = turn.id;
 						}
 					}
+					if (appServerNotificationEndsTurn(n) && turn.subagents) {
+						parentEnded = n.method === "turn/completed";
+						queue.push(n);
+						void finishManaged();
+						return;
+					}
 					if (appServerNotificationEndsTurn(n)) turnEnded = true;
 					if (turnEnded && controller.signal.aborted) {
 						queue.fail(new Error("turn aborted"));
@@ -602,13 +697,14 @@ export class CodexAppServerAgent extends SessionAgent {
 			);
 			// If the subprocess dies mid-turn, fail the turn instead of hanging.
 			unsubscribe.push(
-				client.onClose((err) =>
+				client.onClose((err) => {
+					if (managedCompletion) return;
 					queue.fail(
 						controller.signal.aborted
 							? new Error("turn aborted")
 							: (err ?? new Error("codex app-server exited mid-turn")),
-					),
-				),
+					);
+				}),
 			);
 
 			controller.signal.addEventListener("abort", onAbort, { once: true });
@@ -628,7 +724,8 @@ export class CodexAppServerAgent extends SessionAgent {
 			}
 			client.request("turn/start", turnParams).catch((err: unknown) => {
 				if (controller.signal.aborted) {
-					forceCancel();
+					if (turn.subagents) void finishManaged();
+					else forceCancel();
 					return;
 				}
 				queue.push({ method: "error", params: { message: String(err) } });
@@ -641,6 +738,11 @@ export class CodexAppServerAgent extends SessionAgent {
 		} catch (error) {
 			throw controller.signal.aborted ? new Error("turn aborted") : error;
 		} finally {
+			if (managedCompletion) await managedCompletion;
+			// Every exit owns cleanup, including turn/start failure and iterator.return().
+			if (options.subagentMode === "turn" && session && !(await session.client.closeAndWait())) {
+				this.unsettledSessions.set(options.sessionId, session.client);
+			}
 			turnEnded = true;
 			clearStall();
 			if (cancelTimer) clearTimeout(cancelTimer);
@@ -664,7 +766,13 @@ export class CodexAppServerAgent extends SessionAgent {
 		// set on a later microtask, so reading afterwards would race that drain.
 		const controllers = [...(this.inflight.get(sessionId) ?? [])];
 		const base = await super.cancel(sessionId);
-		if (!base.hadTurn) return base;
+		if (!base.hadTurn) {
+			const unsettled = this.unsettledSessions.get(sessionId);
+			if (!unsettled) return base;
+			const confirmed = await unsettled.closeAndWait();
+			if (confirmed) this.unsettledSessions.delete(sessionId);
+			return { confirmed, hadTurn: false };
+		}
 		const acknowledgements = await Promise.all(
 			controllers.map(
 				(controller) => this.turnInterruptState.get(controller)?.acknowledgement ?? false,
@@ -691,6 +799,13 @@ export class CodexAppServerAgent extends SessionAgent {
 	}
 
 	override async release(sessionId: string): Promise<void> {
+		// A host may release this harness before switching providers. Do not let
+		// that path discard ownership while managed child cleanup is unconfirmed.
+		const managed =
+			this.unsettledSessions.has(sessionId) ||
+			this.sessions.get(sessionId)?.subagentMode === "turn";
+		if (managed && !(await this.cancel(sessionId)).confirmed)
+			throw new Error("Codex native cleanup was not confirmed; cannot release the session");
 		await super.release(sessionId);
 		this.sessions.close(sessionId);
 		for (const [home, owner] of this.mcpHomes) {

package/src/core/agents/codex-app-server/subagents.ts

@@ -0,0 +1,201 @@
+import type { CodexAppServerClient, CodexNotification } from "./client.ts";
+
+interface NativeThread {
+	id: string;
+	parentThreadId?: string | null;
+	status?: { type: string };
+	source?: { subagent?: { thread_spawn?: { parent_thread_id?: string } } } | string;
+	turns?: Array<{ id: string; status: string }>;
+}
+
+function parentOf(thread: NativeThread): string | undefined {
+	return (
+		thread.parentThreadId ??
+		(typeof thread.source === "object"
+			? thread.source.subagent?.thread_spawn?.parent_thread_id
+			: undefined)
+	);
+}
+
+/** Native ownership and cleanup for ONE execution; scheduling stays in Codex. */
+export class CodexTurnSubagents {
+	private readonly parents = new Map<string, string>();
+	private readonly candidates = new Set<string>();
+	private readonly active = new Set<string>();
+	private activeAtParentEnd = new Set<string>();
+
+	constructor(
+		private readonly client: CodexAppServerClient,
+		private readonly root: string,
+		private readonly timeoutMs: number,
+	) {}
+
+	observe(notification: CodexNotification): void {
+		const id = notification.params.threadId;
+		if (id && id !== this.root) {
+			if (notification.method === "turn/started") this.active.add(id);
+			if (notification.method === "turn/completed") this.active.delete(id);
+			if (notification.method === "thread/status/changed") {
+				const status = notification.params.status as { type?: string } | undefined;
+				if (status?.type === "active") this.active.add(id);
+				else if (status?.type) this.active.delete(id);
+			}
+		}
+		if (id === this.root && notification.method === "turn/completed")
+			this.activeAtParentEnd = new Set(this.active);
+		if (notification.method === "thread/started") {
+			const thread = notification.params.thread as NativeThread | undefined;
+			const parent = thread && parentOf(thread);
+			if (thread?.id && parent) {
+				this.parents.set(thread.id, parent);
+				this.candidates.add(thread.id);
+				if (thread.status?.type === "active") this.active.add(thread.id);
+			}
+		}
+		if (notification.params.threadId !== this.root) return;
+		const item = notification.params.item as
+			| {
+					type?: string;
+					agentThreadId?: string;
+					receiverThreadIds?: string[];
+					agentsStates?: Record<string, { status: string }>;
+			  }
+			| undefined;
+		if (item?.type === "subAgentActivity" && item.agentThreadId)
+			this.candidates.add(item.agentThreadId);
+		if (item?.type === "collabAgentToolCall") {
+			for (const id of item.receiverThreadIds ?? []) this.candidates.add(id);
+			for (const [id, state] of Object.entries(item.agentsStates ?? {})) {
+				if (state.status === "running" || state.status === "pendingInit") this.active.add(id);
+				else this.active.delete(id);
+			}
+		}
+	}
+
+	private async read(id: string): Promise<NativeThread> {
+		const result = (await this.client.request(
+			"thread/read",
+			{ threadId: id, includeTurns: true },
+			this.timeoutMs,
+		)) as { thread?: NativeThread };
+		if (result.thread?.id !== id)
+			throw new Error("Codex did not confirm the requested child thread");
+		const parent = parentOf(result.thread);
+		if (parent) this.parents.set(id, parent);
+		return result.thread;
+	}
+
+	async owns(id: string): Promise<boolean> {
+		const visited = new Set<string>();
+		let current = id;
+		while (current !== this.root) {
+			if (visited.has(current) || visited.size >= 32) return false;
+			visited.add(current);
+			const parent = this.parents.get(current) ?? parentOf(await this.read(current));
+			if (!parent) return false;
+			current = parent;
+		}
+		if (id !== this.root) this.candidates.add(id);
+		return true;
+	}
+
+	private async descendants(): Promise<NativeThread[]> {
+		// The native inventory closes missed/start-notification races, including nested workers.
+		let cursor: string | undefined;
+		const cursors = new Set<string>();
+		do {
+			const page = (await this.client.request(
+				"thread/loaded/list",
+				{
+					limit: 100,
+					...(cursor && { cursor }),
+				},
+				this.timeoutMs,
+			)) as { data?: string[]; nextCursor?: string | null };
+			if (!Array.isArray(page.data)) throw new Error("Codex did not return its child inventory");
+			for (const id of page.data) this.candidates.add(id);
+			cursor = page.nextCursor ?? undefined;
+			if (cursor && cursors.has(cursor)) throw new Error("Codex repeated a child inventory cursor");
+			if (cursor) cursors.add(cursor);
+			if (this.candidates.size > 512)
+				throw new Error("Codex child inventory exceeds the managed turn limit");
+		} while (cursor);
+		const threads: NativeThread[] = [];
+		for (const id of this.candidates) {
+			if (id !== this.root && (await this.owns(id))) threads.push(await this.read(id));
+		}
+		return threads;
+	}
+
+	/** Root must have stopped first. Returns whether it left unfinished delegated work. */
+	async settle(): Promise<boolean> {
+		let unfinished = false;
+		for (const id of this.activeAtParentEnd) {
+			if (await this.owns(id)) unfinished = true;
+		}
+		let idleInventory: string | undefined;
+		for (let pass = 0; pass < 8; pass++) {
+			let stoppedWork = false;
+			const descendants = await this.descendants();
+			for (const thread of descendants) {
+				if (!thread.status) throw new Error("Codex child liveness is unknown");
+				if (thread.status.type === "active") {
+					unfinished = true;
+					stoppedWork = true;
+					const active = thread.turns
+						?.slice()
+						.reverse()
+						.find((turn) => turn.status === "inProgress");
+					// Empty IDs are native startup interrupts, acknowledged on submission.
+					// The read below and final EOF cleanup still have to establish settlement.
+					// A worker can finish naturally between the inventory and the interrupt.
+					await this.client
+						.request(
+							"turn/interrupt",
+							{ threadId: thread.id, turnId: active?.id ?? "" },
+							this.timeoutMs,
+						)
+						.catch(async (error) => {
+							if ((await this.read(thread.id)).status?.type !== "idle") throw error;
+						});
+					const stopped = await this.read(thread.id);
+					if (!stopped.status || stopped.status.type === "active")
+						throw new Error("Codex child interrupt was not confirmed");
+				}
+				if (thread.status.type === "notLoaded") continue;
+				const terminals = (await this.client.request(
+					"thread/backgroundTerminals/list",
+					{ threadId: thread.id },
+					this.timeoutMs,
+				)) as { data?: unknown[] };
+				if (!Array.isArray(terminals.data))
+					throw new Error("Codex child terminal liveness is unknown");
+				if (terminals.data.length) {
+					unfinished = true;
+					stoppedWork = true;
+					await this.client.request(
+						"thread/backgroundTerminals/clean",
+						{ threadId: thread.id },
+						this.timeoutMs,
+					);
+					const remaining = (await this.client.request(
+						"thread/backgroundTerminals/list",
+						{ threadId: thread.id },
+						this.timeoutMs,
+					)) as { data?: unknown[] };
+					if (!Array.isArray(remaining.data) || remaining.data.length)
+						throw new Error("Codex child terminals did not stop");
+				}
+			}
+			// Interrupting a worker may race its final spawn. Reconcile the native
+			// inventory after stops, while the root can no longer create new work.
+			const inventory = descendants
+				.map((thread) => thread.id)
+				.sort()
+				.join("\n");
+			if (!stoppedWork && inventory === idleInventory) return unfinished;
+			idleInventory = stoppedWork ? undefined : inventory;
+		}
+		throw new Error("Codex descendants did not settle within the managed cleanup bound");
+	}
+}

package/src/core/agents/codex-items.ts

@@ -23,6 +23,10 @@ export interface CodexToolItem {
 	result?: unknown;
 	error?: { message?: string } | string;
 	query?: string;
+	receiverThreadIds?: string[];
+	prompt?: string | null;
+	model?: string | null;
+	agentsStates?: Record<string, { status: string; message?: string | null }>;
 }
 
 export interface CodexToolDescriptor {
@@ -60,6 +64,27 @@ function stringifyMcpResult(result: unknown): string {
 const failed = (item: CodexToolItem) => item.status === "failed";
 
 export const CODEX_TOOL_ITEMS: Record<string, CodexToolDescriptor> = {
+	collabAgentToolCall: {
+		toolName: (item) => item.tool ?? "collabAgentToolCall",
+		input: (item) => ({
+			...(item.prompt != null && { prompt: item.prompt }),
+			...(item.model != null && { model: item.model }),
+			receiverThreadIds: item.receiverThreadIds ?? [],
+		}),
+		meta: (item) => ({
+			kind: "task",
+			...(item.tool === "spawnAgent" && {
+				subagent: {
+					...(item.model && { model: item.model }),
+					...(item.receiverThreadIds?.[0] && { agentId: item.receiverThreadIds[0] }),
+				},
+			}),
+		}),
+		result: (item) => ({
+			output: JSON.stringify(item.agentsStates ?? {}),
+			isError: failed(item) || item.status === "interrupted",
+		}),
+	},
 	commandExecution: {
 		toolName: () => "shell",
 		input: (item) => ({ command: item.command ?? "" }),
@@ -104,6 +129,8 @@ export const CODEX_TOOL_ITEMS: Record<string, CodexToolDescriptor> = {
 /** Map either protocol's item-type spelling onto a descriptor. */
 export function codexToolDescriptor(itemType: string): CodexToolDescriptor | undefined {
 	switch (itemType) {
+		case "collabAgentToolCall":
+			return CODEX_TOOL_ITEMS.collabAgentToolCall;
 		case "command_execution":
 		case "commandExecution":
 			return CODEX_TOOL_ITEMS.commandExecution;

package/src/core/agents/session-agent.ts

@@ -21,6 +21,9 @@ export abstract class SessionAgent extends BaseAgent {
 	): AsyncIterableIterator<RawAgentEvent> {
 		const { sessionId } = options;
 		if (this.terminated) throw new Error("Agent has been terminated");
+		if (options.subagentMode && !this.capabilities.turnScopedSubagents) {
+			throw new Error(`${this.harness} does not support turn-scoped subagents`);
+		}
 		if (this.activeSessions.has(sessionId)) throw new TurnActiveError(sessionId);
 		this.activeSessions.add(sessionId);
 		const controller = this.trackTurn(sessionId, options.signal);

package/src/core/runtime/agent-runtime.ts

@@ -396,6 +396,7 @@ export class AgentRuntime {
 			thinkingLevel: config.thinkingLevel,
 			permissionMode: config.permissionMode,
 			maxTurns: config.maxTurns,
+			subagentMode: config.subagentMode,
 			systemPromptAppend: config.systemPromptAppend,
 			resumeSessionId: config.resumeSessionId,
 			resumeSessionAt: config.resumeSessionAt,

package/src/protocol/config.ts

@@ -57,6 +57,8 @@ export const RunConfigSchema = z.object({
 	additionalDirectories: z.array(z.string()).optional(),
 	systemPromptAppend: z.string().optional(),
 	maxTurns: z.number().int().positive().optional(),
+	/** Native workers must settle before this managed execution releases its context. */
+	subagentMode: z.literal("turn").optional(),
 	permissionMode: PermissionModeSchema.optional(),
 	/**
 	 * Native session/thread id to resume (from a prior `session.created`). When

package/src/protocol/guards.ts

@@ -14,7 +14,7 @@
 import type { DecodedLifecycleEvent, UnknownEvent } from "./lifecycle.ts";
 import type { Part, UnknownPart } from "./parts.ts";
 
-export const PART_TYPES = ["text", "reasoning", "tool", "image", "file"] as const;
+export const PART_TYPES = ["text", "reasoning", "tool", "subagent", "image", "file"] as const;
 
 export function isKnownPartType(type: unknown): type is (typeof PART_TYPES)[number] {
 	return typeof type === "string" && (PART_TYPES as readonly string[]).includes(type);

package/src/protocol/harness.ts

@@ -46,5 +46,7 @@ export const AgentCapabilitiesSchema = z.object({
 	mcpServers: z.boolean(),
 	/** Can raise interactive `permission.requested` round-trips mid-turn. */
 	permissionRequests: z.boolean(),
+	/** Supports native delegation contained within the current execution. */
+	turnScopedSubagents: z.boolean().optional(),
 });
 export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;

package/src/protocol/parts.ts

@@ -81,6 +81,16 @@ export const ToolPartSchema = PartBase.extend({
 });
 export type ToolPart = z.infer<typeof ToolPartSchema>;
 
+/** Native worker activity, including harnesses without a public spawning tool call. */
+export const SubagentPartSchema = PartBase.extend({
+	type: z.literal("subagent"),
+	nativeActivityId: z.string(),
+	nativeThreadId: z.string(),
+	path: z.string().optional(),
+	activity: z.enum(["started", "interacted", "interrupted", "completed"]),
+});
+export type SubagentPart = z.infer<typeof SubagentPartSchema>;
+
 /**
  * Exactly one of `data` (base64) | `url` — ENFORCED, not merely documented: a
  * payload-less blob part renders as a broken image, and one carrying both
@@ -112,6 +122,7 @@ export const PartSchema = z.discriminatedUnion("type", [
 	TextPartSchema,
 	ReasoningPartSchema,
 	ToolPartSchema,
+	SubagentPartSchema,
 	ImagePartSchema,
 	FilePartSchema,
 ]);