feat: `tool report-event` takes the Claude Code plugin's session start and feature-used events

Merged
HK
12h ago
+544-38

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:

EventWhenFields (the whole payload)
plugin_session_starteach Claude Code session startplugin_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_useda person opened a panel or command, or a gate held or allowed a commandplugin_version, install_id, feature, outcome
  • feature is one of lineage, dbt_show, profile_ctes, scan_cost, comments, sql_graph, health, runs, to_model, cost_gate, health_push_gate.
  • outcome is one of opened, failed (the panel could not open, or Claude Code could not place it), held, allowed.
  • install_id is 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, and reportEvent(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, --outcome on report-event. --session is required only by the lineage steps. Help lists every action and value. The CLI's strict parsing refuses any unknown flag, and reportEvent refuses a known flag the action does not take (exit 1, nothing tracked).
  • src/altimate/telemetry/index.ts: the two event types in the Event union. They go through Telemetry.track, so ALTIMATE_TELEMETRY_DISABLED, OPENCODE_DISABLE_TELEMETRY and telemetry.disabled drop them like every other event. ANONYMOUS_EVENTS (built from PLUGIN_ACTIONS) builds their envelope without account, machine id, project or session, keyed to the install id.
  • Docs: docs/docs/reference/telemetry.md lists both events and their fields. docs/docs/usage/tool.md gives 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's src, report-event.test.ts fails 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.7 and 1.8.2-rc.1+sha.5114f85 pass;
      • an install id that is not a lowercase v4 UUID;
      • an OS, feature or outcome outside its list;
      • --session on a plugin action, and any flag the action does not take, including plugin flags on a lineage step.
    • Unlinkable when signed in (identity.test.ts): with an account resolved, plugin_session_start and plugin_feature_used carry no user_id, tenant, machine_id, project_id, session_id or launch_id. ai.user.id is the install id, and none of the account row's identifiers (user, tenant, machine id, a claude: 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.serve as the App Insights ingestion endpoint):
      • Each event arrives once. Its properties keys are exactly cli_version, client and source plus its allow-listed fields. The run starts from a fresh install marker, so the same process also sends first_launch with 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_version equals cli_version, ai.user.id is the install id, and ai.session.id is empty.
      • With ALTIMATE_TELEMETRY_DISABLED=true, and with {"telemetry":{"disabled":true}} in the config, nothing reaches the sink.
      • A bad --feature exits 1 and says why. An extra --sql … flag exits 1. Neither sends anything, and the SQL text is nowhere in what the sink got.
  • 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