@inixiative/agent-session 0.6.4 → 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.4",
+  "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.81",
+    "@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/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;