Grilling: does a subagent instance become a first-class Agent node, or stay a flat Action pair with a populated PARENT_OF?

[antejavor]

Part of #275

Question

Today, SubagentStart/SubagentStop are just another action_type value on a generic (:Action) node, sitting in the same flat per-session FOLLOWED_BY chain as everything else -- there's no node that "contains" the subagent's own tool-call sequence as children. Two candidate shapes once #2 (the inference rule) resolves:

(a) Introduce a first-class (:Agent) node (or similar) that a spawning tool call points at, which itself owns its own internal FOLLOWED_BY-sequenced tool-call actions -- a real tree, not a flat log with a pointer.
(b) Keep the existing flat Action-typed SubagentStart/SubagentStop pair, and just populate parent_action_id (feeding the already-existing but currently-dead PARENT_OF relationship) pointing at the spawning tool call.

Resolve which shape, and if (a), what properties/fields the new node carries. Blocked on #2 since the exact parent-linking mechanism shapes what there even is to attach a new node to. Resolve with the driving user via /grilling + /domain-modeling.

[antejavor]

Resolution

Resolved via /grilling + /domain-modeling with the driving user:

First-class (:Agent) node, not a flat Action pair with a populated PARENT_OF:

• (:Agent {agent_id, agent_type, started_at, ended_at, last_assistant_message, ...}) -- SubagentStart/SubagentStop are no longer separate Action nodes; the same information becomes lifecycle properties on one entity instead of two events sitting loosely in the session's flat timeline. Rationale: matches the precedent set reversing the Episode decision (Grilling: what does continuous episodic-memory organization mean? #261) -- dedicated node types for owned data (Memory, Action, Chunk, now Agent) rather than growing another type's property set indefinitely.
• (:Session)-[:HAS_AGENT]->(:Agent) -- unconditional, every Agent gets this regardless of whether Grilling: formalize the subagent-nesting parent-inference rule (including parallel/batch tool calls) #277's inference rule actually resolved a parent tool call. This is what keeps a genuinely-ambiguous subagent (tier 3 from Grilling: formalize the subagent-nesting parent-inference rule (including parallel/batch tool calls) #277) reachable rather than orphaned.
• (:Action)-[:SPAWNED]->(:Agent) -- additional, layered on only when a parent tool call was actually resolved (Grilling: formalize the subagent-nesting parent-inference rule (including parallel/batch tool calls) #277 tiers 1/2). Honestly reflects "we don't know" for the ambiguous case rather than hiding it.
• (:Agent)-[:HAS_ACTION]->(:Action) -- the agent's own tool-call sequence, in its own separate chain. Recurses naturally for further-nested agents (a nested Action can itself -[:SPAWNED]-> a further Agent).
• FOLLOWED_BY is scoped per container -- a Session has its own chain, each Agent has its own separate chain. Not one flat chain spanning the whole tree, as today.
• Agent.agent_id (the harness-provided identifier) is the node's unique key, matching Memory.memory_id/Action.action_id's existing pattern.
• PARENT_OF / Action.parent_action_id -- deleted outright, not deprecated. Confirmed dead code (never populated by any real adapter) with nothing depending on it.

Feeds #280 (Skill Usage attaching to the specific Agent, now that a real node exists to attach to) and the synthesis ticket #282.

[antejavor]

Correction (2026-08-14): the premise behind deleting PARENT_OF outright was wrong in one respect. actions-graph has a second, independent integration surface — actions_graph.hooks (ActionTracker/create_tracking_hooks, a direct Claude Agent SDK hooks={...} integration that bypasses agent-context-graph entirely) — that does populate parent_action_id/PARENT_OF for real subagent nesting: pre_tool_use links a tool call made inside a subagent back to that subagent's SubagentStart action, and subagent_stop links back to its own SubagentStart. This is actively tested in test_hooks.py and was missed when this ticket originally checked only agent-context-graph's claude_code.py/connector.py path.

Resolution (confirmed with the driving user): migrate hooks.py's ActionTracker onto the same Agent node model as connector.py, rather than freezing it as legacy or ripping it out. The separate, unrelated use of parent_action_id/PARENT_OF for ToolResult→ToolCall correlation (in both connector.py and hooks.py) is a different concept — not subagent nesting — and stays as-is, out of scope for this map.