@inixiative/agent-session 0.6.3 → 0.6.5

package/README.md

@@ -114,6 +114,30 @@ session.onToolRequest(async (call) => {
   A turn timeout does not withdraw a pending Claude ask; `interruptNative()` does.
 - A fork starts with a snapshot of the parent's gates.
 
+## Subagents
+
+A subagent's activity reaches `onEvent`, but never becomes part of a turn:
+
+- **Outside every admission.** Every subagent event, lifecycle included,
+  carries `unattributedReason: "subagent"`. It is never in a turn's
+  `result.events` and never its `content`. This holds whichever turn is in
+  flight, because a background subagent outlives the turn that started it.
+- **`parentToolUseId`** names the parent's tool call that spawned it. On
+  Claude this is the frame's `parent_tool_use_id`, with the native envelope
+  kept in `raw`. On Codex it is the collab `spawnAgent` item.
+- **`kind: "subagent"`** carries its lifecycle in `subagent`:
+  - `phase`: started, progress, updated or ended;
+  - identity and shape: `taskId`, `toolUseId`, `parentTaskId`, `agentType`,
+    `depth`, `backgrounded`;
+  - outcome: `status`, `summary`, `prompt`, and running `usage`.
+- **Claude** builds the lifecycle from its `system` task frames for
+  `task_type: "local_agent"`. Background shells, monitors and workflows are
+  tasks too, and they are not reported as subagents.
+- **Codex** reports `started` on the spawn and `ended` on `closeAgent`, plus
+  `updated` (with the turn's status) as each child turn ends. Child threads
+  carry their final messages as text; their other items stay diagnostics.
+  Approval requests from child threads are not routed to gates yet.
+
 ## Primed decision sessions
 
 One live, warm session per middleware role, primed once with its role

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.78",
+    "@inixiative/config": "^0.5.83",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-code-session.ts

@@ -57,6 +57,7 @@ import type {
   SessionResult,
   SessionSendOptions,
   SessionTokens,
+  SubagentLifecycle,
   ToolDecision,
   ToolGate,
   ToolRequest,
@@ -314,6 +315,8 @@ export class ClaudeCodeSession implements HarnessSession {
    * are distinct compactions.
    */
   private _seenBoundaries = new Set<string>();
+  /** Task ids whose task_started was a subagent (local_agent); later task frames carry no type. */
+  private _agentTasks = new Set<string>();
 
   // -- Turn queue --
   private _queue: QueuedTurn[] = [];
@@ -1104,6 +1107,34 @@ export class ClaudeCodeSession implements HarnessSession {
       return;
     }
 
+    // A subagent's frames and lifecycle are never part of an admission, whichever turn is in flight
+    // (a background subagent outlives the turn that started it): they reach handlers tagged
+    // `subagent`, with the spawning call in `parentToolUseId`.
+    const parentToolUseId =
+      typeof raw.parent_tool_use_id === 'string' && raw.parent_tool_use_id
+        ? raw.parent_tool_use_id
+        : undefined;
+    const lifecycle = this._subagentLifecycle(raw);
+    if (parentToolUseId || lifecycle) {
+      const message = raw.message as Record<string, unknown> | undefined;
+      const events: SessionEvent[] = lifecycle
+        ? [{ kind: 'subagent', timestamp: Date.now(), subagent: lifecycle, raw }]
+        : this._classify(raw, parentToolUseId);
+      if (!events.length) {
+        this._unattributed(raw, 'subagent');
+        return;
+      }
+      for (const event of events)
+        this._emit({
+          ...event,
+          correlation: 'unknown',
+          unattributedReason: 'subagent',
+          nativeSessionId: typeof raw.session_id === 'string' ? raw.session_id : undefined,
+          messageId: typeof message?.id === 'string' ? message.id : undefined,
+        });
+      return;
+    }
+
     const turn = this._inflight;
     if (!turn) {
       if (terminalKey) this._seenTerminals.add(terminalKey);
@@ -1373,7 +1404,34 @@ export class ClaudeCodeSession implements HarnessSession {
   // Private — event classification
   // ---------------------------------------------------------------------------
 
-  private _classify(msg: Record<string, unknown>): SessionEvent[] {
+  /**
+   * A Claude Code `system` task frame for a subagent (`task_type: local_agent`), as lifecycle. Other
+   * task types (a background shell, a monitor, a workflow) are not subagents and return nothing.
+   * Later phases carry no task type, so the session remembers which task ids are subagents.
+   */
+  private _subagentLifecycle(msg: Record<string, unknown>): SubagentLifecycle | undefined {
+    if (msg.type !== 'system' || typeof msg.subtype !== 'string') return undefined;
+    const phase = CLAUDE_TASK_PHASES[msg.subtype];
+    const taskId = typeof msg.task_id === 'string' && msg.task_id ? msg.task_id : undefined;
+    if (!phase || !taskId) return undefined;
+    if (phase === 'started') {
+      const agent =
+        msg.task_type === 'local_agent' ||
+        (msg.task_type === undefined && typeof msg.subagent_type === 'string');
+      if (!agent) return undefined;
+      this._agentTasks.add(taskId);
+    } else if (!this._agentTasks.has(taskId)) return undefined;
+    if (phase === 'ended') this._agentTasks.delete(taskId);
+    return claudeSubagentLifecycle(msg, phase, taskId);
+  }
+
+  private _classify(msg: Record<string, unknown>, parentToolUseId?: string): SessionEvent[] {
+    return this._classifyFrame(msg).map((event) =>
+      parentToolUseId ? { ...event, parentToolUseId } : event,
+    );
+  }
+
+  private _classifyFrame(msg: Record<string, unknown>): SessionEvent[] {
     const events: SessionEvent[] = [];
     const ts = Date.now();
 
@@ -1558,3 +1616,51 @@ function processAlive(pid: number): boolean {
     return (error as NodeJS.ErrnoException).code === 'EPERM';
   }
 }
+
+const CLAUDE_TASK_PHASES: Readonly<Record<string, SubagentLifecycle['phase']>> = {
+  task_started: 'started',
+  task_progress: 'progress',
+  task_updated: 'updated',
+  task_notification: 'ended',
+};
+
+function claudeSubagentLifecycle(
+  msg: Record<string, unknown>,
+  phase: SubagentLifecycle['phase'],
+  taskId: string,
+): SubagentLifecycle {
+  const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+  const record = (value: unknown) =>
+    value && typeof value === 'object' && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
+  const patch = record(msg.patch);
+  const usage = record(msg.usage);
+  const status = text(msg.status) ?? text(patch?.status);
+  const count = (value: unknown) =>
+    typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+  return {
+    phase,
+    taskId,
+    ...(text(msg.tool_use_id) ? { toolUseId: text(msg.tool_use_id) } : {}),
+    ...(text(msg.parent_task_id) ? { parentTaskId: text(msg.parent_task_id) } : {}),
+    ...(text(msg.subagent_type) ? { agentType: text(msg.subagent_type) } : {}),
+    ...(text(msg.description) ? { description: text(msg.description) } : {}),
+    ...(typeof msg.spawn_depth === 'number' ? { depth: msg.spawn_depth } : {}),
+    ...(typeof msg.is_backgrounded === 'boolean' ? { backgrounded: msg.is_backgrounded } : {}),
+    ...(status ? { status } : {}),
+    ...(text(msg.summary) ? { summary: text(msg.summary) } : {}),
+    ...(text(msg.prompt) ? { prompt: text(msg.prompt) } : {}),
+    ...(usage && count(usage.total_tokens) !== undefined
+      ? {
+          usage: {
+            totalTokens: count(usage.total_tokens)!,
+            ...(count(usage.tool_uses) !== undefined ? { toolUses: count(usage.tool_uses) } : {}),
+            ...(count(usage.duration_ms) !== undefined
+              ? { durationMs: count(usage.duration_ms) }
+              : {}),
+          },
+        }
+      : {}),
+  };
+}

package/src/claude-subagents.ts

@@ -30,6 +30,15 @@
 //             Each spare serves one decision; `prestart` with new standby
 //             context replaces the spares (a turn landed), and a consumed one
 //             is pre-started again.
+//   pairs     each role keeps `sparesPerRole` spares (default 2), each copy in
+//             a different standby side session. A decision takes the spare
+//             whose side session is already most used, so a trigger empties
+//             whole side sessions; a side session whose spares were partly
+//             used ends its standby turn once nothing it serves is in flight,
+//             and is pre-started again while the other copy serves.
+//   sides     standby side sessions hold spares only; fan-outs (decisions with
+//             no spare) run in their own side sessions, so they never take a
+//             spare's place.
 //
 // Every member is a fresh subagent conversation: nothing of one decision
 // reaches another. Groups above `maxMembers` split evenly across more side
@@ -80,10 +89,12 @@ export interface ClaudeSubagentConfig {
     argv: string[],
     options: { cwd: string; env: Record<string, string | undefined> },
   ) => PipedSubprocess;
-  /** Members per fan-out; a larger batch splits evenly across side sessions. Default 12. */
+  /** Members per fan-out or standby turn; a larger set splits evenly across side sessions. Default 12. */
   maxMembers?: number;
-  /** Side sessions per group (pre-started spares hold some). Default 6. */
+  /** Fan-out side sessions per group. Standby side sessions are sized by the spares they hold. Default 6. */
   maxSessionsPerGroup?: number;
+  /** Pre-started spares kept per role, each copy in its own standby side session. Default 2. */
+  sparesPerRole?: number;
   /** Decisions arriving within this window of each other fan out together. Default 25 ms. */
   batchWindowMs?: number;
   /** Close a side session idle this long. Default 30 min. */
@@ -144,6 +155,8 @@ interface Spare {
 
 interface Side {
   readonly group: string;
+  /** Holds pre-started spares; never takes a fan-out. */
+  readonly standby: boolean;
   readonly names: ReadonlySet<string>;
   readonly proc: PipedSubprocess;
   readonly dir: string;
@@ -162,6 +175,8 @@ interface Side {
   spares: Map<string, Spare>;
   /** Its standby context was replaced: end its standby turn once no decision uses it. */
   retire?: boolean;
+  /** Its standby turn is being ended; it is pre-started again once rewound. */
+  ending?: boolean;
   onResult?: () => void;
   control: Map<string, { resolve(r: Record<string, unknown>): void; reject(e: Error): void }>;
 }
@@ -197,7 +212,12 @@ export class ClaudeSubagentSessions implements PrimedSessions {
     Required<
       Pick<
         ClaudeSubagentConfig,
-        'maxMembers' | 'maxSessionsPerGroup' | 'batchWindowMs' | 'idleMs' | 'timeoutMs'
+        | 'maxMembers'
+        | 'maxSessionsPerGroup'
+        | 'sparesPerRole'
+        | 'batchWindowMs'
+        | 'idleMs'
+        | 'timeoutMs'
       >
     >;
   private _groups = new Map<string, Group>();
@@ -213,11 +233,16 @@ export class ClaudeSubagentSessions implements PrimedSessions {
       ...config,
       maxMembers: config.maxMembers ?? 12,
       maxSessionsPerGroup: config.maxSessionsPerGroup ?? 6,
+      sparesPerRole: config.sparesPerRole ?? 2,
       batchWindowMs: config.batchWindowMs ?? 25,
       idleMs: config.idleMs ?? 30 * 60_000,
       timeoutMs: config.timeoutMs ?? 30_000,
     };
-    if (this._config.maxMembers < 1 || this._config.maxSessionsPerGroup < 1)
+    if (
+      this._config.maxMembers < 1 ||
+      this._config.maxSessionsPerGroup < 1 ||
+      this._config.sparesPerRole < 1
+    )
       throw Error('Invalid subagent session bounds');
   }
 
@@ -423,20 +448,26 @@ export class ClaudeSubagentSessions implements PrimedSessions {
     return name;
   }
 
+  /**
+   * A free spare for this role and standby context. A held one beats one still starting; among
+   * those, the one whose side session has the fewest free spares left, so a trigger empties whole
+   * side sessions and the other copies stay held.
+   */
   private _spareFor(group: Group, name: string, standby: string): Spare | undefined {
     const standbyHash = hash(standby);
-    for (const side of group.sides)
-      if (side.alive && !side.retire)
-        for (const spare of side.spares.values())
-          if (
-            spare.name === name &&
-            spare.standbyHash === standbyHash &&
-            !spare.member &&
-            !spare.done &&
-            !spare.violation
-          )
-            return spare;
-    return undefined;
+    const free = (sp: Spare) => !sp.member && !sp.done && !sp.violation;
+    let best: { spare: Spare; held: boolean; left: number } | undefined;
+    for (const side of group.sides) {
+      if (!side.alive || side.retire) continue;
+      const left = [...side.spares.values()].filter(free).length;
+      for (const spare of side.spares.values()) {
+        if (spare.name !== name || spare.standbyHash !== standbyHash || !free(spare)) continue;
+        const held = !!spare.pending;
+        if (!best || (held && !best.held) || (held === best.held && left < best.left))
+          best = { spare, held, left };
+      }
+    }
+    return best?.spare;
   }
 
   /** Admit a decision onto its spare; the input goes out when the spare's moment call is held. */
@@ -589,6 +620,9 @@ export class ClaudeSubagentSessions implements PrimedSessions {
       spare.pending = { requestId, rpcId: id };
       this._reportStandby(spare);
       this._deliver(spare);
+      // A copy now holds: a partly used side session elsewhere may be free to refill.
+      const held = this._groups.get(side.group);
+      if (held && !spare.member) this._releaseSpent(held);
       return true;
     }
     if (id === undefined) return this._mcpReply(side, requestId, null);
@@ -599,62 +633,121 @@ export class ClaudeSubagentSessions implements PrimedSessions {
     });
   }
 
-  /** Pre-start every desired role that has no spare holding its current standby context. */
+  /**
+   * Keep `sparesPerRole` spares of every desired role holding its current standby context. Copies
+   * of one role always go to different standby side sessions: each round of missing copies is its
+   * own set of standby turns.
+   */
   private _replenish(group: Group): void {
     if (this._closed || !group.desired.size || Date.now() < group.retryAt) return;
     // Spares are created when their standby turn is assigned, so one still starting counts as held.
-    const held = new Set<string>();
+    const held = new Map<string, number>();
     for (const side of group.sides)
       if (side.alive && !side.retire)
         for (const spare of side.spares.values())
           if (!spare.done && !spare.member && !spare.violation)
             if (group.desired.get(spare.name)?.standbyHash === spare.standbyHash)
-              held.add(spare.name);
-    const missing = [...group.desired.keys()].filter((name) => !held.has(name));
-    if (!missing.length) return;
-    const chunks = Math.ceil(missing.length / this._config.maxMembers);
-    const size = Math.ceil(missing.length / chunks);
-    for (let i = 0; i < missing.length; i += size) {
-      const chunk = missing.slice(i, i + size);
-      const needs = chunk.map(standbyName);
-      let side = group.sides.find((s) => s.alive && !s.busy && needs.every((n) => s.names.has(n)));
-      if (!side) {
-        if (group.sides.length >= this._config.maxSessionsPerGroup) return; // retried when one frees
-        try {
-          side = this._spawn(group);
-        } catch {
-          this._startFailed(group);
-          return;
+              held.set(spare.name, (held.get(spare.name) ?? 0) + 1);
+    const copies = this._config.sparesPerRole;
+    // Standby sessions this group may hold: every copy of every role, plus two for refills while
+    // partly used side sessions keep serving their unused spares.
+    const cap = copies * Math.ceil(group.desired.size / this._config.maxMembers) + 2;
+    for (let round = 0; round < copies; round++) {
+      const missing = [...group.desired.keys()].filter((name) => (held.get(name) ?? 0) <= round);
+      if (!missing.length) continue;
+      const chunks = Math.ceil(missing.length / this._config.maxMembers);
+      const size = Math.ceil(missing.length / chunks);
+      for (let i = 0; i < missing.length; i += size) {
+        const chunk = missing.slice(i, i + size);
+        // A side session launched with these roles' definitions (each has its standby variant).
+        let side = group.sides.find(
+          (s) => s.standby && s.alive && !s.busy && chunk.every((n) => s.names.has(n)),
+        );
+        if (!side) {
+          // A standby turn being ended, or with every spare used or taken, frees its side session in
+          // a moment: no new process meanwhile.
+          if (
+            group.sides.some(
+              (s) =>
+                s.standby &&
+                s.alive &&
+                (s.ending ||
+                  (s.spares.size > 0 &&
+                    [...s.spares.values()].every((sp) => sp.done || sp.member))),
+            )
+          )
+            return;
+          if (group.sides.filter((s) => s.standby).length >= cap) return; // retried when one frees
+          try {
+            side = this._spawn(group, true);
+          } catch {
+            this._startFailed(group);
+            return;
+          }
         }
+        const owner = side;
+        owner.busy = true;
+        owner.spares = new Map(
+          chunk.map((name, index) => {
+            const desired = group.desired.get(name)!;
+            // A position in this standby turn: deterministic, so a recorded turn replays.
+            const token = `s${index + 1}`;
+            const spare: Spare = {
+              name,
+              standbyHash: desired.standbyHash,
+              prompt: standbyPrompt(desired.standby, token),
+              token,
+              side: owner,
+              done: false,
+              tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            };
+            return [token, spare] as const;
+          }),
+        );
+        for (const name of chunk) held.set(name, (held.get(name) ?? 0) + 1);
+        void this._standbyFanOut(owner, group)
+          .catch(() => undefined)
+          .finally(() => {
+            owner.busy = false;
+            owner.retire = false;
+            owner.ending = false;
+            owner.lastUsed = Date.now();
+            this._replenish(group);
+          });
       }
-      const owner = side;
-      owner.busy = true;
-      owner.spares = new Map(
-        chunk.map((name, index) => {
-          const desired = group.desired.get(name)!;
-          // A position in this standby turn: deterministic, so a recorded turn replays.
-          const token = `s${index + 1}`;
-          const spare: Spare = {
-            name,
-            standbyHash: desired.standbyHash,
-            prompt: standbyPrompt(desired.standby, token),
-            token,
-            side: owner,
-            done: false,
-            tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-          };
-          return [token, spare] as const;
-        }),
-      );
-      void this._standbyFanOut(owner, group)
-        .catch(() => undefined)
-        .finally(() => {
-          owner.busy = false;
-          owner.retire = false;
-          owner.lastUsed = Date.now();
-          this._drain(group);
-          this._replenish(group);
-        });
+    }
+  }
+
+  /**
+   * Refills are staggered so one copy of every role is always serving. A partly used standby turn
+   * keeps serving its unused spares (the used copies refill elsewhere) and ends only once nothing it
+   * serves is in flight and every role it still holds has another held copy: ending it then frees
+   * its process without leaving any role uncovered.
+   */
+  private _releaseSpent(group: Group): void {
+    if (this._config.sparesPerRole < 2) return;
+    const free = (sp: Spare) => !sp.member && !sp.done && !sp.violation;
+    for (const side of group.sides) {
+      if (!side.standby || !side.alive || side.ending || side.retire || !side.busy) continue;
+      const spares = [...side.spares.values()];
+      if (!spares.some((sp) => sp.done || sp.member)) continue; // untouched
+      if (spares.some((sp) => sp.member && !sp.member.settled)) continue; // still serving
+      const covered = spares
+        .filter(free)
+        .every((sp) =>
+          group.sides.some(
+            (other) =>
+              other !== side &&
+              other.alive &&
+              !other.ending &&
+              !other.retire &&
+              [...other.spares.values()].some(
+                (o) =>
+                  o.name === sp.name && o.standbyHash === sp.standbyHash && free(o) && !!o.pending,
+              ),
+          ),
+        );
+      if (covered) this._endStandbyNow(side);
     }
   }
 
@@ -668,12 +761,14 @@ export class ClaudeSubagentSessions implements PrimedSessions {
   private _endStandby(side: Side): void {
     const inUse = [...side.spares.values()].some((sp) => sp.member && !sp.member.settled);
     if (inUse || !side.spares.size) return;
+    side.ending = true;
     void this._control(side, { subtype: 'interrupt' }, 5_000).catch(
       () => void this._kill(side, 'standby interrupt unanswered'),
     );
   }
 
   private _endStandbyNow(side: Side): void {
+    side.ending = true;
     void this._control(side, { subtype: 'interrupt' }, 5_000).catch(
       () => void this._kill(side, 'standby interrupt unanswered'),
     );
@@ -791,19 +886,18 @@ export class ClaudeSubagentSessions implements PrimedSessions {
         continue;
       }
       const needs = new Set(chunk.map((m) => m.name));
-      let side = group.sides.find(
-        (s) => s.alive && !s.busy && [...needs].every((n) => s.names.has(n)),
-      );
+      const fanOuts = group.sides.filter((s) => !s.standby);
+      let side = fanOuts.find((s) => s.alive && !s.busy && [...needs].every((n) => s.names.has(n)));
       if (!side) {
-        const idleLacking = group.sides.find((s) => !s.busy);
-        if (group.sides.length >= this._config.maxSessionsPerGroup) {
+        const idleLacking = fanOuts.find((s) => !s.busy);
+        if (fanOuts.length >= this._config.maxSessionsPerGroup) {
           if (!idleLacking) return; // every side session is busy: the chunk waits
           // A side session without these definitions is replaced by one that has them all.
           group.sides.splice(group.sides.indexOf(idleLacking), 1);
           void this._kill(idleLacking, 'definitions changed');
         }
         try {
-          side = this._spawn(group);
+          side = this._spawn(group, false);
         } catch (error) {
           group.waiting.shift();
           for (const m of chunk)
@@ -828,18 +922,18 @@ export class ClaudeSubagentSessions implements PrimedSessions {
     }
   }
 
-  private _spawn(group: Group): Side {
+  private _spawn(group: Group, standby: boolean): Side {
     const generation = ++this._generation;
     const dir = mkdtempSync(join(tmpdir(), 'agent-session-agents-'));
     try {
-      return this._launch(group, generation, dir);
+      return this._launch(group, generation, dir, standby);
     } catch (error) {
       rmSync(dir, { recursive: true, force: true });
       throw error;
     }
   }
 
-  private _launch(group: Group, generation: number, dir: string): Side {
+  private _launch(group: Group, generation: number, dir: string, standby: boolean): Side {
     chmodSync(dir, 0o700);
     const agents: Record<string, unknown> = {};
     for (const [name, def] of group.defs) {
@@ -909,6 +1003,7 @@ export class ClaudeSubagentSessions implements PrimedSessions {
         }) as unknown as PipedSubprocess);
     const side: Side = {
       group: group.id,
+      standby,
       names: new Set(group.defs.keys()),
       proc,
       dir,
@@ -1108,7 +1203,10 @@ export class ClaudeSubagentSessions implements PrimedSessions {
         if ([...side.spares.values()].every((sp) => sp.done)) this._endStandbyNow(side);
         else if (side.retire) this._endStandby(side);
         const group = this._groups.get(side.group);
-        if (group) this._replenish(group);
+        if (group) {
+          this._releaseSpent(group);
+          this._replenish(group);
+        }
         return;
       }
       const member = this._byToolUse(side, frame.tool_use_id);

package/src/codex-session.ts

@@ -944,6 +944,8 @@ export class CodexAppServerSession implements HarnessSession {
   private _approvals = new Map<string, AbortController>();
   /** The owned turn's in-progress fileChange items' changes, by item id, for their approvals. */
   private _fileChanges = new Map<string, readonly CodexFileChange[]>();
+  /** Child threads this session's turns spawned (collab `spawnAgent`), to the spawning item's id. */
+  private _children = new Map<string, string>();
   private _items = new Map<
     string,
     {
@@ -1266,6 +1268,8 @@ export class CodexAppServerSession implements HarnessSession {
           thread.turns.some((value) => !this._turn(value)))
       )
         this._refuse('configuration-missing-or-incompatible');
+      // Sub-agents belong to the thread that spawned them.
+      if (this._externalSessionId !== id) this._children.clear();
       this._externalSessionId = id;
       this._nativeSessionId =
         typeof thread?.sessionId === 'string' && thread.sessionId ? thread.sessionId : undefined;
@@ -1430,6 +1434,9 @@ export class CodexAppServerSession implements HarnessSession {
       },
     ];
     const a = this._inflight?.evidence;
+    const spawnedBy = threadId ? this._children.get(threadId) : undefined;
+    if (threadId && spawnedBy)
+      return this._childEvents(method, threadId, spawnedBy, turn, item, unowned);
     if (!threadId || threadId !== this._externalSessionId) return unowned('foreign-session');
     if (!a || this._appAdmission !== a.admissionId) return unowned('no-admission');
     if (turnId && this._seenTerminals.has(turnId))
@@ -1519,6 +1526,50 @@ export class CodexAppServerSession implements HarnessSession {
         else this._fileChanges.delete(itemId);
         return unowned('unrecognized-event');
       }
+      if (item.type === 'collabAgentToolCall') {
+        // A sub-agent this turn spawned (its thread is named once known, on start or completion),
+        // or closed. Other collab calls (send input, wait) are diagnostics.
+        const receivers = Array.isArray(item.receiverThreadIds)
+          ? item.receiverThreadIds.filter((id): id is string => typeof id === 'string' && !!id)
+          : [];
+        const prompt = typeof item.prompt === 'string' && item.prompt ? item.prompt : undefined;
+        if (item.tool === 'spawnAgent') {
+          const fresh = receivers.filter((child) => !this._children.has(child));
+          if (!fresh.length) return status();
+          return fresh.map((child): SessionEvent => {
+            this._children.set(child, itemId);
+            return {
+              ...identity,
+              kind: 'subagent',
+              timestamp: Date.now(),
+              subagent: {
+                phase: 'started',
+                taskId: child,
+                toolUseId: itemId,
+                agentType: 'spawnAgent',
+                depth: 1,
+                backgrounded: true,
+                ...(prompt ? { prompt } : {}),
+              },
+            };
+          });
+        }
+        if (item.tool === 'closeAgent' && method === 'item/completed') {
+          const closed = receivers.filter((child) => this._children.has(child));
+          if (!closed.length) return status();
+          return closed.map((child): SessionEvent => {
+            const toolUseId = this._children.get(child)!;
+            this._children.delete(child);
+            return {
+              ...identity,
+              kind: 'subagent',
+              timestamp: Date.now(),
+              subagent: { phase: 'ended', taskId: child, toolUseId, status: 'closed' },
+            };
+          });
+        }
+        return status();
+      }
       if (item.type === 'agentMessage') {
         if (method !== 'item/completed') return status();
         if (this._items.get(itemId)?.completed) return unowned('after-terminal');
@@ -1638,6 +1689,43 @@ export class CodexAppServerSession implements HarnessSession {
     }
     return method === 'turn/started' ? status() : unowned('unrecognized-event');
   }
+
+  /**
+   * A spawned sub-agent's thread, outside any admission of this session: its final messages as
+   * text and its turns' ends as lifecycle, tagged with the spawning item. Anything else stays a
+   * diagnostic, tagged the same way.
+   */
+  private _childEvents(
+    method: string,
+    threadId: string,
+    spawnedBy: string,
+    turn: { id: string; status: string; error?: unknown } | undefined,
+    item: Record<string, unknown> | undefined,
+    unowned: (reason: NonNullable<SessionEvent['unattributedReason']>) => SessionEvent[],
+  ): SessionEvent[] {
+    const tag = { parentToolUseId: spawnedBy, unattributedReason: 'subagent' as const };
+    const base = { threadId, correlation: 'unknown' as const, timestamp: Date.now(), ...tag };
+    if (
+      method === 'item/completed' &&
+      item?.type === 'agentMessage' &&
+      typeof item.text === 'string'
+    )
+      return [{ ...base, kind: 'text', text: item.text }];
+    if (method === 'turn/completed' && turn && turn.status !== 'inProgress')
+      return [
+        {
+          ...base,
+          kind: 'subagent',
+          subagent: {
+            phase: 'updated',
+            taskId: threadId,
+            toolUseId: spawnedBy,
+            status: turn.status,
+          },
+        },
+      ];
+    return unowned('subagent').map((event) => ({ ...event, ...tag }));
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/harness-session.ts

@@ -92,7 +92,38 @@ export type SessionEventKind =
   | 'usage'
   | 'rate_limit'
   | 'result'
-  | 'error';
+  | 'error'
+  | 'subagent';
+
+/**
+ * A subagent's lifecycle as the native runtime reports it (kind `subagent`). Claude Code: its
+ * `system` task frames for an Agent/Task call. Codex: a collab `spawnAgent` item and its child thread.
+ */
+export interface SubagentLifecycle {
+  readonly phase: 'started' | 'progress' | 'updated' | 'ended';
+  /** The native id of the subagent run (Claude task id, Codex child thread id). */
+  readonly taskId: string;
+  /** The tool call that spawned it, in its parent's stream. */
+  readonly toolUseId?: string;
+  /** The task that spawned it, when a subagent spawned it (Claude). */
+  readonly parentTaskId?: string;
+  readonly agentType?: string;
+  readonly description?: string;
+  /** 1 for a child of the main thread. */
+  readonly depth?: number;
+  readonly backgrounded?: boolean;
+  /** The native status at the end (completed, stopped, failed, killed). */
+  readonly status?: string;
+  readonly summary?: string;
+  /** The task the subagent was given. */
+  readonly prompt?: string;
+  /** Its own running totals, when the runtime reports them (Claude progress and end frames). */
+  readonly usage?: {
+    readonly totalTokens: number;
+    readonly toolUses?: number;
+    readonly durationMs?: number;
+  };
+}
 
 /** Input excludes cache reads/writes when those disjoint counters are supplied.
  * Thinking is a subset of output; TTL counters are subsets of cacheWrite.
@@ -130,7 +161,8 @@ export interface SessionEvent extends SessionIdentity {
     | 'duplicate-tool'
     | 'unmatched-tool'
     | 'malformed-tool'
-    | 'account-status';
+    | 'account-status'
+    | 'subagent';
   /** Local transport observation, not a native terminal acknowledgment. */
   readonly transportOutcome?: SessionAttempt['transportOutcome'];
   readonly nativeOutcome?: NativeOutcome;
@@ -174,6 +206,14 @@ export interface SessionEvent extends SessionIdentity {
   readonly limits?: LimitSnapshot;
   /** Owned, deeply frozen native JSON data (for Oracle introspection). */
   readonly raw?: unknown;
+  /**
+   * The tool call (in its parent's stream) that spawned the subagent this event came from; absent
+   * for the main thread's own events. Every subagent event, its lifecycle included, is outside any
+   * admission (`unattributedReason: "subagent"`), so it never touches a turn's content or results.
+   */
+  readonly parentToolUseId?: string;
+  /** A subagent's lifecycle (kind `subagent`). */
+  readonly subagent?: SubagentLifecycle;
 }
 
 /** Result of a single send() — the turn's content plus all classified events. */

package/src/turn-state.ts

@@ -63,8 +63,11 @@ export class TurnState {
   record(event: SessionEvent): SessionEvent {
     const e = retainEvidence({ ...this.identity, ...event, admissionId: this.admissionId });
     this.events.push(e);
-    if ((e.kind === 'text' || e.kind === 'result') && e.text) this.content = e.text;
-    if (e.kind === 'text_delta' && e.text) this.content += e.text;
+    // A subagent's text is its own; the parent turn's content is only the parent's.
+    if (!e.parentToolUseId) {
+      if ((e.kind === 'text' || e.kind === 'result') && e.text) this.content = e.text;
+      if (e.kind === 'text_delta' && e.text) this.content += e.text;
+    }
     // Usage events are per-request snapshots; the terminal result carries the turn total.
     if (e.tokens && e.kind !== 'usage') this.tokens = e.tokens;
     return e;