Event Schema

Every event shares a common envelope; the event-specific payload lives in data.

Envelope

{
  "ts": "2026-05-12T14:23:01.456Z",
  "event": "tool_use",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "seq": 42,
  "data": { }
}

The same envelope is used for local JSONL and for POST /api/v1/events.

Two names for four events

The plugin writes every event to ~/.claude/trenchcoat/events-YYYY-MM-DD.jsonl under a local name, then translates four of them to a wire name before sending. The payload is identical either way — only event changes.

All other types use the same name in both places. This matters when you are reading raw JSONL and querying the API in the same breath — grep tool_use finds nothing on disk, and event=tool_start matches nothing over the API.

Below, headings use the wire name, with the local name noted where they differ.

Event types

The API also accepts an error type, which the plugin does not currently emit.

Only these types are pushed. A local event type the ingest schema does not accept is written to JSONL but never queued — the API validates the whole batch, so one unrecognized type would reject every event alongside it.

Optional fields below are omitted entirely when they do not apply — they are not sent as null.

session_start

{ "cwd": "/Users/alice/projects/my-app" }

session_end

{ "duration_ms": 5062100 }

Token totals and cost are not on this event — they are derived server-side from the assistant_stop events in the session.

prompt_submit

Local name: prompt

{ "prompt_length": 184, "word_count": 31 }

By default this event records the shape of your prompt, never its content.

tool_use

Local name: tool_start

{
  "tool_name": "Bash",
  "tool_use_id": "toolu_01ABC...",
  "correlation_id": "9f86d081b8ac",
  "input_preview": "ls -la /Users/alice/projects"
}

tool_result

Local name: tool_end

{
  "tool_name": "Bash",
  "tool_use_id": "toolu_01ABC...",
  "correlation_id": "9f86d081b8ac",
  "duration_ms": 634,
  "duration_source": "native",
  "result_size": 1428,
  "is_error": false,
  "error_preview": null
}

A duration_source of reconciled means the plugin never saw the tool finish and closed the record out at the end of the turn — treat those durations as upper bounds.

skill_use

Emitted instead of tool_use when the invoked tool is a Skill.

{
  "skill_name": "superpowers:brainstorming",
  "activation_id": "3c9a1e7f2b04",
  "args_preview": "redesign the connect command"
}

assistant_stop

Local name: stop

{
  "reason": "end_turn",
  "input_tokens": 12400,
  "output_tokens": 2340,
  "cache_creation_tokens": 1800,
  "cache_read_tokens": 96000,
  "model": "claude-sonnet-4-6"
}

Cache fields are separate from input_tokens because they are priced differently; session cost is derived from all four.

subagent_start

{ "agent_id": "3c9a1e7f2b04", "agent_type": "general-purpose", "agent_kind": "builtin" }

subagent_stop

{
  "agent_id": "3c9a1e7f2b04",
  "agent_type": "general-purpose",
  "agent_kind": "builtin",
  "tool_counts": { "Read": 4, "Bash": 2 },
  "tool_count_total": 6,
  "turns": 5,
  "input_tokens": 8210,
  "output_tokens": 1340,
  "model": "claude-haiku-4-5",
  "stop_hook_active": false
}

pre_compact

{}

Carries no payload. Its value is the timestamp — it marks where context was compacted, which is often where a session's behavior changes.

Edge labels

When one agent spawns another via the Agent tool, the spawning agent can annotate why by embedding a marker anywhere in the Task prompt:

[tc:delegate]
[tc:verify]
[tc:critique]

If the label matches one of those three (case-insensitive), it is:

1. Recorded as edge_label on both the tool_use and matching tool_result for that Agent invocation.
2. Stripped from the prompt before truncation into input_preview, so the marker never appears in the stored preview and does not consume the truncation budget.

Unrecognized markers are left in place and ignored — no edge_label is emitted. The convention applies only to the Agent tool.

Caveat — parallel spawns. agent_id correlation and edge-label attachment both assume at most one Agent spawn in flight per session. With concurrent spawns, attribution may be ambiguous between siblings, and any latency or label derived from it inherits that ambiguity. Serial spawns are unaffected.

Schema stability

data is stored as jsonb and is not strictly validated at ingest, so the schema can evolve without breaking older clients. Fields documented here are stable; new fields may appear without a major version bump. Removals and renames are announced in the changelog.