Runtime agent support. Adds execution_context discriminator and runtime outcome signals for action-trajectory agents.
Read the full schema documentation for design rationale and usage guides, or see contributing to the schema to propose changes.
Root record. One per session, one JSONL line.
| field | type | description | |
|---|---|---|---|
| schema_version | string | req | e.g. "0.2.0" |
| trace_id | string | req | UUID for this trace |
| session_id | string | req | Agent's native session ID |
| content_hash | string | SHA-256 for deduplication | |
| timestamp_start | string | ISO 8601 start | |
| timestamp_end | string | ISO 8601 end | |
| task | Task | Task metadata | |
| agent | Agent | req | Agent identity |
| environment | Environment | OS, shell, VCS, languages | |
| system_prompts | dict | Deduplicated prompts keyed by hash | |
| tool_definitions | dict[] | Available tool schemas | |
| steps | Step[] | TAO-loop steps | |
| outcome | Outcome | Session outcome | |
| dependencies | string[] | Project dependencies | |
| metrics | Metrics | Aggregated metrics | |
| security | SecurityMetadata | Security tier and redactions | |
| attribution | Attribution | Code attribution (experimental) | |
| metadata | dict | Extensible key-value pairs | |
| execution_context | string | null | "devtime" (code-editing agent) or "runtime" (action-trajectory / RL agent). Null for pre-0.2 traces. |
Task metadata for filtering and grouping.
| field | type | description | |
|---|---|---|---|
| description | string | What the task is | |
| source | string | user_prompt, cli_arg, skill, etc. | |
| repository | string | owner/repo format | |
| base_commit | string | Starting commit SHA |
Agent identity.
| field | type | description | |
|---|---|---|---|
| name | string | req | claude-code, cursor, codex, etc. |
| version | string | Agent version | |
| model | string | provider/model-name |
Runtime context.
| field | type | description | |
|---|---|---|---|
| os | string | darwin, linux, etc. | |
| shell | string | zsh, bash, etc. | |
| vcs | VCS | type, base_commit, branch, diff | |
| language_ecosystem | string[] | python, typescript, etc. |
One LLM API call in the TAO loop.
| field | type | description | |
|---|---|---|---|
| step_index | int | req | Sequential index |
| role | string | req | system | user | agent |
| content | string | Message content | |
| reasoning_content | string | Chain-of-thought | |
| model | string | Model for this step | |
| system_prompt_hash | string | Key into system_prompts | |
| agent_role | string | main, explore, plan, etc. | |
| parent_step | int | Parent step index | |
| call_type | string | main | subagent | warmup | |
| subagent_trajectory_ref | string | Sub-agent session ID | |
| tools_available | string[] | Available tool names | |
| tool_calls | ToolCall[] | Tool invocations | |
| observations | Observation[] | Tool results | |
| snippets | Snippet[] | Extracted code blocks | |
| token_usage | TokenUsage | Token breakdown | |
| timestamp | string | ISO 8601 |
A tool invocation within a step.
| field | type | description | |
|---|---|---|---|
| tool_call_id | string | req | ID for linking to observations |
| tool_name | string | req | Tool name |
| input | dict | Input parameters | |
| duration_ms | int | Wall-clock time |
Tool result linked to its ToolCall.
| field | type | description | |
|---|---|---|---|
| source_call_id | string | req | Links to ToolCall |
| content | string | Full output | |
| output_summary | string | Lightweight preview | |
| error | string | Error info if failed |
Per-step token breakdown.
| field | type | description | |
|---|---|---|---|
| input_tokens | int | Input tokens | |
| output_tokens | int | Output tokens | |
| cache_read_tokens | int | From cache | |
| cache_write_tokens | int | Written to cache | |
| prefix_reuse_tokens | int | Via prefix caching |
Session outcome for reward modeling.
| field | type | description | |
|---|---|---|---|
| success | boolean | Goal achieved | |
| signal_source | string | Default: "deterministic" | |
| signal_confidence | string | derived | inferred | annotated | |
| description | string | Outcome description | |
| patch | string | Unified diff | |
| committed | boolean | Changes committed to git | |
| commit_sha | string | Commit SHA | |
| terminal_state | string | null | "goal_reached", "interrupted", "error", or "abandoned". Meaningful for runtime agents. | |
| reward | float | null | Numeric reward signal from an RL environment or evaluator. | |
| reward_source | string | null | Canonical values: "rl_environment", "judge", "human_annotation", "orchestrator". |
Code attribution (experimental).
| field | type | description | |
|---|---|---|---|
| experimental | boolean | Always true in v0.1.x | |
| files | AttributionFile[] | Per-file line ranges |
Session-level aggregates.
| field | type | description | |
|---|---|---|---|
| total_steps | int | Step count | |
| total_input_tokens | int | Sum of input tokens | |
| total_output_tokens | int | Sum of output tokens | |
| total_duration_s | float | Wall-clock seconds | |
| cache_hit_rate | float | 0.0 to 1.0 | |
| estimated_cost_usd | float | Estimated cost |
Security mode and redaction record.
| field | type | description | |
|---|---|---|---|
| tier | int | 1 (auto), 2 (review) | |
| flags_reviewed | int | Flags reviewed | |
| redactions_applied | int | Redactions applied | |
| classifier_version | string | Classifier version |
{
"schema_version": "0.2.0",
"trace_id": "a4f2b8c1-e2d3-4f5a-b6c7-d8e9f0a1b2c3",
"session_id": "sess_0x8f2a1b3c",
"content_hash": "e3b0c44298fc1c14...",
"timestamp_start": "2026-03-27T14:30:00Z",
"task": {
"description": "Add input validation to the signup form",
"repository": "acme/webapp",
"base_commit": "a1b2c3d4"
},
"agent": {
"name": "claude-code",
"version": "1.0.32",
"model": "anthropic/claude-sonnet-4-20250514"
},
"environment": {
"os": "darwin",
"shell": "zsh",
"vcs": { "type": "git", "branch": "main" },
"language_ecosystem": ["typescript"]
},
"system_prompts": {
"abc123": "You are Claude Code..."
},
"steps": [
{
"step_index": 0,
"role": "user",
"content": "Add Zod validation to the signup form"
},
{
"step_index": 1,
"role": "agent",
"content": "I'll add Zod validation...",
"model": "anthropic/claude-sonnet-4-20250514",
"system_prompt_hash": "abc123",
"agent_role": "main",
"call_type": "main",
"tool_calls": [{
"tool_call_id": "tc_001",
"tool_name": "Edit",
"input": { "file_path": "src/signup.tsx" },
"duration_ms": 120
}],
"observations": [{
"source_call_id": "tc_001",
"output_summary": "Added Zod schema to signup form",
"content": "File edited successfully"
}],
"token_usage": {
"input_tokens": 4200,
"output_tokens": 1800,
"cache_read_tokens": 3800,
"prefix_reuse_tokens": 3800
}
}
],
"outcome": {
"success": true,
"signal_source": "deterministic",
"signal_confidence": "derived",
"committed": true,
"commit_sha": "f5e6d7c8"
},
"metrics": {
"total_steps": 2,
"total_input_tokens": 8400,
"total_output_tokens": 1800,
"cache_hit_rate": 0.9,
"estimated_cost_usd": 0.24
},
"security": { "tier": 2, "redactions_applied": 1 }
}