Summary

Add first-class session/task chain tracking so OpenClaw can reconstruct subagent execution DAGs without external loggers.

Problem

Today we can partially infer spawn relationships via spawnedBy, sessions.list(spawnedBy=...), and subagent registry, but we cannot reliably reconstruct an end-to-end chain in one place:

• no canonical chain fields exposed for all spawned sessions
• no stable trace identifier across a multi-hop task
• no direct visibility of parent/root lineage in sessions_list results

This makes analysis/debugging hard (e.g., "which parent spawned this subagent", "did any subagent spawn further", "show full chain for a run").

Proposal (Phase 1: minimal, backward-compatible)

Data model (SessionEntry)

• parentSessionKey?: string
• rootSessionKey?: string
• traceId?: string
• spawnDepth?: number

Spawn write path

When sessions_spawn creates a child session:

• set parentSessionKey = requester session key
• set rootSessionKey = parent.rootSessionKey ?? parentSessionKey
• set traceId = parent.traceId ?? uuid
• set spawnDepth = (parent.spawnDepth ?? 0) + 1

Gateway/tool read path

Expose chain metadata in session listing rows so tooling/UI can consume it immediately:

• include spawnedBy, parentSessionKey, rootSessionKey, traceId, spawnDepth in sessions.list output (optional fields)

Why this helps

• enables deterministic DAG reconstruction from session APIs
• reduces need for workspace-local dispatch/task loggers
• provides a stable foundation for future chain APIs/visualization

Non-goals in this issue

• no behavior change for spawn permissions
• no recursive spawning policy changes
• no new mandatory fields (all optional for compatibility)

Follow-up (Phase 2)

• add dedicated gateway method for chain traversal (e.g., sessions.chain)
• chain-aware UI view (tree/graph)
• optional task-level correlation for non-spawn tool calls