Grilling: formalize the subagent-nesting parent-inference rule (including parallel/batch tool calls)

[antejavor]

Part of #275

Question

Given no harness provides an explicit parent link for a spawned subagent, temporal inference (whichever tool call is "open" -- PreToolUse fired, no matching PostToolUse yet -- when SubagentStart arrives) was proposed as the general answer. But Claude Code's PostToolBatch event ("after a full batch of parallel tool calls resolves") implies tool calls can run in parallel/batched, breaking the assumption that exactly one tool call is ever "open" at a time.

Resolve concretely: what's the actual inference rule once parallel/batched tool calls are accounted for? Candidates to grill through: only tool calls matching a specific tool_name (the "Agent"/subagent-spawning tool specifically, not any open call) are eligible parents; some other disambiguation when multiple Agent-type calls are simultaneously open; or accepting an explicit ambiguity/best-effort answer in that rare case rather than a fully deterministic rule. Resolve with the driving user via /grilling + /domain-modeling.

[antejavor]

Resolution

Resolved via /grilling + /domain-modeling with the driving user, verified against the exact SubagentStart payload schema (not just the summary table):

Three-tier parent-inference rule, in order:

1. Filter by tool name. Candidates are tool calls currently open (PreToolUse fired, no matching PostToolUse yet) anywhere within the same session -- not just top-level, since nested subagents report the same top-level session_id on both harnesses -- whose tool_name is a known agent-spawning tool (exact string per harness to be confirmed at implementation time; Claude Code calls it the "Agent" tool per prose, no confirmed exact tool_name string yet). Track open candidates as a set scoped to the session, not a strict single top-of-stack, since parallel batches (Claude Code's PostToolBatch) mean more than one call can be open at once.
2. Disambiguate by type, if more than one candidate is open. Match SubagentStart.agent_type against each open candidate's tool_input's subagent-type field.
3. Honest null on genuine ambiguity, never a guess. If multiple open candidates share the same type (e.g. two parallel subagents of the same kind dispatched together), the parent link comes back unresolved for that SubagentStart, not an arbitrary pick.

Verified explicitly that agent_id does not rescue tier 3: fetched the exact SubagentStart example payload ("agent_id": "agent_abc123def456") -- this is a fresh, independent identifier unrelated to the spawning tool call's tool_use_id pattern (toolu_...). It uniquely identifies each subagent instance (useful for pairing that subagent's own Start↔Stop, and for tagging its own nested tool calls) but gives no path back to which specific parent tool call spawned it.

Explicit requirement for whoever implements this: this rule is derived entirely from documentation, not observed behavior. It must be verified end-to-end against a real dev Memgraph instance with actual live Claude Code and Codex sessions (not just unit tests against synthetic payloads) before being trusted -- flagged explicitly by the driving user, not optional polish.

Feeds directly into #278 (what node type this produces) and #283 (the separate question of whether Claude Agent SDK should get a stronger, non-inferred link via the message-stream API instead of this rule).

[antejavor]

Correction (2026-08-17), found while resolving Map: Live Claude Code verification for the SPAWNED subagent-nesting inference rule — exactly the live-session verification this ticket flagged as required before trusting the rule:

The tool that actually launches a subagent reports tool_name: "Agent" in real PreToolUse/PostToolUse hook payloads — not "Task" as this ticket's resolution assumed (doc-derived, not observed at the time). "Task" turns out to be how Claude Code's CLI/UI refers to it (e.g. --allowedTools=Task), not what shows up in tool-call hook data.

actions-graph's agent_spawning_tool_names default was {"Task"}, meaning the SPAWNED inference rule never actually matched anything against a real Claude Code session — Tier 1 silently failed every time. Fixed to {"Agent", "Task"} (keeping both, since harness/version differences aren't fully characterized) and verified end-to-end against three consecutive live sessions. See map #288 for the full verification writeup.