feat(lineage): park confirmations issued by unplaced Claude starts; regression tests on the 2.1.259 orchestration capture (#422)

Author: ScriptedAlchemy

.changeset/422-claude-spawn-confirmation.md

@@ -3,4 +3,4 @@
 "agent-bundle": patch
 ---
 
-Take Claude Code's own word for a subagent's parent: the parent's `Agent` `PostToolUse` carries the spawn `tool_use_id` and `tool_response.agentId`, the child's `agent_id`, so the lineage registry behind `request.lineage` now confirms the edge it matched from spawn-call ordering, fills in `subagent.toolCallId` for siblings it had claimed blind, places a `SubagentStart` no spawn window could (none open, or two parents with one — the start's id, type, time and stop are kept meanwhile), moves a child it had filed under the wrong parent and re-bases that child's descendants, and holds a child the host names before its start arrives. Add `'confirmed'` to `AgentLineageResolution` (`@agent-bundle/runtime`, `RequestLineageProvenance` in `agent-bundle`): a subagent's `parent`/`root`/`depth` resolve `confirmed` once every edge up to the root is host-named — right after `SubagentStart` for a background spawn, after `SubagentStop` for a foreground one — and stay `registry` otherwise. The Claude capability table's `lineage.parent`/`lineage.depth` rows record the confirmation and its timing, and the generated hosts page gains a "Conversation lineage" section rendered from every host's `lineage` rows. (#422)
+Take Claude Code's own word for a subagent's parent: the parent's `Agent` `PostToolUse` carries the spawn `tool_use_id` and `tool_response.agentId`, the child's `agent_id`, so the lineage registry behind `request.lineage` now confirms the edge it matched from spawn-call ordering, fills in `subagent.toolCallId` for siblings it had claimed blind, places a `SubagentStart` no spawn window could (none open, or two parents with one — the start's id, type, time, stop, and any confirmations it issued for its own children are kept meanwhile, so a missed spawn hook at one level does not lose the subtree beneath it), moves a child it had filed under the wrong parent and re-bases that child's descendants, and holds a child the host names before its start arrives. Add `'confirmed'` to `AgentLineageResolution` (`@agent-bundle/runtime`, `RequestLineageProvenance` in `agent-bundle`): a subagent's `parent`/`root`/`depth` resolve `confirmed` once every edge up to the root is host-named — right after `SubagentStart` for a background spawn, after `SubagentStop` for a foreground one — and stay `registry` otherwise. The Claude capability table's `lineage.parent`/`lineage.depth` rows record the confirmation and its timing, and the generated hosts page gains a "Conversation lineage" section rendered from every host's `lineage` rows. (#422)

docs/audits/2026-09-03-host-lineage-matrix.md

@@ -321,7 +321,7 @@ gives shell commands the agent runs `CURSOR_CONVERSATION_ID`/`CURSOR_REQUEST_ID`
 
 | Host | Root | Parent |
 | --- | --- | --- |
-| Claude | Yes — `session_id` on every event is the root session (re-verified live: all 42 + 46 + 127 hook payloads across the three runs carry the root id — through resumed turns and a compaction too — and `CLAUDE_CODE_SESSION_ID` in every plugin process is the root id) | Only through the runtime's registry (inferred at `SubagentStart`); nothing in the child's payload |
+| Claude | Yes — `session_id` on every event is the root session (re-verified live: all 42 + 46 + 127 hook payloads across the three runs carry the root id — through resumed turns and a compaction too — and `CLAUDE_CODE_SESSION_ID` in every plugin process is the root id) | Only through the runtime's registry (placed at `SubagentStart`, confirmed by the parent's `Agent` PostToolUse); nothing in the child's payload |
 | Codex | Yes — `session_id` is the root thread on every event, and `_meta.x-codex-turn-metadata.session_id` on MCP calls | Yes on MCP calls (`parent_thread_id`); on hooks only through the registry (or the parent rollout at `SubagentStop`) |
 | Cursor | Only through the registry — a child's payload carries neither root nor parent | Only through the registry (ordering-bound) |
 
@@ -354,7 +354,7 @@ root, and the parent-of-subagent chain — is the only identity-adjacent surface
 | Roots first seen on a tool hook (Cursor restart or plugin load mid-conversation) | Cursor | §9 | Ours: workspace-scoped child binding plus correction (subtree re-rooted) when a bound conversation later carries a root-only event (`beforeSubmitPrompt`, `stop`, `sessionEnd`, `preCompact`) |
 | Cursor CLI not exercised | Cursor | table above | Needs a signed-in `cursor-agent`; not attempted on the operator's account |
 | ~~Claude session used a scripted model~~ | Claude | §8 | Closed 2026-09-03: two live-model sessions replace the stand-in fixture; every stand-in claim held, see §8 |
-| Claude `PostToolUse(Agent).tool_response.agentId` not consumed by the registry | Claude | §1, §2 | The registry claims the newest unclaimed spawn under the root at `SubagentStart` and marks same-parent sibling cohorts `siblingsUncertain`; the parent's `Agent` PostToolUse could later firm those up. Not needed for any live run: even the orchestration run's two parallel spawns arrived serialised (`SubagentStart` before the next `Agent` `PreToolUse`), so every claim was certain; left as an improvement |
+| ~~Claude `PostToolUse(Agent).tool_response.agentId` not consumed by the registry~~ | Claude | §1, §2 | Closed 2026-09-03 (#422 follow-up PR): the registry now treats the parent's `Agent` PostToolUse as the host's word on the edge — it confirms the spawn-window match (`resolution: confirmed` once every edge to the root is host-named), fills in sibling `toolCallId`s claimed blind, places a `SubagentStart` no window could (an unplaced start keeps id/type/time/stop, and any confirmations it issued for its own children, until its edge is known), moves a child filed under the wrong parent and re-bases its descendants, and holds a child named before its start (orchestration row 13 → 14). Replays of the orchestration capture with row 64 or row 81 withheld recover the sequential agent and the depth-2 child from rows 99/101 alone |
 | ~~Claude interactive OAuth session expired; refresh fails~~ | Claude | header table | Closed 2026-09-03: after the operator signed in again, the unmodified harness (`probe:install claude` byte-for-byte copy of `~/.claude/.credentials.json`) produced the signed-in 2.1.259 orchestration session. The two 2.1.257 runs had used a one-off re-seed of the isolated `.credentials.json` outside the harness (`docs/audits/2026-09-03-claude-live-session-proofs.md`); no credential-handling code was ever added |
 | `stream-json` shows depth-1 subagent traffic only | Claude | §1 (orchestration run) | The nested agent's 7 tool calls appear in hooks (with its `agent_id`) but in no stream envelope; `task_started` still announces it with `spawn_depth: 2`. Hooks remain the only complete lineage source; recorded, no framework impact |
 | Auto-compaction (`PreCompact trigger: "auto"`) not induced | Claude | §1 (orchestration run) | Manual `/compact` as a resumed `-p` prompt fires `PreCompact` → `SessionStart source: compact` → `PostCompact`; the automatic path would need a session near the context limit and was not attempted |

docs/entry-conventions.md

@@ -463,7 +463,12 @@ as the host's word on the edge, whatever it believed before:
   parent were claimed blind, so `subagent.toolCallId` appears after the fact;
 - it places an unplaced start under the parent, as it started (time, type,
   and already stopped when its stop came first), and consumes the spawn call
-  so no later start can claim it;
+  so no later start can claim it; a confirmation an unplaced start issued
+  for its own children waits with it and is applied when it is placed, so a
+  missed spawn hook at one level does not lose the subtree beneath it
+  (replaying the 2.1.259 capture without the root's spawn `PreToolUse`
+  recovers both the sequential agent and its depth-2 child from the two
+  `PostToolUse` payloads alone);
 - it moves a child the window filed under the wrong parent (a missed spawn
   `PreToolUse` leaves another parent's open call as the only candidate) and
   re-bases everything the child spawned meanwhile;

packages/agent-bundle/src/adapters/capabilities/claude-2.1.250.json

@@ -177,7 +177,7 @@
       "reason": "live model 2026-09-03, Claude Code 2.1.257 and 2.1.259: no hook payload a subagent itself emits names its parent (#422: SubagentStart carries only the child agent_id and agent_type, and a subagent's own hooks carry session_id + agent_id; the hooks reference's common input fields list session_id, transcript_path, cwd, permission_mode, agent_id and agent_type, no parent). The runtime registry places the child under the Agent/Task PreToolUse that is the newest unclaimed spawn when SubagentStart fires (resolution: registry) — exact for sequential spawns and for the 2.1.259 parallel pair (the host serialises SubagentStart before the next Agent PreToolUse), verified at depth 1 and 2 in background, foreground and parallel spawn paths, refused as id-not-resolvable when two parents have unclaimed spawns, toolCallId withheld when siblings from one parent were claimed blind — and then takes the host's own word for the edge: the parent's Agent PostToolUse carries the spawn tool_use_id, the parent's identity and tool_response.agentId, the child. That hook confirms the edge (resolution: confirmed once every edge up to the root is host-named), fills in the sibling→tool_use_id assignment, places a start the window could not, and moves a child the window filed under the wrong parent, re-basing its descendants. It arrives right after SubagentStart for a background spawn (status async_launched; in 2.1.259 even before it) but only after the child's SubagentStop for a foreground one (status completed), so a foreground child's own events resolve as registry for their whole life. The host's stream-json task_started envelope (task_id, tool_use_id, spawn_depth) agrees with every placement but is not delivered to plugins.",
       "evidence": [
         "live model 2026-09-03, Claude Code 2.1.257 (fixtures/host-lineage/claude-2.1.257.ndjson rows 17 and 41; claude-2.1.257-foreground.ndjson rows 47 and 49): the parent's Agent PostToolUse tool_response is {isAsync: true, status: \"async_launched\", agentId} for a background spawn and {status: \"completed\", agentId, agentType, content[]} for a foreground one; agentId equals the agent_id on the child's SubagentStart, SubagentStop and every hook the child fired.",
-        "live model 2026-09-03, Claude Code 2.1.259 (fixtures/host-lineage/claude-2.1.259-orchestration.ndjson): all four Agent PostToolUse payloads name their child — rows 13 and 17 (background Explore and general-purpose, async_launched; row 13 fires before that child's SubagentStart at row 14, so the registry holds the node by the host's word and the start adds its agent_type), row 99 (the depth-1 agent's own PostToolUse, carrying its agent_id, names the depth-2 child, completed) and row 101 (the root's, naming the depth-1 agent, completed); the depth-2 child's SubagentStart (row 82) and every hook it fires carry only its own agent_id and the root session_id, nothing that names the depth-1 parent.",
+        "live model 2026-09-03, Claude Code 2.1.259 (fixtures/host-lineage/claude-2.1.259-orchestration.ndjson): all four Agent PostToolUse payloads name their child — rows 13 and 17 (background Explore and general-purpose, async_launched; row 13 fires before that child's SubagentStart at row 14, so the registry holds the node by the host's word and the start adds its agent_type), row 99 (the depth-1 agent's own PostToolUse, carrying its agent_id, names the depth-2 child, completed) and row 101 (the root's, naming the depth-1 agent, completed); the depth-2 child's SubagentStart (row 82) and every hook it fires carry only its own agent_id and the root session_id, nothing that names the depth-1 parent. Replays of that capture with the root's spawn PreToolUse (row 64) or the depth-1 agent's (row 81) withheld leave the affected starts unplaced until rows 99/101 place them — the sequential agent under the root and the depth-2 child under it, with the start and stop times the hooks carried (packages/rsc-runtime/tests/lineage-registry.test.ts). The child's SubagentStop agent_transcript_path is <session>/subagents/agent-<agent_id>.jsonl for depth-1 and depth-2 children alike (rows 57, 61, 98, 100), and Stop/SubagentStop background_tasks[] entries carry id, type, status, description and agent_type but no tool_use_id or parent, so neither path nor list can bind a nested child to its parent.",
         "uploaded 2026-09-03, Claude Code docs hooks reference (hooks-2.md, \"Common input fields\": agent_id and agent_type are the only subagent fields hooks add, no parent; \"SubagentStart\"/\"SubagentStop\": agent_id, agent_type, agent_transcript_path under the parent's transcript folder, background_tasks scoped to the parent session; \"PostToolUse\": tool_name, tool_input, tool_response, tool_use_id) and sub-agents reference (sub-agents-3.md, \"Resume subagents\": when a subagent completes Claude receives its agent ID — the id the registry matches to agent_id — and the one-shot built-in Explore and Plan agents return no agent ID to Claude, so a spawn whose tool_response omits agentId keeps the registry's own match; observed 2.1.259 background Explore responses did carry agentId)."
       ]
     },

packages/rsc-runtime/src/lineage/registry.ts

@@ -591,25 +591,31 @@ export const createAgentLineageRegistry = (
         if (event === 'tool/failure' && SPAWN_TOOLS[host](toolName)) {
           await dispatch('spawnFailed', { toolCallId }, keys);
         }
-        // The spawn's own post-tool hook names the child (Claude
-        // `tool_response.agentId`): the carrier is the parent, by the host's
-        // word. That places a start the claim window could not, confirms an
-        // edge it matched, or moves one it matched wrong — the same event in
-        // every case, so a redelivery is idempotent.
-        const confirmation = event === 'tool/after' && SPAWN_TOOLS[host](toolName)
-          ? SPAWN_CONFIRMATIONS[host](native)
-          : undefined;
-        if (confirmation !== undefined && confirmation.child !== carrier.conversation) {
-          await dispatch('spawnConfirmed', {
-            at: observedAt,
-            child: confirmation.child,
-            ...(confirmation.completed ? { completed: true } : {}),
-            parent: carrier.conversation,
-            toolCallId,
-          }, keys);
-        }
       }
     }
+    // The spawn's own post-tool hook names the child (Claude
+    // `tool_response.agentId`): the carrier is the parent, by the host's word.
+    // That places a start the claim window could not, confirms an edge it
+    // matched, or moves one it matched wrong — the same event in every case,
+    // so a redelivery is idempotent. A carrier that is itself an unplaced
+    // start keeps the confirmation until its own edge is known.
+    const confirmation = event === 'tool/after' && toolName !== undefined && SPAWN_TOOLS[host](toolName)
+      ? SPAWN_CONFIRMATIONS[host](native)
+      : undefined;
+    if (
+      confirmation !== undefined
+      && carrier.conversation !== undefined
+      && confirmation.child !== carrier.conversation
+      && (carrierNode !== undefined || (state.unplacedStarts ?? []).some((start) => start.id === carrier.conversation))
+    ) {
+      await dispatch('spawnConfirmed', {
+        at: observedAt,
+        child: confirmation.child,
+        ...(confirmation.completed ? { completed: true } : {}),
+        parent: carrier.conversation,
+        ...(toolCallId === undefined ? {} : { toolCallId }),
+      }, keys);
+    }
     return resolve(host, native, host === 'cursor' ? 'inferred' : 'registry');
   };
 

packages/rsc-runtime/src/lineage/state.ts

@@ -58,7 +58,22 @@ export const OpenToolCallSchema = z.object({
  * later host confirmation of the edge (Claude's `Agent` PostToolUse naming the
  * child) materializes the node as it started, not as it was confirmed.
  */
+/** The host named a spawn edge: `parent` produced `child` through `toolCallId` (see `spawnConfirmed`). */
+export const SpawnConfirmationSchema = z.object({
+  at: timestamp,
+  child: id,
+  completed: z.boolean().optional(),
+  parent: id,
+  toolCallId: id.optional(),
+}).strict();
+
 export const UnplacedStartSchema = z.object({
+  /**
+   * Edges this start confirmed for its own children while it was still
+   * unplaced; applied the moment the start itself is placed, so a missed
+   * spawn hook at one level does not lose the subtree beneath it.
+   */
+  confirmations: z.array(SpawnConfirmationSchema).optional(),
   generation: id.optional(),
   id,
   root: id,
@@ -97,6 +112,7 @@ export const LineageStateSchema = z.object({
 export type LineageNode = z.output<typeof LineageNodeSchema>;
 export type OpenToolCall = z.output<typeof OpenToolCallSchema>;
 export type UnplacedStart = z.output<typeof UnplacedStartSchema>;
+export type SpawnConfirmation = z.output<typeof SpawnConfirmationSchema>;
 export type LineageState = z.output<typeof LineageStateSchema>;
 
 export const lineageEventSchemas = {
@@ -122,13 +138,7 @@ export const lineageEventSchemas = {
    * `confirmed`; a pending spawn call with that `toolCallId` is consumed.
    * `completed` says the child has already finished from the host's view.
    */
-  spawnConfirmed: z.object({
-    at: timestamp,
-    child: id,
-    completed: z.boolean().optional(),
-    parent: id,
-    toolCallId: id.optional(),
-  }).strict(),
+  spawnConfirmed: SpawnConfirmationSchema,
   /** A spawn call failed before any child started, so no later start may claim it. */
   spawnFailed: z.object({ toolCallId: id }).strict(),
   /** A subagent started but no single spawn call could be claimed for it; the edge waits for a host confirmation. */
@@ -311,14 +321,25 @@ export const reduceLineage = (
       };
     }
     case 'spawnConfirmed': {
-      const { at, child, completed, parent: parentId, toolCallId } = event.payload as {
-        at: string; child: string; completed?: boolean; parent: string; toolCallId?: string;
-      };
+      const confirmation = event.payload as SpawnConfirmation;
+      const { at, child, completed, parent: parentId, toolCallId } = confirmation;
       const parent = state.nodes[parentId];
       const existing = state.nodes[child];
+      if (child === parentId || existing?.depth === 0) return state;
+      if (parent === undefined) {
+        // The parent is itself waiting for its edge: keep the confirmation
+        // with it, to apply the moment the parent is placed.
+        const unplaced = state.unplacedStarts ?? [];
+        if (!unplaced.some((start) => start.id === parentId)) return state;
+        return {
+          ...state,
+          unplacedStarts: unplaced.map((start) => start.id === parentId
+            ? { ...start, confirmations: [...(start.confirmations ?? []).filter((kept) => kept.child !== child), confirmation] }
+            : start),
+        };
+      }
       // A root never becomes a child on a host's say-so, and no parent may be
       // made to descend from its own child; the confirmation is then noise.
-      if (parent === undefined || child === parentId || existing?.depth === 0) return state;
       const descendants = existing === undefined ? new Set<string>() : descendantsOf(state.nodes, child, existing.root);
       if (descendants.has(parentId)) return state;
       const waiting = (state.unplacedStarts ?? []).find((start) => start.id === child);
@@ -349,7 +370,7 @@ export const reduceLineage = (
         call.root !== placed.root && (call.conversation === child || descendants.has(call.conversation))
           ? { ...call, root: placed.root }
           : call;
-      return {
+      const placedState: LineageState = {
         ...state,
         nodes: pruneStopped({
           ...Object.fromEntries(Object.entries(state.nodes).map(([key, node]) => [key, moved(node)])),
@@ -367,6 +388,11 @@ export const reduceLineage = (
           ? {}
           : { unplacedStarts: (state.unplacedStarts ?? []).filter((start) => start.id !== child) }),
       };
+      // Edges the child confirmed for its own children while unplaced follow it into the tree.
+      return (waiting?.confirmations ?? []).reduce(
+        (next, kept) => reduceLineage(next, { name: 'spawnConfirmed', payload: kept }),
+        placedState,
+      );
     }
     case 'sessionRetired': {
       const { root } = event.payload as { root: string };