docs(trace): add a guide to implement a new trace provider

Merged
JI
2d ago
+322-1

Adds app/cli/internal/trace/PROVIDERS.md, a guide to add a new Chainloop Trace provider (harness), and links it from the Trace README.

Refs #3657: the guide describes what a Codex provider must implement.

The guide covers:

  • The session lifecycle, and which provider method and shared handler run at each step (trace init, agent hooks, commit, push, uninstall, trace run).
  • The trace.Provider methods by group: hook installation, hook input, code attribution (snapshot or reverse edits), session copy and parsing, and the user and model channels. It uses Claude Code, Cursor, and OpenCode as examples.
  • The evidence mapping: session metadata, models, token usage, and cost.
  • The optional interfaces: SkillTracker, SpecCopyReplacer, and PastedImageFinder.
  • The CLI wiring: registry, init wizard, --<agent> flags, and trace hook <agent> subcommands.
  • The required end-to-end harness and compatibility matrix updates.
  • A checklist for new providers.

AI disclosure: written with the assistance of Claude Code.