flowviant 0.125.1 → 0.125.3

package/bin/lib/orchestratorInput.mjs

@@ -0,0 +1,47 @@
+// A whole-event memory guard, aligned with the authenticated API's 24 MiB
+// request budget. It is not an allowance on a prompt or tool-result field.
+export const ORCHESTRATOR_REQUEST_BYTES = 24 * 1024 * 1024;
+export const ORCHESTRATOR_INPUT_TOO_LARGE = 'ORCHESTRATOR_INPUT_TOO_LARGE';
+
+export class OrchestratorInputTooLarge extends Error {
+  constructor() {
+    super('The orchestration hook request exceeds the 24 MiB transport limit.');
+    this.code = ORCHESTRATOR_INPUT_TOO_LARGE;
+  }
+}
+
+/** Read bounded raw bytes before decoding: pipe/HTTP chunks can split UTF-8.
+ * On refusal, drain without buffering so HTTP can still return its reason. */
+export function readOrchestratorInput(stream) {
+  return new Promise((resolve, reject) => {
+    let chunks = [], bytes = 0;
+    const cleanup = () => {
+      stream.off('data', data); stream.off('end', end);
+      stream.off('error', fail); stream.off('close', closed);
+    };
+    const fail = error => {
+      cleanup(); chunks = [];
+      // The producer can abort after seeing the refusal. That late stream
+      // error must not crash the controller while the remainder is drained.
+      const ignore = () => {};
+      stream.on('error', ignore);
+      stream.once('close', () => stream.off('error', ignore));
+      stream.resume(); reject(error);
+    };
+    const closed = () => fail(new Error('The orchestration input closed before completion.'));
+    const data = chunk => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      bytes += buffer.length;
+      if (bytes > ORCHESTRATOR_REQUEST_BYTES) { fail(new OrchestratorInputTooLarge()); return; }
+      chunks.push(buffer);
+    };
+    const end = () => {
+      cleanup();
+      try { resolve(JSON.parse(Buffer.concat(chunks, bytes).toString('utf8'))); }
+      catch (error) { reject(error); }
+      chunks = [];
+    };
+    stream.on('data', data); stream.once('end', end);
+    stream.once('error', fail); stream.once('close', closed);
+  });
+}

package/bin/lib/orchestratorPrompt.mjs

@@ -0,0 +1,19 @@
+export const ORCHESTRATOR_CONTRACT = `CARD ORCHESTRATOR — this applies to this card's one CLI and worktree.
+You are the model the person chose and remain responsible for the card and its final JSON.
+Work yourself when the card spans one area. Only split work spanning several areas into native in-process subagents by kind (Backend/UI/Tests…). This is authorization to use those native agents on this card. Give each a concrete title, prompt and kind, and post short updates of your own. Do not create extra branches or Flowviant agents. Use a native agent type that can call card_orchestrator MCP (Claude general-purpose); keep the work yourself if none can. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.
+
+The daemon gates every native spawn against this project's Turns at once pool, shared with its other turns. Claude children run in the background so you remain available for messages and their questions; Codex spawns are already asynchronous. A refused spawn with a waiting id has not started. Keep working yourself; do not wait for it. When notified of a free slot, retry its native spawn with the same prompt. Never bypass this gate with another CLI process. The orchestrator itself also holds a slot. If no slot becomes available, finish the work yourself.
+
+The card_orchestrator MCP tools report routing and child questions. A live person’s note has a Message id. Report each note using route_message:
+- Handle it yourself: taken.
+- Delegate it: queued, with the native agent id, its kind, and the safePoint chosen FOR THIS NOTE: "when it finishes", "after its current edit", or a precise stated checkpoint.
+- When it finishes: wait for that child's completion, then put the note in its next native task/follow-up.
+- After its current edit: the gate pauses further tool use at the next boundary. Use the native stop/interrupt tool, preserve its work so far, and resume it or start a follow-up with that context and the note. Do not interrupt in the middle of an edit.
+- Only after native delivery at that checkpoint: handed with that agent id/kind/safePoint. This appends "From {orchestrator} …" to its stream. Never report a handoff before doing it.
+Use the tools' agent record id when one is supplied by a native spawn gate. Keep a later native id with that record.
+
+All child prompts must say: share this worktree, preserve others' edits, return questions to the orchestrator with agent_question, read its answer before continuing, never escalate directly to the person, and do not commit independently of the card's orchestrator. Answer child questions from the card, code and earlier notes with answer_agent when possible. If only the person can decide, mark escalate with answer_agent, then use the existing blocked JSON question card naming the asking child. Leave that child asked until answered. When the person answers in a resumed run, call answer_agent with the earlier agentId, nativeAgentId, kind/title and question from your conversation plus their answer; then give it to that same child through a native follow-up. Never guess a missing identity.
+
+Urgent is the person's explicit exception. The daemon uses the whole-turn interrupt/resume fallback when a child cannot be targeted reliably; the same stored note becomes the resumed prompt and reads "interrupted the run". Stop ends the whole run. Do not keep working or hand off notes after Stop.
+
+Claude receives notes through its native live stdin. Codex exec cannot accept stdin mid-turn: on supported code-card CLIs, the daemon injects pending notes through the next native tool hook boundary in the same turn. During a tool-free answer or on fenced/older Codex turns, the note remains for the next run; do not claim it was already read. No new model is involved.`;

package/bin/lib/orchestratorProtocol.mjs

@@ -0,0 +1,15 @@
+/** The run-scoped MCP vocabulary; safe to load in a credential-free client. */
+export const ORCHESTRATOR_TOOLS = [
+  { name: 'register_agent', description: 'A native child calls this first with the agent record id in its prompt, before working. It binds native events to that record.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' } }, required: ['agentId'], additionalProperties: false } },
+  { name: 'describe_agent', description: 'The orchestrator reports the kind and title it chose for a child when the native role is generic. Use Backend, UI, Tests or the actual area of work.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, kind: { type: 'string' }, title: { type: 'string' } }, required: ['agentId', 'kind', 'title'], additionalProperties: false } },
+  { name: 'route_message', description: 'Report where you routed a person’s live note. Choose its safe point per note. Report handed only after native delivery at that checkpoint; taken means you handled it yourself.',
+    inputSchema: { type: 'object', properties: { messageId: { type: 'string' }, state: { enum: ['queued', 'handed', 'taken'] },
+      agentId: { type: 'string' }, kind: { type: 'string' }, safePoint: { type: 'string' } }, required: ['messageId', 'state'], additionalProperties: false } },
+  { name: 'agent_question', description: 'A child asks its orchestrator before asking the person. Call again to read an answer. The orchestrator answers from the card/code/earlier notes or escalates a real person-only decision.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, question: { type: 'string' } }, required: ['agentId', 'question'], additionalProperties: false } },
+  { name: 'answer_agent', description: 'Answer a child question from known facts, or mark it for escalation to the person. An escalation returns the attribution to put on the existing blocked question card.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, answer: { type: 'string' }, escalate: { type: 'boolean' },
+      question: { type: 'string' }, nativeAgentId: { type: 'string' }, kind: { type: 'string' }, title: { type: 'string' } }, required: ['agentId'], additionalProperties: false } },
+];

package/bin/lib/promptTransport.mjs

@@ -0,0 +1,34 @@
+/** Move complete prompts off argv's OS byte limits. Keep each adapter's
+ * assembled framing verbatim; stdin carries the very string argv held.
+ * Claude's separate system prompt uses its native file flag. */
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export function promptTransport(runtime, original, stdinText = null) {
+  const args = [...original];
+  let text = null;
+  let dir = null;
+  try {
+    if (runtime === 'codex') {
+      text = stdinText ?? args[args.length - 1];
+      args[args.length - 1] = '-';
+    } else if (runtime === 'claude') {
+      if (!args.includes('--input-format')) {
+        const at = args.indexOf('-p');
+        text = args.splice(at + 1, 1)[0];
+      }
+      const at = args.indexOf('--append-system-prompt');
+      if (at !== -1) {
+        dir = mkdtempSync(join(tmpdir(), 'flowviant-system-'));
+        const file = join(dir, 'system.txt');
+        writeFileSync(file, args[at + 1], { mode: 0o600 });
+        args.splice(at, 2, '--append-system-prompt-file', file);
+      }
+    }
+    return { args, text, cleanup: () => { if (dir) rmSync(dir, { recursive: true, force: true }); } };
+  } catch (error) {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+    throw error;
+  }
+}

package/bin/lib/runTurn.mjs

@@ -10,6 +10,7 @@
  * (runtimeEvents.mjs).
  */
 
+import { promptTransport } from './promptTransport.mjs';
 import { runIsolatedResearch } from './codexResearch.mjs';
 import { spawn } from 'node:child_process';
 import { runtimeById } from './runtimes.mjs';
@@ -24,6 +25,11 @@ import { codexTurnModel } from './turnModel.mjs';
 import { printableText } from './printable.mjs';
 import { startTurnDiagnostics } from './turnDiagnostics.mjs';
 import { createClaudeInput } from './claudeInput.mjs';
+import { createClaudeSubagents } from './claudeSubagents.mjs';
+import { createCodexSubagentReader } from './codexSubagents.mjs';
+import { measuredRuntimeVersion } from './runtimeDetection.mjs';
+import { createClaudeSubagentProgress } from './claudeSubagentProgress.mjs';
+import { codexSpawnResult } from './codexSubagentEvents.mjs';
 
 /** How long a Codex turn's answer may wait on its rollout's model line. */
 const CODEX_MODEL_READ_MS = 1_500;
@@ -88,6 +94,9 @@ function runPlainTurn(opts) {
     const resolve = (v) => {
       if (!workLanesStopped()) resolveTurn(v);
     };
+    const reject = (error) => {
+      if (!workLanesStopped()) rejectTurn(error);
+    };
     const rt = runtimeById(runtime);
     // AN UNKNOWN RUNTIME IS REFUSED, NEVER RUN AS CLAUDE (2026-09-26). Asked
     // before anything is spawned. This is the belt, not the relay: the words
@@ -169,6 +178,10 @@ function runPlainTurn(opts) {
     // to get wrong: the caller named one profile (turnProfile.mjs).
     const stdinText = rt.stdin?.({ prompt, system, profile: turnProfile.adapterProfile }) ?? null;
     const args = rt.args({
+      cardTurn: opts.cardTurn === true,
+      orchestration: opts.orchestration === true,
+      codexVersion: measuredRuntimeVersion('codex')?.version,
+
       streamInput: stdinText !== null || (rt.id === 'claude' && Boolean(opts.liveMessages)),
       writableDirs: opts.writableDirs,
       personal,
@@ -255,10 +268,15 @@ function runPlainTurn(opts) {
      * so no throw on the way leaves that file behind: the sweep takes only a
      * dead process's leftovers, and this one names the daemon's own pid.
      */
+    let transport;
+    try { transport = promptTransport(rt.id, args, stdinText); }
+    catch (error) { rt.releaseArgs?.(args); throw error; }
+    args.splice(0, args.length, ...transport.args);
     let argsReleased = false;
     const releaseArgs = () => {
       if (argsReleased) return;
       argsReleased = true;
+      transport.cleanup();
       try {
         rt.releaseArgs?.(args);
       } catch {
@@ -278,11 +296,11 @@ function runPlainTurn(opts) {
         browserHome: browser?.dir,
       });
       finishDiagnostics = startTurnDiagnostics({ runtime, bin: rt.bin, env: childEnv,
-        cwd, args, stdinBytes: stdinText === null ? 0 : Buffer.byteLength(stdinText),
+        cwd, args, stdinBytes: transport.text === null ? 0 : Buffer.byteLength(transport.text),
         profile: turnProfile.name, planId: opts.diagnosticPlanId });
       child = spawn(rt.bin, args, {
         cwd,
-        stdio: [stdinText !== null || (rt.id === 'claude' && opts.liveMessages) ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        stdio: [transport.text !== null || (rt.id === 'claude' && opts.liveMessages) ? 'pipe' : 'ignore', 'pipe', 'pipe'],
         /**
          * ITS OWN PROCESS GROUP, so what the agent starts stays attributable.
          *
@@ -324,7 +342,7 @@ function runPlainTurn(opts) {
       child.once('close', browser.cleanup);
       child.once('error', browser.cleanup);
     }
-    onSpawn?.(child);
+    if (child.pid) onSpawn?.(child);
     // When this turn began, for the Codex rollout read: a `turn_context` older
     // than this is a previous turn's (turnModel.mjs).
     const spawnedAt = Date.now();
@@ -375,7 +393,25 @@ function runPlainTurn(opts) {
       recordClaudeRateLimit(info);
       onRateLimit?.(info);
     };
+    const agentStates = new Map();
+    const reportSubagent = (update) => {
+      if (!update?.id || (!agentStates.has(update.id) && agentStates.size >= 32)) return;
+      agentStates.set(update.id, update.status ?? agentStates.get(update.id) ?? 'running');
+      opts.onSubagent?.(update);
+    };
+    const subagents = createClaudeSubagents(reportSubagent);
+    const claudeProgress = rt.id === 'claude' && opts.onSubagent ? createClaudeSubagentProgress({
+      cwd, since: spawnedAt, env: { ...process.env, ...(mcpEnv ?? {}) },
+      onLine: line => handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText,
+        answerFromResult: true, subagents }),
+    }) : null;
+    const codexAgents = rt.id === 'codex' && opts.onSubagent ? createCodexSubagentReader({
+      since: spawnedAt, env: { ...process.env, ...(mcpEnv ?? {}) },
+      onSubagent: reportSubagent, onActivity, onToolEvent,
+      onSpawnResult: opts.onSpawnResult,
+    }) : null;
     let codexThread = rt.id === 'codex' && typeof resumeThreadId === 'string' ? resumeThreadId : null;
+    if (codexThread) codexAgents?.thread(codexThread);
     /**
      * THE MODEL THIS SPAWN RAN ON, ONCE (2026-09-29, turnModel.mjs). Claude
      * names it in its init event and again on every reply; the first valid
@@ -399,6 +435,7 @@ function runPlainTurn(opts) {
      */
     const harvest = initHarvestFor(rt, args);
     const onInitAll = (i) => {
+      claudeProgress?.session(i?.sessionId);
       if (harvest.skills) recordSkills(i?.skills);
       if (harvest.mcp) recordMcpServers(i?.mcpServers, i?.tools);
       onInit?.(i);
@@ -408,7 +445,8 @@ function runPlainTurn(opts) {
     const onLine = (line) => {
       try {
         const event = JSON.parse(line);
-        if (input) {
+        const parentEvent = event.parent_tool_use_id == null && !event.isSidechain;
+        if (input && parentEvent) {
           input.event(event);
           if (event.type === 'system' && event.subtype === 'init' && event.session_id) opts.liveMessages.onInit(event.session_id);
           // A message written just before result may become a second native
@@ -416,26 +454,30 @@ function runPlainTurn(opts) {
           // structured objects joined together; every result still reports spend.
           if (event.type === 'result') out = '';
         }
-        if ((event.type === 'result' && event.is_error === true) ||
-            event.type === 'error' || event.type === 'turn.failed') {
+        if (parentEvent && ((event.type === 'result' && event.is_error === true) ||
+            event.type === 'error' || event.type === 'turn.failed')) {
           cliFailed = true;
           opts.onCliFailure?.();
         }
       } catch { /* ordinary non-JSON CLI output */ }
       if (!rt.parse)
-        return handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit: onInitAll, onUsage, onRateLimit: onRate, onModel: onRanOn });
+        return handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit: onInitAll, onUsage, onRateLimit: onRate, onModel: onRanOn, subagents });
       const ev = rt.parse(line, cwd);
       if (!ev) return;
       // The conversation id, when the runtime announces one (codex's
       // thread.started). Purely additive: callers that pass no onThreadId —
       // every dispatch path — see zero behavior change.
       if (ev.threadId) {
-        if (rt.id === 'codex') codexThread = ev.threadId;
+        if (rt.id === 'codex') { codexThread = ev.threadId; codexAgents?.thread(ev.threadId); }
         onThreadId?.(ev.threadId);
       }
       // The runtime's own token count (codex's `turn.completed`) — the same
       // `onUsage` Claude's result event feeds, so a caller charges a turn
       // identically whichever CLI ran it.
+      for (const update of ev.subagents ?? []) codexAgents?.update(update);
+      if (rt.id === 'codex') {
+        try { const item = JSON.parse(line)?.item; const result = codexSpawnResult(item); if (result) opts.onSpawnResult?.(result); } catch { /* non-JSON */ }
+      }
       if (ev.toolEvent) onToolEvent?.(...ev.toolEvent);
       if (ev.usage) onUsage?.(ev.usage);
       // One agent MESSAGE, alone — see parseCodexLine's `answer`. Last call
@@ -478,11 +520,13 @@ function runPlainTurn(opts) {
      * legitimately, and the wiki/plan-check/consult turns still ask for Claude
      * by default. On such a machine the first wiki sweep would have killed the
      * whole daemon, taking every in-flight build with it, because one
-     * background job could not find one binary. Any other spawn error
-     * resolves what was captured so far.
+     * background job could not find one binary. Other spawn errors reject
+     * this turn with the native reason; the lane records a failed report.
      */
     const onSpawnError = (e) => {
       input?.close();
+      void codexAgents?.stop();
+      void claudeProgress?.stop();
       if (opts.liveMessages) void opts.liveMessages.stop();
       finishDiagnostics({ pid: child.pid, spawnError: typeof e.code === 'string' ? e.code : 'SPAWN_ERROR' });
       releaseArgs();
@@ -492,7 +536,7 @@ function runPlainTurn(opts) {
         return;
       }
       console.error(e);
-      resolve(out);
+      reject(e);
     };
     child.on('error', onSpawnError);
     child.on('close', (code, signal) => {
@@ -503,6 +547,17 @@ function runPlainTurn(opts) {
       finishDiagnostics({ code, signal, pid: child.pid, output: out, cliFailed, inputError: stdinError?.code });
       const handBack = async () => {
         if (opts.liveMessages) await opts.liveMessages.stop();
+        // Native transcript reads are readouts too: a stuck filesystem must
+        // not hold the card's answer. Readers stop scheduling before draining.
+        let progressTimer;
+        try {
+          await Promise.race([
+            Promise.all([codexAgents?.stop(), claudeProgress?.stop()]),
+            new Promise(resolve => { progressTimer = setTimeout(resolve, CODEX_MODEL_READ_MS); }),
+          ]);
+        } finally { clearTimeout(progressTimer); }
+        for (const [id, status] of agentStates)
+          if (status === 'running' || status === 'waiting') reportSubagent({ id, status: 'stopped' });
         if (stdinError) {
           if (!workLanesStopped()) rejectTurn(stdinError);
           return;
@@ -537,7 +592,7 @@ function runPlainTurn(opts) {
       }
       handBack();
     });
-    if (stdinText !== null) {
+    if (transport.text !== null) {
       // end() buffers with backpressure and closes at EOF; Codex reads the
       // entire prompt before starting. An early close must not accept output
       // from a turn whose complete authorized input never reached the CLI.
@@ -546,7 +601,7 @@ function runPlainTurn(opts) {
         opts.onCliFailure?.();
         child.kill('SIGTERM');
       });
-      child.stdin.end(stdinText, 'utf8');
+      child.stdin.end(transport.text, 'utf8');
     }
     if (input) {
       const initial = opts.liveMessages.initialPrompt(prompt, resumeThreadId, resume, opts.liveContinuation === true);

package/bin/lib/runtimeClaude.mjs

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { MODEL, USER_AGENT } from './config.mjs';
 import { NO_SETTING_SOURCES, personalClaudeSettings, releaseTurnSettings, withPersonalSettings } from './claudePersonal.mjs';
 import { withMachineMcp } from './claudePosture.mjs';
+import { orchestratorHooks } from './orchestratorHooks.mjs';
 
 /** The profiles an agent lane mounts the machine's MCP servers on (2026-10-11):
  *  the ones whose turn profile says `projectMcp` and that Claude declares. */
@@ -101,7 +102,7 @@ export const CLAUDE_RUNTIME = {
    * strongest form of it available anywhere: `--append-system-prompt` sits
    * above the conversation rather than inside it.
    */
-  args({ writableDirs = [], prompt, system, model, effort, resume, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, streamInput = false }) {
+  args({ writableDirs = [], prompt, system, model, effort, resume, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, streamInput = false, orchestration = false }) {
     // THE CARTOGRAPHER'S FENCE NAMES ITS VAULT (2026-10-10): its one write rule
     // is the vault's absolute path (claudePosture.mjs `wikiPermFor`), so a turn
     // with no vault, or one no rule can name, has no list — refused here in
@@ -169,6 +170,7 @@ export const CLAUDE_RUNTIME = {
      * agent renders the CURRENT base snapshot, not the first turn's cache.
      */
     const fenced = profile !== 'build';
+    if (orchestration && !fenced) a.push('--settings', JSON.stringify({ hooks: orchestratorHooks(), disableAllHooks: false }));
     if (fenced) a.push(...NO_SETTING_SOURCES);
     // A FENCED POSTURE NAMES ITS OWN MODE (2026-10-10). Its lists fence only
     // under the CLI's `default` mode, where a tool the list does not name is

package/bin/lib/runtimeCodex.mjs

@@ -16,6 +16,8 @@ import { ARTIFACT_DIR, FENCE_TMP_DIR } from './artifacts.mjs';
 import { codexPersonalTurn } from './codexPersonal.mjs';
 import { researchFence } from './codexResearch.mjs';
 import { projectReadBoundary, projectReadFence } from './codexProjectRead.mjs';
+import { compareVersions } from './versionOrder.mjs';
+import { codexOrchestratorArgs } from './orchestratorHooks.mjs';
 
 /**
  * FLOWVIANT'S OWN TOOLS NEED NO APPROVAL FROM A CHAT NOBODY CAN ANSWER
@@ -78,9 +80,18 @@ export const NO_REACH_OUT = Object.freeze([
  */
 export const NO_WEB = Object.freeze(['-c', 'tools.web_search=false', '-c', 'web_search="disabled"']);
 
-/** Sub-agents would be a second turn whose posture nobody here chose. */
+/** Fenced lanes and non-card turns never delegate. */
 export const NO_SUBAGENTS = Object.freeze(['-c', 'features.multi_agent=false', '-c', 'features.goals=false']);
 
+/** rust-v0.160.0 core/src/agent/child_config.rs applies the invoking turn's
+ * approval policy, permission profile and cwd AFTER role overrides, for V1
+ * and V2. Older/unmeasured binaries have no inheritance evidence here. */
+export const CODEX_SUBAGENTS_MIN = '0.160.0';
+export function codexSubagentsSafe(version) {
+  const order = compareVersions(String(version ?? '').replace(/^codex-cli\s+/, ''), CODEX_SUBAGENTS_MIN);
+  return order === 0 || order === 1;
+}
+
 /**
  * HERMETIC. Without these a user's ~/.codex/config.toml, a project `.rules`
  * execpolicy file, or their own MCP servers can widen a posture we are
@@ -239,7 +250,7 @@ export const CODEX_RUNTIME = {
    * limit even when its argv plus environment is far below ARG_MAX. Both exec
    * and exec resume support `-` (verified on Codex 0.160.0, 2026-10-16).
    */
-  args({ streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads }) {
+  args({ streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, codexVersion, orchestration = false }) {
     // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
     // agy moves) — codex has no adoptable store wired yet. Reaching here
     // with an adopt id is a wiring mistake upstream, and it fails loudly on
@@ -285,6 +296,10 @@ export const CODEX_RUNTIME = {
       // before it started. `-c sandbox_mode=` means the same on both.
       if (writableDirs.length) a.push('-c', `sandbox_workspace_write.writable_roots=${JSON.stringify(writableDirs)}`);
       a.push('-c', `sandbox_mode="${SAFE ? 'workspace-write' : 'danger-full-access'}"`);
+      if (cardTurn) a.push('-c', 'approval_policy="never"');
+      a.push(...(cardTurn && profile === 'build' && codexSubagentsSafe(codexVersion)
+        ? ['-c', 'features.multi_agent=true', '-c', 'features.goals=false']
+        : NO_SUBAGENTS));
     }
 
     /**
@@ -300,6 +315,7 @@ export const CODEX_RUNTIME = {
     if (a.includes('--ignore-user-config')) a.push(...(personal?.args ?? []));
 
     a.push(...mcp, ...resultSchemaArgs);
+    if (orchestration && !fenced && codexSubagentsSafe(codexVersion)) a.push(...codexOrchestratorArgs());
     a.push(streamInput ? '-' : codexPrompt({ system, prompt, profile }));
     return a;
   },

package/bin/lib/runtimeEvents.mjs

@@ -14,6 +14,8 @@
  * own stream loop and calls `humanizeClaudeTool`/`toolEventOf` from it.
  */
 
+import { codexCollabUpdates } from './codexSubagentEvents.mjs';
+
 /** Truncate for a one-line activity label. */
 const oneLine = (s, n = 140) =>
   String(s ?? '').replace(/\s+/g, ' ').trim().slice(0, n);
@@ -139,6 +141,11 @@ export function countLines(s) {
  *  window minus the cap to straddle out of it — no real credential is. */
 const SCRUB_WINDOW = 8_192;
 
+/** The same window/scrub/cap order for native agent metadata and tools. */
+export function scrubNativeText(value, cap, scrub) {
+  return scrub(String(value ?? '').slice(0, SCRUB_WINDOW)).slice(0, cap);
+}
+
 /**
  * Tool-call → ONE STRUCTURED EVENT for the transcript's tool cards — the
  * relay's durable form, where `humanizeClaudeTool` above is its one-line live
@@ -165,7 +172,7 @@ const SCRUB_WINDOW = 8_192;
 export function toolEventOf(name, input = {}, cwd = '', scrub = (s) => s) {
   // Window → scrub → cap. The window bounds what a multi-MB input costs; the
   // cap is applied AFTER the scrub so a replacement cannot overflow it.
-  const clean = (v, cap) => scrub(String(v ?? '').slice(0, SCRUB_WINDOW)).slice(0, cap);
+  const clean = (v, cap) => scrubNativeText(v, cap, scrub);
   const rel = (p) => clean(shortPath(p, cwd), 300);
   // The first k lines of a side, from a scrubbed bounded prefix — never a
   // full split of the raw string.
@@ -197,6 +204,7 @@ export function toolEventOf(name, input = {}, cwd = '', scrub = (s) => s) {
       return { t: 'glob', q: clean(input.pattern, 200) };
     case 'Bash':
       return { t: 'bash', c: clean(input.command, 200) };
+    case 'Agent':
     case 'Task':
       return { t: 'task', q: clean(input.description, 200) };
     case 'TodoWrite': {
@@ -313,6 +321,9 @@ export function parseCodexLine(line, cwd) {
   } catch {
     return null; // not every line is JSON (warnings go to stderr, but be safe)
   }
+  if (['item.started', 'item.updated', 'item.completed'].includes(ev.type) &&
+      (ev.item?.type ?? ev.item?.item_type) === 'collab_tool_call')
+    return { subagents: codexCollabUpdates(ev.item), activity: null, text: '' };
   switch (ev.type) {
     // The conversation's own id, announced before any item (`ThreadStarted` on
     // the shipped 0.147 binary, like the measured events below). Surfaced so a

package/bin/lib/trace.mjs

@@ -59,7 +59,7 @@
  * tail of a trace, never the settle behind it.
  */
 
-import { THINK_MARKER } from './runtimeEvents.mjs';
+import { THINK_MARKER, scrubNativeText } from './runtimeEvents.mjs';
 import { withoutTurnDeclaration } from './turnDeclaration.mjs';
 
 /** One batch every two seconds — the discipline the tab's narrator keeps, for
@@ -107,7 +107,7 @@ function newRunId() {
  * with no such route, a body the server will never accept). Resolving falsy
  * keeps them queued for the next flush.
  */
-export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run = newRunId() }) {
+export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run = newRunId(), orchestrationVersion }) {
   /** Entries not yet delivered. `base` is the ABSOLUTE index of queue[0] in
    *  THIS RUN's stream, so `base + queue.length` is everything this relay has
    *  ever accepted — sent, queued or shed. Absolute for the TURN is the
@@ -119,7 +119,9 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
    *  empties the queue and a batch boundary is not a change in the stream. Read
    *  by the bare-marker collapse in `prose()` and nothing else. */
   let lastEntry = null;
-  let dirty = false;
+  const agentReadings = new Map();
+  let dirty = orchestrationVersion === 2;
+  let markerPending = dirty;
   let timer = null;
   let stopped = false;
   /** The await chain. Every flush appends to it, so batches leave in order
@@ -149,7 +151,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
 
   const drain = async (deadlineMs) => {
     const until = deadlineMs > 0 ? Date.now() + deadlineMs : 0;
-    while (queue.length) {
+    while (queue.length || markerPending) {
       if (until && Date.now() > until) {
         dirty = true;
         return;
@@ -159,7 +161,9 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
       dirty = false;
       let ok = false;
       try {
-        ok = (await post({ agentId, turnId, run, seq, entries })) !== false;
+        ok = (await post({ agentId, turnId, run, seq, entries,
+          ...(orchestrationVersion === 2 ? { orchestrationVersion } : {}),
+        })) !== false;
       } catch {
         ok = false;
       }
@@ -169,6 +173,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
         dirty = true;
         return;
       }
+      markerPending = false;
       // Remove only what of the batch is STILL at the head: a push during the
       // await may have shed some of it already (advancing `base`), and
       // splicing the whole batch length would then drop entries that were
@@ -188,7 +193,11 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
     return done;
   };
 
+  // The first report stamps even a silent or immediately failed CLI invocation.
+  schedule();
+  const scoped = (id) => id ? `${run}:${scrubNativeText(id, 96, scrub)}` : undefined;
   return {
+    agentId: scoped,
     /**
      * A prose line from the stream. `kind` is the daemon's activity vocabulary
      * (runtimeEvents.mjs); anything that is not thinking or the model speaking is a
@@ -207,7 +216,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
      * CLI's own stdout, and a secret in a thought must not ride further than it
      * did when a thought was 300 characters.
      */
-    prose(kind, text) {
+    prose(kind, text, agentId) {
       const readable = kind === 'think' ? String(text ?? '') : withoutTurnDeclaration(text);
       const t = scrub(readable)
         // One line ending, whatever the CLI printed.
@@ -239,10 +248,10 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
        * never takes a seq, exactly like the empty line above it. The "N earlier
        * steps are not shown" count stays a count of steps that existed.
        */
-      if (k === 'think' && t === THINK_MARKER && lastEntry?.k === 'think' && lastEntry.t === t) {
+      if (k === 'think' && t === THINK_MARKER && lastEntry?.k === 'think' && lastEntry.t === t && lastEntry.agentId === scoped(agentId)) {
         return readable;
       }
-      push({ k, t });
+      push({ k, t, ...(agentId ? { agentId: scoped(agentId) } : {}) });
       // The activity pulse uses this same filtering; its original compact
       // label stands unless protocol text was removed from the full message.
       return readable;
@@ -250,13 +259,42 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
     /** One structured tool event, exactly as `toolEventOf` built it. A tool this
      *  builder does not know returns null there and nothing is pushed here — a
      *  card is never invented. */
-    tool(e) {
-      if (e && typeof e === 'object') push({ k: 'tool', e });
+    tool(e, agentId) {
+      if (e && typeof e === 'object') push({ k: 'tool', e, ...(agentId ? { agentId: scoped(agentId) } : {}) });
+    },
+    agent(update) {
+      if (!update?.id) return;
+      const clean = (v, n) => scrubNativeText(v, n, scrub);
+      const fields = {};
+      for (const [key, cap] of Object.entries({ kind: 80, title: 200, now: 400, brief: 4_000 }))
+        if (typeof update[key] === 'string') fields[key] = clean(update[key], cap);
+      if (typeof fields.now === 'string') fields.now = fields.now.replace(/\s+/g, ' ').trim();
+      if (['running', 'waiting', 'asked', 'stopped', 'done'].includes(update.status)) fields.status = update.status;
+      const previous = agentReadings.get(update.id) ?? {};
+      if (agentReadings.has(update.id) && Object.entries(fields).every(([k, v]) => previous[k] === v)) return;
+      if (!agentReadings.has(update.id) && agentReadings.size >= 32) return;
+      const reading = { ...previous, ...fields };
+      agentReadings.set(update.id, reading);
+      // A later update repairs metadata whose first report was shed while
+      // offline; a delta alone cannot recover the child's prompt or title.
+      push({ k: 'agent', id: scoped(update.id), ...reading });
+    },
+    /** Routing is declared by the orchestrator; no server interpretation. */
+    handoff(agentId, from, text) {
+      push({ k: 'handoff', agentId: scoped(agentId), from: scrub(String(from)).slice(0, 160), t: scrub(String(text)).slice(0, TRACE_PROSE_CAP) });
+    },
+    doing(agentId, text) {
+      push({ k: 'doing', agentId: scoped(agentId), t: scrub(String(text)).slice(0, TRACE_PROSE_CAP) });
     },
     flush,
     /** No more entries, no more timers. The queue survives so a final flush can
      *  still deliver it. */
     stop() {
+      if (!stopped && orchestrationVersion === 2) {
+        // Even a quiet child retains its identity after another child's noisy
+        // stream overflowed the relay. These snapshots remain sequence-safe.
+        for (const [id, reading] of agentReadings) push({ k: 'agent', id: scoped(id), ...reading });
+      }
       stopped = true;
       if (timer) {
         clearTimeout(timer);