Skip to content

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

TypeScript

telemetry: rows carry the engine's version, base version and build time from $.session.version() (#96487)

Alice T'Poteatcbab6f4598e9
diff --git a/mods/telemetry/README.md b/mods/telemetry/README.md
index 5bd450ab..c5b02b07 100644
--- a/mods/telemetry/README.md
+++ b/mods/telemetry/README.md
@@ -26,10 +26,12 @@ entrypoint and interactivity, and an `env` block (platform and
architecture from one `uname` probe, terminal, shell, package managers and
runtimes, CI and GitHub Actions, the remote container, the deployment, the
Linux distribution and kernel, WSL, the working directory's version
-control), with the repository's remote hash beside the row's properties.
-What the engine alone knows (its version and build time, its runtime's
-version, the process's memory, the request's betas, the subscription tier,
-the calling agent) is not on `$`, and those columns stay empty.
+control, and the engine's version, base version and build time from
+`$.session.version()`, left empty on an engine that does not answer it),
+with the repository's remote hash beside the row's properties. What the
+engine alone knows (its runtime's version, the process's memory, the
+request's betas, the subscription tier, the calling agent) is not on `$`,
+and those columns stay empty.
It sends nothing wherever the CLI's own analytics are off: under
`DISABLE_TELEMETRY`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
diff --git a/mods/telemetry/hooks/context/environment-fields-of/environment-fields-of.ts b/mods/telemetry/hooks/context/environment-fields-of/environment-fields-of.ts
index 3ab180dc..c389f3dd 100644
--- a/mods/telemetry/hooks/context/environment-fields-of/environment-fields-of.ts
+++ b/mods/telemetry/hooks/context/environment-fields-of/environment-fields-of.ts
@@ -12,6 +12,9 @@ import { tagsOf } from './tags-of'
* The rows' `env` block from what was probed, valued as the CLI's own is;
* the GitHub Actions fields only inside a workflow, the Linux ones on Linux.
*
+ * The engine's version, base version and build time are as it answered
+ * them, absent where it did not.
+ *
* @param probe what was gathered for the session
* @returns the block
*/
@@ -56,5 +59,8 @@ export function environmentFieldsOf(probe: Probe): EnvironmentFields {
linuxDistroVersion: probe.distro.version,
linuxKernel: isLinux ? machine.kernel : undefined,
vcs: probe.vcs,
+ version: probe.engine?.version,
+ versionBase: probe.engine?.base,
+ buildTime: probe.engine?.builtAt,
}
}
diff --git a/mods/telemetry/hooks/context/environment-fields/environment-fields.ts b/mods/telemetry/hooks/context/environment-fields/environment-fields.ts
index 41e22e1d..5acbb062 100644
--- a/mods/telemetry/hooks/context/environment-fields/environment-fields.ts
+++ b/mods/telemetry/hooks/context/environment-fields/environment-fields.ts
@@ -5,8 +5,8 @@ import type { GithubActionsFields } from './github-actions-fields'
* carry it, before its keys are spelled for the wire (Entries.wireOf).
*
* The machine, the terminal and shell, CI and GitHub Actions, the remote
- * container, the deployment. `isClaudeAiAuth` follows the credential each
- * batch is sent with and joins these then; an absent field is undefined.
+ * container, the deployment, the engine's version. `isClaudeAiAuth` follows
+ * the credential each batch is sent with and joins these then.
*/
export type EnvironmentFields = {
readonly platform: string
@@ -38,4 +38,7 @@ export type EnvironmentFields = {
readonly linuxDistroVersion: string | undefined
readonly linuxKernel: string | undefined
readonly vcs: string | undefined
+ readonly version: string | undefined
+ readonly versionBase: string | undefined
+ readonly buildTime: string | undefined
}
diff --git a/mods/telemetry/hooks/context/probe-of/probe-of.ts b/mods/telemetry/hooks/context/probe-of/probe-of.ts
index 8231cd28..c6aa4fff 100644
--- a/mods/telemetry/hooks/context/probe-of/probe-of.ts
+++ b/mods/telemetry/hooks/context/probe-of/probe-of.ts
@@ -1,3 +1,4 @@
+import Batching from '../../batching'
import type { TelemetryDeps } from '../../telemetry-deps'
import Identity from '../identity'
import Machine from '../machine'
@@ -8,10 +9,10 @@ import { linuxFilesOf } from './linux-files-of'
/**
* Gathers what holds for the whole session through the nouns beneath: the
- * variables, the global config, one machine probe, the directory, the remote.
+ * variables, the global config, one machine probe, the directory, the engine.
*
- * Each read that fails leaves its part empty; the Linux files are read on
- * Linux alone.
+ * Each read that fails leaves its part empty, the engine's version saying so
+ * once in the debug log; the Linux files are read on Linux alone.
*
* @param deps the calls on the nouns beneath
* @param isInteractive whether a person is at the prompt
@@ -21,14 +22,23 @@ export async function probeOf(
deps: TelemetryDeps,
isInteractive: boolean,
): Promise<Probe> {
- const [facts, signals, location, environment, cwd, repo] = await Promise.all([
- deps.facts(),
- deps.deployment(),
- deps.configLocation(),
- deps.environment(),
- deps.cwd().catch(() => undefined),
- deps.repo().catch(() => null),
- ])
+ const [facts, signals, location, environment, cwd, repo, engine] =
+ await Promise.all([
+ deps.facts(),
+ deps.deployment(),
+ deps.configLocation(),
+ deps.environment(),
+ deps.cwd().catch(() => undefined),
+ deps.repo().catch(() => null),
+ deps.version().catch((error: unknown) => {
+ deps.debug(
+ "telemetry: the engine's version is not readable here, so the " +
+ `version columns stay empty (${Batching.messageOf(error)})`,
+ )
+
+ return undefined
+ }),
+ ])
const [identity, machine, vcs, remoteHash] = await Promise.all([
Identity.identityOf(deps.read, location, environment.userType === 'ant'),
@@ -50,5 +60,6 @@ export async function probeOf(
wslVersion: files.wslVersion,
vcs,
remoteHash,
+ engine,
}
}
diff --git a/mods/telemetry/hooks/context/probe/probe.ts b/mods/telemetry/hooks/context/probe/probe.ts
index fcc8061d..51501e6f 100644
--- a/mods/telemetry/hooks/context/probe/probe.ts
+++ b/mods/telemetry/hooks/context/probe/probe.ts
@@ -1,3 +1,5 @@
+import type { SessionVersion } from 'claude-code'
+
import type Deployment from '../../deployment'
import type { Facts } from '../../facts'
import type { Identity } from '../identity'
@@ -6,7 +8,7 @@ import type { Machine } from '../machine'
/**
* Everything gathered for the session's context before it is shaped: the
- * variables, the identity, the machine, the Linux files and the directory.
+ * variables, the identity, the machine, the Linux files, the engine's version.
*/
export type Probe = {
readonly facts: Facts
@@ -19,4 +21,5 @@ export type Probe = {
readonly wslVersion: string | undefined
readonly vcs: string | undefined
readonly remoteHash: string | undefined
+ readonly engine: SessionVersion | undefined
}
diff --git a/mods/telemetry/hooks/register.ts b/mods/telemetry/hooks/register.ts
index 1e78659d..6647abb9 100644
--- a/mods/telemetry/hooks/register.ts
+++ b/mods/telemetry/hooks/register.ts
@@ -335,6 +335,7 @@ export function register(on: On) {
}),
cwd: () => beneath.session.cwd(),
repo: () => beneath.session.repo(),
+ version: async () => beneath.session.version(),
read: path => beneath.fs.read(path),
list: path => beneath.fs.list(path),
exists: path => beneath.fs.exists(path),
diff --git a/mods/telemetry/hooks/telemetry-deps/telemetry-deps.ts b/mods/telemetry/hooks/telemetry-deps/telemetry-deps.ts
index 7c1573e0..d75d65e5 100644
--- a/mods/telemetry/hooks/telemetry-deps/telemetry-deps.ts
+++ b/mods/telemetry/hooks/telemetry-deps/telemetry-deps.ts
@@ -5,6 +5,7 @@ import type {
ProcessRunResult,
SessionAuthorization,
SessionRepo,
+ SessionVersion,
Timer,
} from 'claude-code'
@@ -79,6 +80,12 @@ export type TelemetryDeps = {
*/
repo: () => Promise<SessionRepo | null>
+ /**
+ * The engine's version, its release and its build time; rejects on an
+ * engine that does not answer it.
+ */
+ version: () => Promise<SessionVersion>
+
/**
* Reads a file as text; rejects when it cannot be read.
*/
diff --git a/mods/telemetry/tests/fixtures/engine-version.ts b/mods/telemetry/tests/fixtures/engine-version.ts
new file mode 100644
index 00000000..33cf87ac
--- /dev/null
+++ b/mods/telemetry/tests/fixtures/engine-version.ts
@@ -0,0 +1,11 @@
+import type { SessionVersion } from 'claude-code'
+
+/**
+ * What the engine answers `$.session.version()` in the plain session: a
+ * development build, its release and its build time.
+ */
+export const ENGINE_VERSION: SessionVersion = {
+ version: '2.1.300-dev.20260920.t101500.sha1a2b3c4',
+ base: '2.1.300-dev',
+ builtAt: '2026-09-20T10:15:00Z',
+}
diff --git a/mods/telemetry/tests/fixtures/expected-row.ts b/mods/telemetry/tests/fixtures/expected-row.ts
index 9e4442e7..0a26372b 100644
--- a/mods/telemetry/tests/fixtures/expected-row.ts
+++ b/mods/telemetry/tests/fixtures/expected-row.ts
@@ -1,4 +1,5 @@
import { DEVICE_ID } from './device-id.js'
+import { ENGINE_VERSION } from './engine-version.js'
import { REMOTE_HASH } from './remote-hash.js'
/**
@@ -36,6 +37,9 @@ export const EXPECTED_ROW = {
is_conductor: false,
deployment_environment: 'unknown-darwin',
vcs: 'git',
+ version: ENGINE_VERSION.version,
+ version_base: ENGINE_VERSION.base,
+ build_time: ENGINE_VERSION.builtAt,
is_claude_ai_auth: true,
},
metadata: { rh: REMOTE_HASH, answer: 2, page: 'ready', seen: true },
diff --git a/mods/telemetry/tests/fixtures/first-party-session.ts b/mods/telemetry/tests/fixtures/first-party-session.ts
index cb828b25..0353a469 100644
--- a/mods/telemetry/tests/fixtures/first-party-session.ts
+++ b/mods/telemetry/tests/fixtures/first-party-session.ts
@@ -4,6 +4,7 @@ import { mock } from 'claude-code/testing'
import { ACCEPTED } from './accepted.js'
import { BEARER } from './bearer.js'
import { CONFIG_PATH } from './config-path.js'
+import { ENGINE_VERSION } from './engine-version.js'
import { GLOBAL_CONFIG } from './global-config.js'
import { LISTING } from './listing.js'
import { PROBED } from './probed.js'
@@ -16,7 +17,7 @@ import type { SessionOptions } from './session-options.js'
* session signed in first party on a Mac in a git checkout, on a mock clock.
*
* Keeps what the plugin did: each post, file read, program run and debug
- * line, as it does it.
+ * line, as it does it. The engine answers its version unless told not to.
*
* @param on the test's `on`
* @param options how this session differs from the plain one
@@ -53,6 +54,12 @@ export function firstPartySession(
on('session.repo', () => ({ value: REPO }))
on('fs.list', () => ({ value: LISTING }))
+ const engineVersion = options.engineVersion ?? ENGINE_VERSION
+
+ if (engineVersion !== 'unanswered') {
+ on('session.version', () => ({ value: engineVersion }))
+ }
+
on('session.authorize', () => {
authorizeCalls += 1
diff --git a/mods/telemetry/tests/fixtures/index.ts b/mods/telemetry/tests/fixtures/index.ts
index 7515e935..39fac021 100644
--- a/mods/telemetry/tests/fixtures/index.ts
+++ b/mods/telemetry/tests/fixtures/index.ts
@@ -4,6 +4,7 @@ export * from './config-path.js'
export * from './deaf-telemetry.js'
export * from './device-id.js'
export * from './ended.js'
+export * from './engine-version.js'
export * from './environments'
export * from './expected-row.js'
export * from './first-party-session.js'
diff --git a/mods/telemetry/tests/fixtures/session-options.ts b/mods/telemetry/tests/fixtures/session-options.ts
index 95bff654..ad90afe6 100644
--- a/mods/telemetry/tests/fixtures/session-options.ts
+++ b/mods/telemetry/tests/fixtures/session-options.ts
@@ -1,4 +1,8 @@
-import type { HttpResponse, SessionAuthorization } from 'claude-code'
+import type {
+ HttpResponse,
+ SessionAuthorization,
+ SessionVersion,
+} from 'claude-code'
import type { PolicyOption } from './policy-option.js'
@@ -16,4 +20,10 @@ export type SessionOptions = {
readonly files?: Readonly<Record<string, string>>
readonly existing?: readonly string[]
readonly probeOutput?: string
+
+ /**
+ * What `$.session.version()` answers; `unanswered` leaves nothing beneath
+ * it, as under an engine without the read.
+ */
+ readonly engineVersion?: SessionVersion | 'unanswered'
}
diff --git a/mods/telemetry/tests/register.test.ts b/mods/telemetry/tests/register.test.ts
index 1fca2e42..f12c8046 100644
--- a/mods/telemetry/tests/register.test.ts
+++ b/mods/telemetry/tests/register.test.ts
@@ -60,6 +60,45 @@ describe('register', () => {
},
)
+ test(
+ 'an engine without the version read leaves those three columns empty',
+ { plugins: [Fixtures.recording] },
+ async ($, on) => {
+ mock.env(on, Fixtures.SENDING_ENV)
+
+ const session = Fixtures.firstPartySession(on, {
+ engineVersion: 'unanswered',
+ })
+
+ await $.session.start(Fixtures.STARTED)
+ await $.command.run(Fixtures.record(Fixtures.surveyAnswer()))
+ await session.clock.advance(Hooks.BATCH_WINDOW_MS)
+
+ const { version, version_base, build_time, ...rest } =
+ Fixtures.EXPECTED_ROW.env
+
+ expect([version, version_base, build_time]).toEqual([
+ Fixtures.ENGINE_VERSION.version,
+ Fixtures.ENGINE_VERSION.base,
+ Fixtures.ENGINE_VERSION.builtAt,
+ ])
+
+ expect(Fixtures.rowsOf(session)).toEqual([
+ { ...Fixtures.EXPECTED_ROW, env: rest },
+ ])
+
+ expect(session.lines).toEqual([
+ expect.stringContaining(
+ "telemetry: the engine's version is not readable here, so the " +
+ 'version columns stay empty (',
+ ),
+ 'telemetry: sent 1 row(s)',
+ ])
+
+ expect(session.lines[0]).toContain('session.version')
+ },
+ )
+
test(
'a full queue goes out at once, before the window',
{ plugins: [Fixtures.recording] },
diff --git a/mods/types/claude-code.d.ts b/mods/types/claude-code.d.ts
index 974450a2..3af34387 100644
--- a/mods/types/claude-code.d.ts
+++ b/mods/types/claude-code.d.ts
@@ -2427,6 +2427,24 @@ declare module 'claude-code' {
* for (const row of usage.context.breakdown?.gridRows ?? []) draw(row)
*/
usage: (args?: SessionUsageArgs) => Promise<SessionUsage>;
+ /**
+ * Returns the version of the engine the session runs on, the release it
+ * is built from, and when it was built.
+ *
+ * The same three values the engine's own analytics rows carry, answered
+ * in every mode and build; `base` is absent when the version is not
+ * spelled as a release, `builtAt` in a run from source that stamps none.
+ *
+ * @returns `{ version, base, builtAt }`: the full version, its release
+ * (`2.1.280`, or `2.1.280-dev` for a development build) and an
+ * ISO 8601 build time
+ * @example
+ * const { version, base, builtAt } = await $.session.version()
+ * row.env = { version, version_base: base, build_time: builtAt }
+ * @example
+ * const isDevelopmentBuild = (await $.session.version()).base?.endsWith("-dev")
+ */
+ version: () => Promise<SessionVersion>;
/**
* Compacts the conversation: the event `session.compact` with `trigger`
* `plugin`, the same call `/compact` makes, between turns.
@@ -5541,6 +5559,10 @@ declare module 'claude-code' {
* The argument of `$.session.usage({ breakdown, columns })`.
*/
'session.usage': SessionUsageArgs;
+ /**
+ * The argument of `$.session.version()`.
+ */
+ 'session.version': NoArgs;
/**
* The argument of `$.turn.abort({ turnId })`.
*/
@@ -5780,6 +5802,10 @@ declare module 'claude-code' {
*/
'session.authorize': SessionAuthorization;
'session.usage': SessionUsage;
+ /**
+ * The engine's version, its release, and its build time when stamped.
+ */
+ 'session.version': SessionVersion;
'turn.abort': void;
/**
* The box as it stands; the empty box where the session draws none.
@@ -9082,6 +9108,34 @@ declare module 'claude-code' {
columns?: number;
};
+ /**
+ * What `$.session.version()` answers: the version of the engine the session
+ * runs on, the release that version is built from, and when it was built.
+ *
+ * The three are what the engine's own analytics rows carry as `version`,
+ * `version_base` and `build_time`, so a row a plugin sends and a row the
+ * engine sends from the same binary agree.
+ */
+ export type SessionVersion = {
+ /**
+ * The engine's full version, as `claude --version` prints it: a release's
+ * (`2.1.280`) or a development build's, which adds the build's date, time
+ * and commit (`2.1.280-dev.20260920.t101500.sha1a2b3c4`).
+ */
+ version: string;
+ /**
+ * The release the version is built from, its semantic core and channel:
+ * `2.1.280` for that release, `2.1.280-dev` for a development build of it.
+ * Absent when the version is not spelled as a release.
+ */
+ base?: string;
+ /**
+ * When the binary was built, an ISO 8601 timestamp
+ * (`2026-09-20T10:15:00Z`). Absent in a run from source that stamps none.
+ */
+ builtAt?: string;
+ };
+
/**
* What `$.settings.read` answers: an object keyed as a settings.json is
* (`permissions`, `env`, `hooks`, `model`, `enabledPlugins`, ...).