Event schema

Emit agent_activity.v1 events.

The event schema is the contract between SDK surfaces and the customer-owned portal ledger. Add fields carefully, preserve compatibility, and keep sensitive values scrubbed.

Canonical families

These event types are covered by the current builder proof or portal projections.

Event	Use
`session.started`	Open a governed agent session and attach team, repo, source, and developer context.
`tool.started`	Record that a capability or third-party tool call is about to run.
`tool.finished`	Record outcome, command preview, file preview, cost, and capability metadata after execution.
`model.completed`	Record model call metadata when the connector can see it without becoming a proxy.
`approval.requested`	Create reviewable evidence for a confirm-level decision.
`hook.blocked`	Show enforced PreToolUse policy decisions from hook packs.
`agent_run_audit.source_snapshot`	Provide TS/JS source evidence for Agent Run Audit projections.
`agent_run_audit.file_change`	Attach changed-file context to the governed session.
`session.finished`	Close the session with final status and outcome summary.

Session start

A connector should start by naming the source and attaching provenance that can be audited later.

json

{
  "schema_version": "agent_activity.v1",
  "event_type": "session.started",
  "session_id": "custom-session-1",
  "team_id": "00000000-0000-4000-8000-000000000000",
  "source": {
    "kind": "custom_connector",
    "name": "internal-agent-connector",
    "version": "0.1.0"
  },
  "provenance": {
    "source_classification": "customer_internal",
    "connector_id": "internal-agent-connector",
    "connector_version": "0.1.0",
    "policy_pack_id": "regulated-baseline",
    "policy_pack_version": "2026-05-16"
  }
}

Compatibility rules

The portal stores raw events and builds projections from known fields.

Additive fields are allowed in agent_activity.v1.
Removing fields, renaming fields, or making optional fields required needs a new schema version.
Older connector payload fixtures must continue to ingest.
Portal projections should ignore unknown fields unless those fields are security-sensitive.
Raw emails, secrets, tokens, and credentials must remain scrubbed or rejected.

Backward compatibility test

The repository includes a legacy connector fixture to prove older agent_activity.v1 payloads still ingest and project even when they do not include the newer provenance fields.