@inixiative/agent-session 0.6.4 → 0.6.6

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
@@ -140,6 +164,47 @@ a pre-spawned spare. Measured on a ChatGPT login: warm Codex decisions 2.45 s
 median vs 3.9 s for `codex exec` per decision, with 34% fewer input tokens; warm
 Claude (haiku) decisions 1.95 s with the whole primed prefix read from cache.
 
+### In the main session's own process (Claude)
+
+`ClaudeInSessionDecisions` holds decision roles as subagents of a main
+`ClaudeCodeSession`, so a thread and all its decision roles are one process:
+
+```ts
+const decisions = new ClaudeInSessionDecisions({ model: "claude-haiku-5-5", effort: "low" });
+const session = new ClaudeCodeSession({ model: "claude-opus-5-5", cwd, toolGate: true });
+session.extend(decisions); // before start(): agents, an SDK MCP server, a PreToolUse claim
+await session.start();     // one internal setup turn starts the root agent
+decisions.prestart(threadId, roles.map((spec) => ({ spec, standby })));
+await decisions.ready();
+const result = await decisions.decide(spec, { input, standby });
+```
+
+- **Shape.** The setup turn asks the main model to start `foundry-root` in the
+  background. The root never ends: it starts dispatcher generations
+  (`foundry-dispatch`), which start members (`foundry-warden`), all in the
+  background, through a `next` tool the host holds open. A member holds the
+  host's `moment` tool until a decision answers it, and answers through
+  `answer`. After setup, no member activity needs a main-model turn.
+- **Pinned input.** Every spawn passes the session's PreToolUse callback,
+  which replaces its prompt with the composed text, so agent definitions are
+  generic and an edited role reaches the next spare without a relaunch.
+  Spawns of these agent types from anywhere else are denied; the main agent's
+  own subagents go to the tool gate untouched.
+- **Fresh per call.** Each member serves one decision. A used one is replaced
+  at once; a role with no held spare starts a member with its input inline.
+- **Recycle.** A dispatcher's context grows ~700 tokens per member started;
+  past `recycleTokens` (100k) a new generation takes over and the old one
+  ends into the root once empty.
+- **Orphans.** A nested agent whose parent ended reports its own end to the
+  main thread, which wakes the main model (Claude Code 2.1.300). Members of a
+  dispatcher that ended unasked are therefore never retired or stopped, and an
+  orphan's `answer` call is held for the session's life. Past `maxOrphans`
+  (40) the host stops serving and its caller falls back.
+- **Limits.** Claude Code runs 20 subagents at once by default; the launch
+  raises `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (`maxSubagents`, 96). The
+  session declares `perTaskStopAffordance`, so the user's Stop spares
+  background agents.
+
 ## Pools, routing and continuity
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "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.88",
     "@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,
@@ -142,6 +143,66 @@ export interface ClaudeCodeSessionConfig {
   ) => PipedSubprocess;
 }
 
+// ---------------------------------------------------------------------------
+// Extension: work a host runs inside this session's own process (ClaudeInSessionDecisions)
+// ---------------------------------------------------------------------------
+
+/** A custom agent definition (`--agents`), as Claude Code reads it. */
+export interface ClaudeAgentDefinition {
+  readonly description: string;
+  readonly prompt: string;
+  readonly tools: readonly string[];
+  readonly model?: string;
+  readonly effort?: string;
+  readonly permissionMode?: string;
+  readonly omitClaudeMd?: boolean;
+  readonly background?: boolean;
+}
+
+/** What the session offers an extension once its process is up. */
+export interface ClaudeSessionHost {
+  /** A control request to the CLI (e.g. `stop_task`). */
+  control(request: Record<string, unknown>, timeoutMs: number): Promise<Record<string, unknown>>;
+  /** Answer an MCP message the extension was handed. */
+  mcpReply(requestId: string, message: unknown): void;
+  /**
+   * A turn of the extension's own, never a caller's: queued like any send, and nothing of it is
+   * attributed to a caller's admission. No deadline: its native outcome must settle.
+   */
+  sendInternal(message: string): Promise<SessionResult>;
+  alive(): boolean;
+}
+
+/**
+ * Work that runs inside this session's process (agents, an SDK MCP server, a PreToolUse claim on
+ * its own tool calls), never through vendor hook files. Attached before `start()`.
+ */
+export interface ClaudeSessionExtension {
+  /** Agent definitions added to the launch. */
+  readonly agents: Readonly<Record<string, ClaudeAgentDefinition>>;
+  /** SDK MCP servers it answers (declared in `initialize`). */
+  readonly mcpServers: readonly string[];
+  /** Environment its agents need on the launch (merged over the session's own). */
+  readonly env?: Readonly<Record<string, string>>;
+  /** The process runs (before `initialize`): it may answer MCP messages from now on. */
+  attach(host: ClaudeSessionHost): void;
+  /** `initialize` was answered: it may write turns and control requests. */
+  started(): void;
+  /** An MCP message for one of its servers; answered through `host.mcpReply`. */
+  mcp(server: string, requestId: string, message: Record<string, unknown>): void;
+  /**
+   * A PreToolUse callback: the hook output when the call is its own (its agents' calls, a spawn of
+   * one of its agent types), else undefined and the tool gate decides.
+   */
+  preToolUse(input: Record<string, unknown>): Record<string, unknown> | undefined;
+  /** A permission ask (`can_use_tool`): its answer when the asking agent is its own, else undefined. */
+  permission(request: Record<string, unknown>): Record<string, unknown> | undefined;
+  /** A native frame: true when it is its own (never emitted, never part of an admission). */
+  frame(raw: Record<string, unknown>): boolean;
+  /** The process ended or was killed. */
+  detach(reason: string): void;
+}
+
 // ---------------------------------------------------------------------------
 // Internal turn queue entry
 // ---------------------------------------------------------------------------
@@ -272,6 +333,9 @@ export class ClaudeCodeSession implements HarnessSession {
   private _persistSession: boolean;
   private _toolGate: boolean;
   private _gates = new ToolGates();
+  private _extension?: ClaudeSessionExtension;
+  /** The private directory holding the extension's agent definitions while a process runs. */
+  private _agentsDir?: string;
   /** Inbound control requests awaiting a gate decision, by request id. */
   private _inbound = new Map<string, AbortController>();
   private readonly _hookCallbackId = `agent-session-pre-tool-${crypto.randomUUID()}`;
@@ -314,6 +378,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[] = [];
@@ -407,6 +473,17 @@ export class ClaudeCodeSession implements HarnessSession {
     return this._gates.add(gate);
   }
 
+  /**
+   * Run an extension inside this session's process (ClaudeInSessionDecisions). Before `start()`
+   * only, once, and never on a text-only session (it needs tools and an MCP server).
+   */
+  extend(extension: ClaudeSessionExtension): void {
+    if (this._proc) throw new Error('Extensions attach before start()');
+    if (this._extension) throw new Error('Session already has an extension');
+    if (this._textOnly) throw new Error('A text-only session cannot host an extension');
+    this._extension = extension;
+  }
+
   onBeforeSend(hook: BeforeSendHook): () => void {
     this._beforeSendHooks.push(hook);
     return () => {
@@ -448,6 +525,7 @@ export class ClaudeCodeSession implements HarnessSession {
     const env: Record<string, string | undefined> = {
       ...process.env,
       ...this._env,
+      ...this._extension?.env,
       DISABLE_AUTOUPDATER: '1',
     };
     delete env.ANTHROPIC_API_KEY;
@@ -468,6 +546,7 @@ export class ClaudeCodeSession implements HarnessSession {
       }
     } catch (error) {
       this._removeBaseContext();
+      this._removeAgents();
       throw error;
     }
 
@@ -483,9 +562,13 @@ export class ClaudeCodeSession implements HarnessSession {
     // Monitor process exit for cleanup
     // The process read its base context file at startup; it goes when the process does.
     const baseDir = this._baseContextDir;
+    const agentsDir = this._agentsDir;
     proc.exited.then(async (code) => {
       this._removeBaseContext(baseDir);
-      if (this._proc !== proc || !this._alive) return;
+      this._removeAgents(agentsDir);
+      if (this._proc !== proc) return;
+      this._detachExtension('process exited');
+      if (!this._alive) return;
       this._alive = false;
       await stdoutDone; // Drain buffered terminal evidence before interpreting process exit.
       const errMsg = this._stderr.trim()
@@ -498,22 +581,60 @@ export class ClaudeCodeSession implements HarnessSession {
     });
 
     // The PreToolUse callback is registered before any turn is written, so it covers the first call.
-    if (this._toolGate) {
+    // An extension's agents run their own tools: it claims them through the same callback.
+    const extension = this._extension;
+    // The extension can answer from the moment the process runs: the CLI connects its SDK MCP
+    // server while `initialize` is still in flight, and an unanswered connect costs a 30 s retry.
+    if (extension)
+      extension.attach({
+        control: (request, timeoutMs) => this._controlRequest(request, timeoutMs),
+        mcpReply: (requestId, message) => {
+          if (this._proc === proc && this._alive)
+            this._writeControlResponse(proc, requestId, { mcp_response: message });
+        },
+        sendInternal: (message) => this.send(message, { timeout: 0 }),
+        alive: () => this._proc === proc && this._alive,
+      });
+    if (this._toolGate || extension) {
       try {
         await this._controlRequest(
           {
             subtype: 'initialize',
             hooks: { PreToolUse: [{ matcher: '.*', hookCallbackIds: [this._hookCallbackId] }] },
+            ...(extension
+              ? {
+                  sdkMcpServers: [...extension.mcpServers],
+                  // The user's Stop aborts the turn only; background agents (the extension's) survive.
+                  perTaskStopAffordance: true,
+                }
+              : {}),
           },
           30_000,
         );
       } catch (error) {
         this.kill();
-        throw new Error(`Tool gate registration failed: ${(error as Error).message}`);
+        throw new Error(
+          `${this._toolGate ? 'Tool gate' : 'Extension'} registration failed: ${(error as Error).message}`,
+        );
+      }
+    }
+    if (extension && this._proc === proc && this._alive) {
+      try {
+        extension.started();
+      } catch {
+        /* an extension's failure never touches the session */
       }
     }
   }
 
+  private _detachExtension(reason: string): void {
+    try {
+      this._extension?.detach(reason);
+    } catch {
+      /* an extension's failure never touches the session */
+    }
+  }
+
   private _rejectControl(error: Error): void {
     for (const pending of this._control.values()) pending.reject(error);
     this._control.clear();
@@ -749,6 +870,8 @@ export class ClaudeCodeSession implements HarnessSession {
     }
     this._proc = null;
     this._removeBaseContext();
+    this._removeAgents();
+    this._detachExtension('killed');
 
     this._emit({ kind: 'session_end', timestamp: Date.now() });
   }
@@ -1004,6 +1127,8 @@ export class ClaudeCodeSession implements HarnessSession {
     if (raw.type === 'control_request') {
       const id = typeof raw.request_id === 'string' ? raw.request_id : undefined;
       const request = raw.request as Record<string, unknown> | undefined;
+      if (id && this._proc && this._extension && this._extensionRequest(this._proc, id, request))
+        return;
       const toolRequest =
         id && this._toolGate && this._proc ? this._toolRequestFrom(request) : undefined;
       if (id && toolRequest) {
@@ -1104,6 +1229,45 @@ export class ClaudeCodeSession implements HarnessSession {
       return;
     }
 
+    // An extension's own agents (their frames and task lifecycle) are its alone.
+    if (this._extension) {
+      let own = false;
+      try {
+        own = this._extension.frame(raw);
+      } catch {
+        /* an extension's failure never touches the session */
+      }
+      if (own) 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);
@@ -1227,6 +1391,52 @@ export class ClaudeCodeSession implements HarnessSession {
     };
   }
 
+  /**
+   * A control request the extension answers: an MCP message for its servers, or a PreToolUse
+   * callback / permission ask that belongs to its agents or spawns one of its agent types. With no
+   * tool gate, our callback's other calls get no opinion (the session's permission mode decides).
+   */
+  private _extensionRequest(
+    proc: PipedSubprocess,
+    id: string,
+    request: Record<string, unknown> | undefined,
+  ): boolean {
+    const extension = this._extension!;
+    try {
+      if (
+        request?.subtype === 'mcp_message' &&
+        typeof request.server_name === 'string' &&
+        extension.mcpServers.includes(request.server_name)
+      ) {
+        extension.mcp(request.server_name, id, (request.message ?? {}) as Record<string, unknown>);
+        return true;
+      }
+      if (this._ownHookCallback(request)) {
+        const input = request!.input as Record<string, unknown> | undefined;
+        const output = input ? extension.preToolUse(input) : undefined;
+        if (output) {
+          this._writeControlResponse(proc, id, { hookSpecificOutput: output });
+          return true;
+        }
+        if (!this._toolGate) {
+          this._writeControlResponse(proc, id, {});
+          return true;
+        }
+        return false;
+      }
+      if (request?.subtype === 'can_use_tool') {
+        const answer = extension.permission(request);
+        if (answer) {
+          this._writeControlResponse(proc, id, answer);
+          return true;
+        }
+      }
+    } catch {
+      /* an extension's failure falls through to the session's own handling */
+    }
+    return false;
+  }
+
   private _ownHookCallback(request: Record<string, unknown> | undefined): boolean {
     return request?.subtype === 'hook_callback' && request.callback_id === this._hookCallbackId;
   }
@@ -1345,10 +1555,26 @@ export class ClaudeCodeSession implements HarnessSession {
     if (this._baseContext) {
       args.push('--append-system-prompt-file', this._writeBaseContext(this._baseContext));
     }
+    // An extension's agents, from a private file; its MCP servers are declared in `initialize`.
+    if (this._extension) args.push('--agents', this._writeAgents(this._extension.agents));
 
     return args;
   }
 
+  private _writeAgents(agents: ClaudeSessionExtension['agents']): string {
+    this._removeAgents();
+    this._agentsDir = mkdtempSync(join(tmpdir(), `${BASE_CONTEXT_PREFIX}${process.pid}-agents-`));
+    const file = join(this._agentsDir, 'agents.json');
+    writeFileSync(file, JSON.stringify(agents), { mode: 0o600 });
+    return file;
+  }
+
+  private _removeAgents(dir = this._agentsDir): void {
+    if (!dir) return;
+    rmSync(dir, { recursive: true, force: true });
+    if (dir === this._agentsDir) this._agentsDir = undefined;
+  }
+
   /** The base context as a private file: argv carries its path, never its text. */
   private _writeBaseContext(text: string): string {
     this._removeBaseContext();
@@ -1373,7 +1599,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 +1811,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) }
+              : {}),
+          },
+        }
+      : {}),
+  };
+}