flowviant 0.125.5 → 0.125.6

package/bin/lib/nativeAgentTools.mjs

@@ -0,0 +1,72 @@
+/**
+ * WHICH NATIVE TOOLS THE ORCHESTRATION GATE ACTS ON (2026-10-18 SOLID pass).
+ *
+ * The gate's fail-closed list (hooks/orchestrator.mjs), the controller's
+ * spawn/follow-up/stop/ask/discovery checks (orchestrator.mjs), Claude's
+ * post-hook matcher (orchestratorHooks.mjs) and the Claude/Codex child
+ * readers each spelled these by hand, and the hook's copy of the naming rule
+ * had already lost two of the controller's names. The fail-closed hook must
+ * gate exactly what the controller admits: a name missing from the hook's
+ * copy fails OPEN while the controller is down, so that spawn escapes the
+ * project's pool (docs/agent-orchestration.md, Hook transport). Both CLIs
+ * have renamed these before (Claude's Task to Agent plus SendMessage in
+ * 2.1.302, Codex's V1 to V2 collab namespaces in 0.160/0.163); a rename is a
+ * row here.
+ *
+ * A leaf: the hook process loads it on every tool call, and must load no HTTP
+ * server or fleet credential with it.
+ */
+
+/** Each CLI's native subagent tools, by what the gate does with them. */
+export const NATIVE_AGENT_TOOLS = Object.freeze({
+  claude: Object.freeze({
+    spawn: Object.freeze(['Agent', 'Task']),
+    // Claude Code 2.1.302 continues a spawned child with SendMessage({to}).
+    followup: Object.freeze(['SendMessage']),
+    // Claude children run in the background so the orchestrator stays
+    // available for notes and their questions.
+    background: Object.freeze(['Agent', 'Task']),
+    stop: Object.freeze(['TaskStop']),
+    ask: Object.freeze(['AskUserQuestion']),
+    discovery: Object.freeze(['ToolSearch']),
+  }),
+  codex: Object.freeze({
+    spawn: Object.freeze(['spawn_agent']),
+    followup: Object.freeze(['followup_task', 'resume_agent', 'send_input']),
+    // Codex spawns are already asynchronous.
+    background: Object.freeze([]),
+    stop: Object.freeze(['interrupt_agent', 'close_agent']),
+    // Seen in a rollout, never gated.
+    message: Object.freeze(['send_message']),
+    ask: Object.freeze(['request_user_input']),
+    discovery: Object.freeze(['tool_search', 'search_tool']),
+  }),
+});
+
+// Codex 0.160 V2 serializes the namespace without punctuation in hook
+// tool_name (measured: collaborationspawn_agent). V1 spawn has an alias.
+// V1 writes it as `multi_agent_v1.` (the hook's note, moved here with its
+// copy of this rule).
+export const nativeName = name => String(name ?? '').split(/[./]/).at(-1).replace(/^(collaboration|multi_agent_v1)(?=spawn_agent|followup_task|resume_agent|send_input|interrupt_agent|close_agent)/, '');
+
+const every = row => Object.freeze(Object.values(NATIVE_AGENT_TOOLS).flatMap(tools => tools[row] ?? []));
+const SPAWN = every('spawn'), FOLLOWUP = every('followup'), BACKGROUND = every('background');
+const DISCOVERY = every('discovery'), ASK = every('ask');
+
+export const isSpawnTool = name => SPAWN.includes(nativeName(name));
+export const isFollowupTool = name => FOLLOWUP.includes(nativeName(name));
+export const isBackgroundSpawnTool = name => BACKGROUND.includes(nativeName(name));
+export const isDiscoveryTool = name => DISCOVERY.includes(nativeName(name));
+export const isPersonQuestionTool = name => ASK.includes(nativeName(name));
+export const isClaudeFollowupTool = name => NATIVE_AGENT_TOOLS.claude.followup.includes(nativeName(name));
+// The controller reads only Claude's stop: TaskStop names its child as task_id.
+export const isClaudeStopTool = name => NATIVE_AGENT_TOOLS.claude.stop.includes(nativeName(name));
+
+/** What the hook refuses while the controller is unreachable: every spawn and
+ * follow-up the controller gates. */
+export const GATED_TOOLS = Object.freeze([...SPAWN, ...FOLLOWUP]);
+export const gatedSpawnEvent = event => event?.hook_event_name === 'PreToolUse' && GATED_TOOLS.includes(nativeName(event.tool_name));
+
+/** Claude's PostToolUse and PostToolUseFailure matcher (orchestratorHooks.mjs):
+ * its spawns and follow-ups. */
+export const CLAUDE_POST_HOOK_MATCHER = [...NATIVE_AGENT_TOOLS.claude.spawn, ...NATIVE_AGENT_TOOLS.claude.followup].join('|');

package/bin/lib/orchestrator.mjs

@@ -1,39 +1,48 @@
 /** A run-scoped loopback capability. Only this daemon holds fleet credentials;
  * native tools and MCP clients receive a random capability for this one run. */
-import { createServer } from 'node:http';
-import { randomBytes, randomUUID } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import { sameSecret } from './grant.mjs';
+import { randomUUID } from 'node:crypto';
 import { fleetRequest } from './fleetPost.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { DAEMON_INSTANCE, FLEET_URL } from './config.mjs';
-import { runningCompiledBinary } from './launchCommand.mjs';
+import { listenHeldTool, mintHeldCapability } from './heldTool.mjs';
 import { scrubNativeText } from './runtimeEvents.mjs';
 import { scrub, learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
 import { OrchestratorInputTooLarge, readOrchestratorInput } from './orchestratorInput.mjs';
+import { SAFE_POINT_AFTER_EDIT as AFTER_EDIT } from './orchestratorProtocol.mjs';
+import { MACHINE_MESSAGE_ROUTE_STATES, MESSAGE_ROUTE_FIELD_MAX, OPEN_MESSAGE_ROUTE_STATES, ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
+import { isClaudeStopTool, isDiscoveryTool, isFollowupTool, isPersonQuestionTool, isSpawnTool } from './nativeAgentTools.mjs';
+import { followupTarget, readSpawn, spawnReceipt, withChildContract } from './orchestratorNative.mjs';
+import { SETTLED_SUBAGENT_STATUSES, SUBAGENT_CAP, SUBAGENT_FIELD_CAPS } from './subagentBounds.mjs';
 
 const WAIT = 'Waiting for a free slot on the machine';
-// Codex 0.160 V2 serializes the namespace without punctuation in hook
-// tool_name (measured: collaborationspawn_agent). V1 spawn has an alias.
-const nativeName = name => String(name ?? '').split(/[./]/).at(-1).replace(/^(collaboration|multi_agent_v1)(?=spawn_agent|followup_task|resume_agent|send_input|interrupt_agent|close_agent)/, '');
-const spawnTool = name => ['Agent', 'Task', 'spawn_agent'].includes(nativeName(name));
-const resumeTool = name => ['followup_task', 'resume_agent', 'send_input'].includes(nativeName(name));
-const terminal = status => ['done', 'stopped'].includes(status);
+const HELD = 'At the checkpoint for a message';
+const terminal = status => SETTLED_SUBAGENT_STATUSES.includes(status);
+const filled = s => typeof s === 'string' && s.trim().length > 0;
+// A safe point is the model's prose: compare its words, not case or punctuation.
+const pointOf = s => String(s ?? '').trim().toLowerCase().replace(/\s+/g, ' ').replace(/^["'“‘`]+|["'”’`.!?;:,…]+$/g, '');
 const text = (s, n) => scrubNativeText(s, n, scrub);
 
-
-
-export async function createOrchestrator({ turnId, runtime, trace, admit, request = fleetRequest, notify = () => {}, taken = () => {},
-  interval = 500, scrubText = text } = {}) {
+export async function createOrchestrator({ turnId, runtime, trace, admit, request = fleetRequest, notify = () => false, taken = () => {},
+  interval = 500, hold = 60_000, clock = Date.now, scrubText = text } = {}) {
   if (typeof admit !== 'function' || typeof admit.reserve !== 'function') throw new Error('This run has no project admission pool.');
-  const capability = randomBytes(32).toString('hex');
+  // Minted before the server exists, so the scrubber knows it from the start.
+  const capability = mintHeldCapability();
   const secretKey = `orchestrator:${turnId}:${capability.slice(0, 8)}`;
   learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_ORCHESTRATOR_CAPABILITY', value: capability }]);
-  const records = new Map(), aliases = new Map(), calls = new Map(), notes = new Map(), inbox = new Map(), questions = new Map();
+  const records = new Map(), aliases = new Map(), calls = new Map(), notes = new Map(), questions = new Map();
+  // A person's notes (Codex) and the daemon's wakes queue apart: a burst of
+  // wakes never evicts a note input() accepted.
+  const inbox = new Map(), wakes = new Map();
   const pending = new Map(), steps = new Map();
-  let closed = false, polling = false, rootSession = null;
+  let closed = false, polling = false, rootSession = null, offerAt = 0;
   const identity = { scope: 'agent', turnId, instance: DAEMON_INSTANCE };
   const resolve = id => aliases.get(id) ?? id;
+  // A re-held note keeps its native id; resolve it when matched, not when held.
+  const target = note => note.agentId ? resolve(note.agentId) : undefined;
+  const spawnable = a => !a.started && !a.resumable;
+  // Both CLIs name a child by agent_id on its hooks; session_id is the root's
+  // (measured on Claude 2.1.302 and Codex 0.163).
+  const childOf = ev => ev.agent_id ?? (rootSession && ev.session_id && ev.session_id !== rootSession ? ev.session_id : null);
   const emit = update => {
     const id = resolve(update.id), prior = records.get(id) ?? { id };
     const reading = { ...prior, ...update, id };
@@ -42,24 +51,32 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     records.set(id, reading); trace.agent(reading); return reading;
   };
   const release = id => { const a = records.get(resolve(id)); a?.release?.(); if (a) a.release = null; };
-  const announce = message => { if (!closed) {
-    inbox.set(randomUUID(), message); if (inbox.size > 64) inbox.delete(inbox.keys().next().value);
-    notify(message);
-  } };
+  // A wake the root CLI did not take (stdin closed; Codex always) waits for
+  // the root's next tool hook, where both CLIs read additionalContext.
+  const announce = message => {
+    if (closed || notify(message) === true) return;
+    wakes.set(randomUUID(), message); if (wakes.size > 64) wakes.delete(wakes.keys().next().value);
+  };
+  const field = (key, value, cap) => { const v = filled(value) ? scrubText(value, cap) : ''; return v.trim() ? { [key]: v } : {}; };
   const route = async args => {
     const note = notes.get(args.messageId);
     if (!note) throw new Error('That note is not held by this run.');
-    if (!['queued', 'handed', 'taken'].includes(args.state)) throw new Error('Choose queued, handed or taken.');
-    const id = args.agentId ? resolve(args.agentId) : undefined;
+    if (!MACHINE_MESSAGE_ROUTE_STATES.includes(args.state)) throw new Error('Choose queued, handed or taken.');
+    const id = filled(args.agentId) ? resolve(args.agentId) : undefined;
     const a = id ? records.get(id) : null;
-    if (args.state !== 'taken' && (!a || !args.safePoint || !args.kind)) throw new Error('Name the agent, its kind and this note’s safe point.');
-    if (args.state === 'handed' && a?.status === 'waiting') throw new Error('The agent has not started yet. Keep this note queued.');
+    if (args.state !== 'taken' && (!a || !filled(args.safePoint) || !filled(args.kind))) throw new Error('Name the agent, its kind and this note’s safe point.');
+    // A child held at a checkpoint has started; only a spawn still waiting for its slot cannot take a note.
+    if (args.state === 'handed' && a.status === 'waiting' && spawnable(a)) throw new Error('The agent has not started yet. Keep this note queued.');
     // Flush the descriptor before the holder-bound route write validates it.
     await trace.flush(1_000);
-    const next = { state: args.state, runtime, ...(id ? { agentId: trace.agentId(id), nativeAgentId: scrubText(a.nativeId ?? id, 160), kind: scrubText(args.kind, 80), safePoint: scrubText(args.safePoint, 200) } : {}) };
+    // Only what exists is reported: the API refuses a whole route over an unknown agent or an empty field.
+    const next = { state: args.state, runtime, ...(a ? { agentId: trace.agentId(id), nativeAgentId: scrubText(a.nativeId ?? id, MESSAGE_ROUTE_FIELD_MAX.id),
+      ...field('kind', args.kind, MESSAGE_ROUTE_FIELD_MAX.kind), ...field('safePoint', args.safePoint, MESSAGE_ROUTE_FIELD_MAX.safePoint) } : {}) };
     const result = await request(fleetEndpoint('agent-message-route', FLEET_URL), { body: { ...identity, messageId: args.messageId, route: next }, timeoutMs: 10_000 });
     if (!result.ok || !result.json?.data?.reported) throw new Error('The route was not recorded. Re-read the note and retry.');
-    Object.assign(note, args, { agentId: id });
+    Object.assign(note, args, { agentId: a ? id : undefined, paused: false, delivering: false });
+    if (a && args.state !== 'queued' && a.status === 'waiting' && a.now === HELD && ![...notes.values()].some(n => n.paused && n.state === 'queued' && target(n) === id))
+      emit({ id, status: 'running', now: 'Continuing with the orchestrator’s note' });
     taken(args.messageId); // the model naming the UUID proves receipt
     // The API stores the handoff atomically with the route; a crash between
     // this receipt and a trace flush must not lose or duplicate that item.
@@ -72,125 +89,181 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     a.release = admit.reserve();
     return true;
   }
-  const match = input => [...records.values()].find(a => a.brief === (input.prompt ?? input.message ?? '') && a.status === 'waiting');
+  // A slot the timer holds belongs to the run's waiting spawns, not to one
+  // exact prompt: a reworded retry takes it, by title or kind, else the oldest.
+  // Without one, a retry of the same brief or title is still that one record.
+  const claim = ({ brief, title, kind }) => {
+    const open = [...records.values()].filter(a => a.status === 'waiting' && spawnable(a)), held = open.filter(a => a.release);
+    return held.find(a => a.brief === brief) ?? held.find(a => title && a.title === title) ?? held.find(a => kind && a.kind === kind)
+      ?? held[0] ?? open.find(a => a.brief === brief) ?? open.find(a => title && a.title === title);
+  };
+  // Admitted: the offer is spent, and notes that paused this child are being
+  // delivered, so its checkpoint lets it work until their route lands.
+  const start = (a, now) => {
+    a.started = true; a.denied = null; a.heldAt = null; a.stops = 0;
+    for (const n of notes.values()) if (n.paused && n.state === 'queued' && target(n) === a.id) n.delivering = true;
+    if (questions.get(a.id)?.answer) questions.get(a.id).read = true;
+    emit({ id: a.id, status: 'running', now });
+  };
   function preSpawn(event) {
-    const input = event.tool_input ?? {}, callId = event.tool_use_id;
-    if (!callId || typeof (input.prompt ?? input.message) !== 'string') throw new Error('A native spawn needs its call id and prompt.');
-    const waiting = match(input);
-    const resumed = input.resume && records.has(resolve(input.resume)) ? resolve(input.resume) : null;
-    const id = resumed ?? waiting?.id ?? resolve(callId);
+    const spawn = readSpawn(event);
+    if (!spawn) return { deny: 'Give this native spawn a text prompt or message so the run can gate it.' };
+    const { callId, brief } = spawn;
+    const resumed = spawn.resume !== null && records.has(resolve(spawn.resume)) ? resolve(spawn.resume) : null;
+    const id = resumed ?? claim(spawn)?.id ?? resolve(callId);
     aliases.set(callId, id); calls.set(callId, id);
     if (aliases.size > 256) aliases.delete(aliases.keys().next().value);
     if (calls.size > 128) calls.delete(calls.keys().next().value);
-    if (!records.has(id) && records.size >= 32) return { deny: 'This run already has 32 agent records. Continue the work yourself.' };
-    const a = emit({ id, brief: input.prompt ?? input.message, title: input.description ?? input.task_name ?? '',
-      kind: input.subagent_type ?? input.agent_type ?? '', status: 'waiting', now: WAIT });
-    if (!slot(id)) return { deny: `${WAIT}. Agent id: ${id}. Keep working yourself; you will be told when this spawn can be retried. Do not wait for a child that has not started.` };
-    a.started = true;
-    a.checkpointSaid = false;
-    emit({ id, status: 'running', now: a.title });
-    const promptKey = typeof input.prompt === 'string' ? 'prompt' : 'message';
+    if (!records.has(id) && records.size >= SUBAGENT_CAP) return { deny: `This run already has ${SUBAGENT_CAP} agent records. Continue the work yourself.` };
+    const a = emit({ id, brief, title: spawn.title ?? '', kind: spawn.kind ?? '', status: 'waiting', now: WAIT });
+    if (!slot(id)) { a.denied = resumed ? 'resume' : 'spawn'; return { deny: `${WAIT}. Agent id: ${id}. Keep working yourself; you will be told when this spawn can be retried. Do not wait for a child that has not started.` }; }
+    // Claude's SendMessage addresses a child by its Agent `name`, Codex V2 by its task name.
+    for (const name of spawn.names) if (filled(name) && name.length <= 160) aliases.set(name, id);
+    start(a, a.title);
     const childContract = `\n\nCard orchestrator agent record id: ${id}. FIRST call card_orchestrator.register_agent with agentId=${id} before doing work (tool discovery is allowed). Share this worktree and preserve others’ edits. Ask questions through card_orchestrator.agent_question with agentId=${id}; read its answer before proceeding. Only your orchestrator escalates person-only decisions. Return your work to it; it owns the card’s final commit and JSON.`;
-    return { context: `Agent record id: ${id}. Use it with card_orchestrator for routing and questions.`,
-      updatedInput: { ...input, ...(['Agent', 'Task'].includes(nativeName(event.tool_name)) ? { run_in_background: true } : {}), [promptKey]: input[promptKey] + childContract } };
+    return { context: `Agent record id: ${id}. Use it with card_orchestrator for routing and questions.${spawn.relocated ? ' Its isolation and cwd were removed: children share this card’s worktree on this machine.' : ''}`,
+      updatedInput: withChildContract(event, spawn, childContract) };
+  }
+  // Native readings never revive a settled record or start a waiting spawn
+  // or follow-up (Codex records a refused call's start anyway); only an
+  // admitted spawn or follow-up does.
+  // …except the CLI's own run of a follow-up admitted while the child ran,
+  // counted again if its held slot already lapsed.
+  const resumeQueued = a => { a.queued = false; slot(a.id); emit({ id: a.id, status: 'running', now: 'Continuing with the orchestrator’s note' }); };
+  const apply = (id, update) => {
+    const a = records.get(id), { status: _status, now: _now, ...metadata } = update;
+    if (terminal(a.status) && a.queued && update.status === 'running') { resumeQueued(a); return; }
+    if ((a.status === 'waiting' && (!a.started || a.denied)) || terminal(a.status)) { emit({ ...metadata, id }); return; }
+    if (terminal(update.status)) { settle(id, update); return; }
+    emit({ ...update, id, ...(questions.has(id) && !questions.get(id).answer ? { status: 'asked' } : {}) });
+  };
+  function settle(id, update) {
+    const a = records.get(id), live = Boolean(a.release) && !a.denied;
+    // Claude 2.1.302 and Codex 0.163 run a child again when it finished before
+    // a follow-up queued while it ran reached a tool round: hold its slot until
+    // that run's own stop.
+    if (a.stops > 1) a.queued = false;
+    if (!a.queued) release(id); else a.heldAt ??= clock();
+    if (terminal(a.status)) return;
+    emit({ ...update, id, ...(questions.has(id) && !questions.get(id).answer ? { status: 'asked' } : {}) });
+    if (live) for (const note of notes.values()) if (note.state === 'queued' && target(note) === id)
+      announce(`Agent ${id} finished. Deliver note ${note.messageId} in its next task or a native follow-up and report handed at that checkpoint.`);
   }
   const bind = (native, id) => {
     if (typeof native !== 'string' || native.length > 160 || !id) return;
     const target = resolve(id); aliases.set(native, target);
     if (records.has(target)) records.get(target).nativeId = native;
     if (pending.has(native)) {
-      const update = pending.get(native);
-      if (terminal(update.status)) release(target);
-      emit({ ...update, id: target }); pending.delete(native);
+      const update = pending.get(native); pending.delete(native);
+      if (records.has(target)) apply(target, update);
     }
     for (const step of steps.get(native) ?? []) step(target);
     steps.delete(native);
     if (aliases.size > 256) aliases.delete(aliases.keys().next().value);
   };
+  // Codex V2 names a child `backend` or `/root/backend` interchangeably.
+  const named = native => {
+    if (aliases.has(native) || records.has(native)) return resolve(native);
+    const hits = new Set([...aliases].filter(([k]) => k.endsWith(`/${native}`) || native.endsWith(`/${k}`)).map(([, v]) => v));
+    return hits.size === 1 ? [...hits][0] : native;
+  };
   function postSpawn(event) {
     const id = calls.get(event.tool_use_id);
     if (!id) return;
-    let output = event.tool_response;
-    try { if (typeof output === 'string') output = JSON.parse(output); } catch { /* native plain output */ }
-    if (Array.isArray(output)) output = output.map(b => b.text ?? '').join('');
-    try { if (typeof output === 'string') output = JSON.parse(output); } catch { /* native prose */ }
-    bind(output?.agent_id ?? output?.agentId ?? output?.thread_id ?? output?.agent_path, id);
-    for (const block of output?.content ?? []) {
-      if (typeof block.text !== 'string') continue;
-      try { const parsed = JSON.parse(block.text); bind(parsed.agent_id ?? parsed.thread_id ?? parsed.agent_path, id); } catch { /* prose */ }
-    }
-    if (output?.is_error || output?.isError || event.error) { release(id); emit({ id, status: 'stopped' }); }
+    const { ids, failed } = spawnReceipt(event);
+    for (const native of ids) bind(native, id);
+    if (failed) { release(id); emit({ id, status: 'stopped' }); }
   }
   function preResume(event) {
-    const input = event.tool_input ?? {};
-    const native = input.target ?? input.id;
-    if (typeof native !== 'string' || native.length > 160) return { deny: 'Name the native agent to resume.' };
-    const id = resolve(native);
+    const input = event.tool_input ?? {}, { claude, native } = followupTarget(event);
+    if (native === null) return claude ? null : { deny: 'Name the native agent to resume.' };
+    const id = named(native);
     if (!records.has(id)) {
-      if (records.size >= 32) return { deny: 'Continue the work in this run’s orchestrator.' };
-      emit({ id, kind: '', title: native, brief: input.message ?? '', status: 'waiting', now: WAIT });
+      // SendMessage also reaches "main" and teammates: only a known child is a follow-up.
+      if (claude) return null;
+      if (records.size >= SUBAGENT_CAP) return { deny: 'Continue the work in this run’s orchestrator.' };
+      emit({ id, kind: '', title: native, brief: typeof input.message === 'string' ? input.message : '', status: 'waiting', now: WAIT, resumable: true });
     }
-    if (!slot(id)) { emit({ id, status: 'waiting', now: WAIT }); return { deny: `${WAIT}. Retry the native follow-up when notified. Agent id: ${id}` }; }
-    records.get(id).started = true; records.get(id).checkpointSaid = false;
-    emit({ id, status: 'running', now: 'Continuing with the orchestrator’s note' });
+    if (spawnable(records.get(id))) return { deny: `Agent ${id} has not started. Retry its native spawn instead.` };
+    // A refused follow-up retried on its offered slot reaches a finished child.
+    const prior = records.get(id), running = Boolean(prior.release) && !prior.denied && !terminal(prior.status);
+    if (!slot(id)) { records.get(id).denied = 'resume'; emit({ id, status: 'waiting', now: WAIT }); return { deny: `${WAIT}. Retry the native follow-up when notified. Agent id: ${id}` }; }
+    start(records.get(id), 'Continuing with the orchestrator’s note');
+    records.get(id).queued = running;
     calls.set(event.tool_use_id, id);
     return typeof input.message === 'string' ? { updatedInput: { ...input,
       message: input.message + `\n\nCurrent card orchestrator agent record id: ${id}. Before continuing work, call card_orchestrator.register_agent with this id. Return questions to the orchestrator.` } } : {};
   }
   function checkpoint(event) {
-    const id = resolve(event.agent_id ?? event.session_id);
+    const child = childOf(event);
+    if (!child || isDiscoveryTool(event.tool_name) || String(event.tool_name).includes(ORCHESTRATOR_SERVER)) return {};
+    const id = resolve(child);
     if (!records.has(id)) return {};
-    const queued = [...notes.values()].filter(n => n.state === 'queued' && n.agentId === id);
-    if (!queued.length) return {};
     // The orchestrator, not this hook, chose each checkpoint. Pause tool
-    // execution at its next boundary and ask the parent to use native stop /
-    // follow-up. The child keeps its worktree and transcript intact.
-    const edits = queued.filter(n => n.safePoint === 'after its current edit');
+    // execution at its next boundary, once per note, and ask the parent for a
+    // native follow-up. The child keeps its worktree and transcript intact.
+    const edits = [...notes.values()].filter(n => n.state === 'queued' && target(n) === id && !n.delivering && pointOf(n.safePoint) === AFTER_EDIT);
     if (!edits.length) return {};
-    if (records.get(id).checkpointSaid) return { deny: 'Remain at the checkpoint until your orchestrator sends the follow-up.' };
-    records.get(id).checkpointSaid = true;
-    emit({ id, status: 'waiting', now: 'At the checkpoint for a message' });
-    announce(`Agent ${id} is between tools. Stop it with the native tool and resume/follow up with note ${edits.map(n => n.messageId).join(' ')} plus its work so far. Then report handed.`);
+    const fresh = edits.filter(n => !n.paused);
+    if (!fresh.length) return { deny: 'Remain at the checkpoint until your orchestrator sends the follow-up. Your card_orchestrator tools still work.' };
+    for (const n of fresh) n.paused = true;
+    const native = records.get(id).nativeId;
+    emit({ id, status: 'waiting', now: HELD });
+    announce(`Agent ${id} is between tools. ${runtime === 'claude' ? `Send it note ${fresh.map(n => n.messageId).join(' ')} with SendMessage to ${native ?? 'its agent id'}; it arrives at its next tool round` :
+      `Stop it with the native tool and resume/follow up with note ${fresh.map(n => n.messageId).join(' ')} plus its work so far`}. Then report handed.`);
     return { deny: 'Your orchestrator has a note for this checkpoint. Stop editing and wait for its follow-up; keep your work so far.' };
   }
+  function hook(ev) {
+    // A child's next tool round carries a follow-up queued to it; after its
+    // stop, its own tool use is the CLI running it again with that follow-up.
+    const kid = records.get(resolve(childOf(ev)));
+    if (kid && ['PreToolUse', 'PostToolUse'].includes(ev.hook_event_name)) { if (kid.queued && terminal(kid.status)) resumeQueued(kid); kid.queued = false; }
+    // A native stop (TaskStop takes the agent id or name as task_id) cancels that resume.
+    const stopped = ev.hook_event_name === 'PreToolUse' && isClaudeStopTool(ev.tool_name) && records.get(named(String(ev.tool_input?.task_id ?? '')));
+    if (stopped) { stopped.queued = false; if (terminal(stopped.status)) release(stopped.id); }
+    if (ev.hook_event_name === 'SubagentStop') { const id = resolve(childOf(ev)); if (records.has(id)) { records.get(id).stops = (records.get(id).stops ?? 0) + 1; settle(id, { status: 'done' }); } }
+    if (ev.hook_event_name === 'PostToolUseFailure' && (isSpawnTool(ev.tool_name) || isFollowupTool(ev.tool_name))) {
+      const id = calls.get(ev.tool_use_id); if (id && records.get(id)?.started) { release(id); emit({ id, status: 'stopped', now: 'The native spawn did not start' }); }
+    }
+    if (ev.hook_event_name === 'PreToolUse') {
+      const child = childOf(ev);
+      if (String(ev.tool_name).includes(ORCHESTRATOR_SERVER) && String(ev.tool_name).endsWith('register_agent')) {
+        // Binding the root would pause the orchestrator at its children's checkpoints.
+        if (!child) return { deny: 'Only a native child registers an agent record. As the orchestrator, use the record id with describe_agent, route_message or answer_agent.' };
+        const id = resolve(ev.tool_input?.agentId);
+        if (!records.has(id)) return { deny: 'Use the agent record id in your prompt.' };
+        bind(child, id);
+      }
+      if (child && !records.has(resolve(child)) && !isDiscoveryTool(ev.tool_name))
+        return { deny: 'Before working, call card_orchestrator.register_agent with the agent record id in your prompt. Tool discovery is allowed.' };
+      if (isSpawnTool(ev.tool_name)) return preSpawn(ev);
+      if (isFollowupTool(ev.tool_name)) { const resumed = preResume(ev); if (resumed) return resumed; }
+      const point = checkpoint(ev); if (point.deny) return point;
+      if (isPersonQuestionTool(ev.tool_name))
+        return { deny: 'A child asks its orchestrator with agent_question first. The orchestrator escalates only person-only decisions through the existing blocked JSON question card.' };
+    }
+    if (ev.hook_event_name === 'PostToolUse' && (isSpawnTool(ev.tool_name) || isFollowupTool(ev.tool_name))) postSpawn(ev);
+    return {};
+  }
   async function handle(action, args) {
     if (closed) throw new Error('This run stopped.');
     if (action === 'hook') {
-      const ev = args;
-      if (ev.hook_event_name === 'SubagentStop') { const id = resolve(ev.agent_id ?? ev.session_id); release(id); if (records.has(id)) emit({ id, status: questions.has(id) && !questions.get(id).answer ? 'asked' : 'done' }); }
-      if (ev.hook_event_name === 'PostToolUseFailure' && (spawnTool(ev.tool_name) || resumeTool(ev.tool_name))) {
-        const id = calls.get(ev.tool_use_id); if (id && records.get(id)?.started) { release(id); emit({ id, status: 'stopped', now: 'The native spawn did not start' }); }
-      }
-      if (ev.hook_event_name === 'PreToolUse') {
-        if (String(ev.tool_name).includes('card_orchestrator') && String(ev.tool_name).endsWith('register_agent')) {
-          const id = resolve(ev.tool_input?.agentId);
-          if (!records.has(id)) return { deny: 'Use the agent record id in your prompt.' };
-          bind(ev.agent_id ?? ev.session_id, id);
-        }
-        const child = ev.agent_id ?? (rootSession && ev.session_id !== rootSession ? ev.session_id : null);
-        if (child && !records.has(resolve(child)) && !['tool_search', 'search_tool'].includes(nativeName(ev.tool_name)))
-          return { deny: 'Before working, call card_orchestrator.register_agent with the agent record id in your prompt. Tool discovery is allowed.' };
-        if (spawnTool(ev.tool_name)) return preSpawn(ev);
-        if (resumeTool(ev.tool_name)) return preResume(ev);
-        const point = checkpoint(ev); if (point.deny) return point;
-        if (['AskUserQuestion', 'request_user_input'].includes(nativeName(ev.tool_name)))
-          return { deny: 'A child asks its orchestrator with agent_question first. The orchestrator escalates only person-only decisions through the existing blocked JSON question card.' };
-      }
-      if (ev.hook_event_name === 'PostToolUse' && (spawnTool(ev.tool_name) || resumeTool(ev.tool_name))) postSpawn(ev);
-      if (runtime === 'codex' && !ev.agent_id && rootSession && ev.session_id === rootSession) {
-        const context = [...inbox.entries()].slice(0, 4); for (const [id] of context) inbox.delete(id);
-        return { context: context.map(([, body]) => body).join('\n\n') };
-      }
-      return {};
+      const result = hook(args);
+      // Root PreToolUse/PostToolUse additionalContext is measured on both CLIs.
+      if (result.deny || !['PreToolUse', 'PostToolUse'].includes(args.hook_event_name) || args.agent_id || !rootSession || args.session_id !== rootSession) return result;
+      const held = [];
+      for (const box of [inbox, wakes]) for (const [key, body] of box) if (held.length < 4) { box.delete(key); held.push(body); }
+      return held.length ? { ...result, context: [result.context, ...held].filter(Boolean).join('\n\n') } : result;
     }
     if (action === 'route_message') return route(args);
     const id = resolve(args.agentId);
     // A person’s answer starts a new CLI turn. The parent carries the earlier
     // question and native identity in its own conversation; relay that known
     // context instead of inventing a new child or requiring another question.
-    if (action === 'answer_agent' && !records.has(id) && typeof id === 'string' && id.length > 0 && id.length <= 160 && records.size < 32 &&
+    if (action === 'answer_agent' && !records.has(id) && typeof id === 'string' && id.length > 0 && id.length <= 160 && records.size < SUBAGENT_CAP &&
       typeof args.question === 'string' && args.question.trim() && args.question.length <= 4_000) {
-      emit({ id, kind: scrubText(args.kind ?? '', 80), title: scrubText(args.title ?? '', 200), brief: '', status: 'asked', now: args.question });
+      // Resumable, never spawnable: no slot is offered until a gated follow-up targets it.
+      emit({ id, kind: scrubText(args.kind ?? '', SUBAGENT_FIELD_CAPS.kind), title: scrubText(args.title ?? '', SUBAGENT_FIELD_CAPS.title), brief: '', status: 'asked', now: args.question, resumable: true });
       questions.set(id, { question: args.question });
       if (args.nativeAgentId) bind(args.nativeAgentId, id);
     }
@@ -198,32 +271,36 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     if (!a) throw new Error('Name an agent in this run.');
     if (action === 'register_agent') return { registered: true, agentId: id };
     if (action === 'describe_agent') {
-      if (typeof args.kind !== 'string' || !args.kind.trim() || args.kind.length > 80 || typeof args.title !== 'string' || !args.title.trim() || args.title.length > 200) throw new Error('Give this agent a bounded kind and title.');
+      if (typeof args.kind !== 'string' || !args.kind.trim() || args.kind.length > SUBAGENT_FIELD_CAPS.kind || typeof args.title !== 'string' || !args.title.trim() || args.title.length > SUBAGENT_FIELD_CAPS.title) throw new Error('Give this agent a bounded kind and title.');
       emit({ id, kind: args.kind, title: args.title, namedKind: args.kind, namedTitle: args.title });
       return { recorded: true };
     }
     if (action === 'agent_question') {
       let q = questions.get(id);
+      // The person answers in a later run; the child ends now so this run settles on the question card.
+      if (q?.escalated && !q.answer) return { waiting: true, escalated: true,
+        instruction: 'Your orchestrator escalated this to the person. Stop now: end your work with a short summary of where you are. You will be continued with the answer.' };
+      // A given answer stands for a reworded poll until the child has it.
+      if (q?.answer && (!q.read || q.question === args.question)) { q.read = true; return { answer: q.answer }; }
       if (!q || q.question !== args.question) {
         if (typeof args.question !== 'string' || args.question.length > 4_000) throw new Error('Keep the question within 4000 characters.');
         q = { question: args.question }; questions.set(id, q); emit({ id, status: 'asked', now: args.question });
         trace.prose('note', args.question, id);
         announce(`${a.kind || a.title || id} asks: ${args.question}\nAnswer with answer_agent from the card, code and earlier notes if possible. Escalate only a real person-only decision.`);
       }
-      return q.answer ? { answer: q.answer } : { waiting: true, escalated: q.escalated === true };
+      return { waiting: true, escalated: false };
     }
     if (action === 'answer_agent') {
       const q = questions.get(id); if (!q) throw new Error('That agent has no unanswered question.');
       if (args.escalate === true) { q.escalated = true; return { askingAgent: { id, nativeAgentId: a.nativeId, kind: a.kind, title: a.title },
-        question: `${a.kind || a.title || id} asks: ${q.question}`, instruction: 'Return the existing blocked JSON question card with this attribution. Leave the agent asked until the person answers.' }; }
+        question: `${a.kind || a.title || id} asks: ${q.question}`, instruction: 'The child is told to stop. Once every child has finished or been stopped, return the existing blocked JSON question card with this attribution. Leave the agent asked until the person answers.' }; }
       if (typeof args.answer !== 'string' || !args.answer.trim() || args.answer.length > 4_000) throw new Error('Give the agent a bounded answer.');
       q.answer = args.answer; trace.handoff(id, runtime, args.answer); emit({ id, status: a.release ? 'running' : 'waiting', now: 'Question answered by the orchestrator' });
       return { answered: true, instruction: 'Give this answer to the child with its native follow-up/resume tool.' };
     }
     throw new Error('Unknown orchestration action.');
   }
-  const server = createServer(async (req, res) => {
-    if (closed || req.method !== 'POST' || req.url !== '/' || !sameSecret(req.headers.authorization, `Bearer ${capability}`)) { res.writeHead(403).end(); return; }
+  const respond = async (req, res) => {
     try {
       const { action, args } = await readOrchestratorInput(req);
       const result = await handle(action, args ?? {});
@@ -232,18 +309,28 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(JSON.stringify({
         error: text(error.message, 300), ...(error instanceof OrchestratorInputTooLarge ? { code: error.code } : {}),
       })); }
-  });
-  server.requestTimeout = 5_000;
-  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
-  const env = { FLOWVIANT_ORCHESTRATOR_URL: `http://127.0.0.1:${server.address().port}/`, FLOWVIANT_ORCHESTRATOR_CAPABILITY: capability };
-  const argv = runningCompiledBinary() ? ['__orchestrator-mcp'] : [fileURLToPath(new URL('../cli.mjs', import.meta.url)), '__orchestrator-mcp'];
+  };
+  const { server, env, args: argv } = await listenHeldTool({ envPrefix: 'FLOWVIANT_ORCHESTRATOR', verb: '__orchestrator-mcp', requestTimeoutMs: 5_000,
+    capability, isClosed: () => closed, respond });
   const timer = setInterval(() => {
     if (closed || polling) return;
     polling = true;
     try {
-      for (const a of records.values()) if (a.status === 'waiting' && !a.started && !a.release && slot(a.id)) {
-        emit({ id: a.id, status: 'waiting', now: 'Ready to start' });
-        announce(`A slot is available for agent ${a.id}. Retry its native spawn with the same prompt now; its slot is reserved. If it is no longer needed, finish the run yourself.`);
+      const now = clock();
+      for (const a of records.values()) {
+        // A follow-up sent during the child's last tool round reaches it there
+        // and resumes nothing; on Claude no post hook says so (2.1.302).
+        if (a.queued && a.release && terminal(a.status)) { if (now - (a.heldAt ??= now) >= hold) release(a.id); continue; }
+        if (!a.denied) continue;
+        // An offer the parent leaves unused lapses: the slot returns to the
+        // project's other turns, and this run is offered one again later.
+        if (a.release) { if (now - (a.heldAt ?? now) >= hold) { release(a.id); offerAt = now + hold; emit({ id: a.id, status: 'waiting', now: WAIT }); } continue; }
+        if (now < offerAt || !slot(a.id)) continue;
+        a.heldAt = now;
+        const resume = a.denied === 'resume';
+        emit({ id: a.id, status: 'waiting', now: resume ? 'Ready to continue' : 'Ready to start' });
+        announce(resume ? `A slot is available for agent ${a.id}. Retry its native follow-up${runtime === 'claude' && a.nativeId ? ` (SendMessage to ${a.nativeId})` : ''} now; the slot is held for about a minute. If it is no longer needed, finish the run yourself.`
+          : `A slot is available for agent ${a.id}. Retry its native spawn now, with the same or a reworded prompt; the slot is held for about a minute. If it is no longer needed, finish the run yourself.`);
       }
     } finally { polling = false; }
   }, interval);
@@ -260,37 +347,29 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     attributed(native, step) {
       const id = resolve(native);
       if (records.has(id)) { step(id); return; }
-      if (!steps.has(native) && steps.size >= 32) return;
+      if (!steps.has(native) && steps.size >= SUBAGENT_CAP) return;
       const queue = steps.get(native) ?? []; queue.push(step); if (queue.length > 40) queue.shift(); steps.set(native, queue);
     },
     note(message) { if (!notes.has(message.id) && notes.size < 64) notes.set(message.id, { ...message, messageId: message.id,
-      state: message.route?.state ?? 'deciding', ...(message.route?.nativeAgentId ? { agentId: resolve(message.route.nativeAgentId), safePoint: message.route.safePoint } : {}) }); },
-    outstanding() { return [...notes.values()].filter(n => ['deciding', 'queued'].includes(n.state)).map(n => ({ id: n.messageId, state: n.state, body: n.body, agentId: n.agentId, safePoint: n.safePoint })); },
+      state: message.route?.state ?? 'deciding', ...(message.route?.nativeAgentId ? { agentId: message.route.nativeAgentId, safePoint: message.route.safePoint } : {}) }); },
+    outstanding() { return [...notes.values()].filter(n => OPEN_MESSAGE_ROUTE_STATES.includes(n.state)).map(n => ({ id: n.messageId, state: n.state, body: n.body, agentId: target(n), safePoint: n.safePoint })); },
     input(id, body) { if (closed || inbox.size >= 64 && !inbox.has(id)) return false; inbox.set(id, body); return true; },
     observe(update) {
       if (update.nativeId) bind(update.nativeId, update.id);
       if (update.callId && calls.has(update.callId)) bind(update.id, calls.get(update.callId));
-      let id = resolve(update.id);
+      const id = resolve(update.id);
       if (!records.has(id)) {
         // Bind from a native receipt, never a guessed match on title/kind.
         if (pending.size < 128 || pending.has(id)) pending.set(id, { ...pending.get(id), ...update });
         return;
       }
-      const a = records.get(id);
-      if (a?.status === 'waiting' && !a.started) {
-        const { status: _status, now: _now, ...metadata } = update;
-        emit({ ...metadata, id }); return;
-      }
-      const finished = terminal(update.status);
-      if (finished) release(id);
-      if (questions.has(id) && !questions.get(id).answer) update = { ...update, status: 'asked' };
-      emit({ ...update, id });
-      if (finished) for (const note of notes.values()) if (note.state === 'queued' && note.agentId === id)
-        announce(`Agent ${id} finished. Deliver note ${note.messageId} in its next task or a native follow-up and report handed at that checkpoint.`);
+      apply(id, update);
     },
     async close(stopped = false) {
       closed = true; clearInterval(timer);
-      for (const a of records.values()) { release(a.id); if (!terminal(a.status) && !(a.status === 'asked' && !stopped)) emit({ id: a.id, status: 'stopped', now: stopped ? 'Stopped with the run' : 'Run ended' }); }
+      // Only an escalated question waits for the person; any other asked child ended with the run.
+      for (const a of records.values()) { release(a.id); const q = questions.get(a.id);
+        if (!terminal(a.status) && !(a.status === 'asked' && !stopped && q?.escalated && !q.answer)) emit({ id: a.id, status: 'stopped', now: stopped ? 'Stopped with the run' : 'Run ended' }); }
       server.close(); server.closeAllConnections();
       forgetExtraSecrets(secretKey);
     },