Labels: architecture, observability, tracing, P0

Summary

Create one canonical run trace schema that works across main agent runs, ACP sessions, subagents, and task flows.

Why

Tracing exists, but it is fragmented and too low-level. When a run goes wrong, it is hard to quickly answer:

• what happened
• what step failed
• what tools were involved
• whether delegation happened
• how parent and child runs relate

Scope

Define a schema with fields like:

• runId
• sessionKey
• parentRunId
• taskId
• stepId
• eventType
• eventSource
• toolName
• handoffType
• status
• startedAt
• endedAt
• latencyMs
• summary

Adopt it in:

• core agent tracing
• ACP parent-child relay paths
• task execution progress and terminal events

Likely files

• src/agents/trace-base.ts
• src/agents/cache-trace.ts
• src/agents/acp-spawn-parent-stream.ts
• src/tasks/task-executor.ts
• new: src/agents/run-trace.ts

Acceptance criteria

• one canonical trace schema exists
• main, ACP, and subagent/task runs emit into it
• parent-child linkage is preserved
• step-level and tool-level events are supported
• trace data can reconstruct a compact run timeline

Checklist

• define schema types
• add parent-child linkage fields
• map current trace producers to schema
• update ACP relay path
• update task executor paths
• add tests