feat: `tool report-event` takes the Claude Code plugin's session start and feature-used events
Issue for this PR
No GitHub issue.
Type of change
- Bug fix
- New feature
- Refactor / code improvement
- Documentation
What does this PR do?
The Claude Code plugin needs install, active-use and per-feature counts, anonymous and with the usual opt-out. Today it sends one kind of event through altimate tool report-event (lineage_report), and nothing counts sessions, plugin versions or the use of its panels and gates. This PR lets tool report-event take two more actions from the plugin and forward them through the existing telemetry. No new network host.
Design
Events. Two new actions for altimate tool report-event, sent by the Claude Code plugin:
| Event | When | Fields (the whole payload) |
|---|---|---|
plugin_session_start | each Claude Code session start | plugin_version, altimate_code_version (stamped by the CLI), host_os (macos, linux, windows, wsl, unknown; apart from the os other events carry as process.platform), install_id |
plugin_feature_used | a person opened a panel or command, or a gate held or allowed a command | plugin_version, install_id, feature, outcome |
featureis one oflineage,dbt_show,profile_ctes,scan_cost,comments,sql_graph,health,runs,to_model,cost_gate,health_push_gate.outcomeis one ofopened,failed(the panel could not open, or Claude Code could not place it),held,allowed.install_idis a random UUID the plugin creates on first run and keeps in its own Claude Code plugin store. It is not derived from the machine, the user or the project.
Allow-list. The CLI builds each event from these fields only, each checked against a fixed pattern or enum: plugin_version is a SemVer 2.0 version of up to 64 characters (any number of digits per part) (or unknown), install_id a lowercase v4 UUID, and os, feature and outcome enums. The plugin actions take no --session, and each action refuses a flag it does not take. Anything else, including any other flag, is refused with exit 1 and nothing is tracked. No project names, SQL, paths, column names or session text can reach the event.
Transport and anonymity. The events go through the CLI's existing telemetry (Telemetry.track to Azure Application Insights, flushed on exit). No new network host. They are unlinkable: unlike every other CLI event, they carry no account (user_id, tenant), no machine id, no project id, no session id and no launch_id, which the same process's first_launch row would share. ai.user.id is the plugin's install id, so they cannot be joined to a signed-in row. Only cli_version, client and source come from the envelope. They are also sent in a request of their own: doFlush never puts them in one body beside rows that carry the machine id or the account, and retries only a batch that was not sent (a batch not tried because the one before it failed keeps its retry).
Opt-out. ALTIMATE_TELEMETRY_DISABLED (or OPENCODE_DISABLE_TELEMETRY) and telemetry.disabled in the altimate-code config turn it off in the CLI, as for every other event. The plugin also checks ALTIMATE_TELEMETRY_DISABLED / OPENCODE_DISABLE_TELEMETRY itself and then starts no CLI process and creates no install id.
Older CLI. An altimate-code without these actions exits 1 with a message on stderr. The plugin runs every event in the background (scheduled with later, never awaited by a hook), ignores the exit code and output, and shows nothing: no toast, no log line outside the debug log.
Code
src/altimate/tool-cli/report-event.ts:PLUGIN_ACTIONS,PLUGIN_FEATURES,PLUGIN_OUTCOMES,PLUGIN_OS, andreportEvent(action, session, now, fields, cliVersion). A lineage step still sends only its action and session, and now refuses a plugin flag passed with it.src/cli/cmd/tool.ts:--plugin-version,--install-id,--os,--feature,--outcomeonreport-event.--sessionis required only by the lineage steps. Help lists every action and value. The CLI's strict parsing refuses any unknown flag, andreportEventrefuses a known flag the action does not take (exit 1, nothing tracked).src/altimate/telemetry/index.ts: the two event types in theEventunion. They go throughTelemetry.track, soALTIMATE_TELEMETRY_DISABLED,OPENCODE_DISABLE_TELEMETRYandtelemetry.disableddrop them like every other event.ANONYMOUS_EVENTS(built fromPLUGIN_ACTIONS) builds their envelope without account, machine id, project or session, keyed to the install id.- Docs:
docs/docs/reference/telemetry.mdlists both events and their fields.docs/docs/usage/tool.mdgives the command lines.
The plugin side is AltimateAI/altimate-claude-plugin#40. An altimate-code without this PR refuses the new actions with exit 1. The plugin ignores that, so nothing is sent or shown.
How did you verify your code works?
bun test test/altimate/tool-cli/report-event.test.ts test/altimate/telemetry/identity.test.ts: 26 pass, 0 fail. On main'ssrc,report-event.test.tsfails because the plugin actions and lists do not exist.- Allow-list unit tests: each feature × outcome and each OS builds exactly the listed fields. These are refused:
- a version that is not full SemVer (
1.8.2-..,1.8.2-01,1.8.2+a..b, path-like or over 64 characters);1.8.2+build.7and1.8.2-rc.1+sha.5114f85pass; - an install id that is not a lowercase v4 UUID;
- an OS, feature or outcome outside its list;
--sessionon a plugin action, and any flag the action does not take, including plugin flags on a lineage step.
- a version that is not full SemVer (
- Unlinkable when signed in (
identity.test.ts): with an account resolved,plugin_session_startandplugin_feature_usedcarry nouser_id,tenant,machine_id,project_id,session_idorlaunch_id.ai.user.idis the install id, and none of the account row's identifiers (user, tenant, machine id, aclaude:session, its launch id) appears anywhere in them. An ordinary event tracked with them keeps its account, as before, and goes in a separate request body. This test fails on main's telemetry. - End to end through the real CLI, with telemetry pointed at a local sink (
Bun.serveas the App Insights ingestion endpoint):- Each event arrives once. Its
propertieskeys are exactlycli_version,clientandsourceplus its allow-listed fields. The run starts from a fresh install marker, so the same process also sendsfirst_launchwith the machine id; no value of that row (machine id, launch id, user id) appears in the plugin's rows, and no request body holds a plugin row beside another.altimate_code_versionequalscli_version,ai.user.idis the install id, andai.session.idis empty. - With
ALTIMATE_TELEMETRY_DISABLED=true, and with{"telemetry":{"disabled":true}}in the config, nothing reaches the sink. - A bad
--featureexits 1 and says why. An extra--sql …flag exits 1. Neither sends anything, and the SQL text is nowhere in what the sink got.
- Each event arrives once. Its
- Allow-list unit tests: each feature × outcome and each OS builds exactly the listed fields. These are refused:
bun test test/altimate/telemetry test/altimate/telemetry-safety.test.ts test/altimate/tool-cli test/cli/help test/branding test/install/install-telemetry.test.ts: 603 pass, 0 fail. The help snapshot is updated for the new description.bun test test/branding: 293 pass.bun typecheck: clean.
Cost side effects
None. No model calls, warehouse queries or cloud resources. Each plugin event is one small App Insights row through the existing telemetry. There is one row per session start and one per panel, command or gate use, so the volume grows with how often people use the plugin, not with their data.
Screenshots / recordings
Not a UI change.
Checklist
- I have tested my changes locally
- I have not included unrelated changes in this PR
- I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"
🤖 Generated with Claude Code