[knihit]

Description

Adds usage telemetry to the Claude Code marketplace plugin. It reports the same two events the CLI already sends for Claude Code, in the same format.

Plugin hook

• Added scripts/claude-plugin-telemetry-hook.js, shipped as hooks/konductor-telemetry.js. Plugin installs have no konductor binary, so this is a plain Node port of konductor __telemetry-hook. It has no npm dependencies and runs on macOS, Linux and Windows.
• SessionStart (startup|clear) sends agent_invocation, and SubagentStart sends subagent_invocation, as in the CLI's TELEMETRY_HOOK_ENTRIES. A SessionStart with no agent_type sends nothing.
• Only Konductor's own agents are reported, and only in the plugin form konductor:<agent>. targetName is the bare name. A bare agent_type comes from a CLI install, whose own hook reports it, so an agent is never counted twice. parentAgentName comes from CLAUDE_CODE_AGENT under the same rule, so a user's own agent is never named.
• The body matches the CLI's:
  • outer Solution/Version/UUID/TimeStamp
  • every schema-required Data field
  • sessionId = sha256(UUID + raw session id)
  • harness is claude-plugin, so plugin events can be told apart from CLI agent events, which send null
  • errorCode and agentVersion are null
  • the outer Version is the plugin version
• docs/telemetry-schema.json's harness description is updated to say so, and its agentVersion description now says plugin events carry the plugin version in the outer Version.
• Machine ID: the hook shares ~/.konductor/telemetry.json with the CLI. It creates the file the way identity.rs does: mode 0600, a temp file plus link, and on a race the loser reads the winner's file. A short write fails before anything is published. It never overwrites a record, and it refuses a symlinked ~/.konductor.
• Opt-outs (any one stops sending):
  • KONDUCTOR_TELEMETRY=off
  • telemetry.enabled: false in .konductor/config.yml in cwd, any parent directory or $HOME, as the CLI searches. A missing enabled leaves telemetry on, as in the CLI; an enabled set to anything but plain true turns it off. Comments are ignored. If the file mentions both telemetry and enabled but the hook finds no plain top-level telemetry key (an indented root, a ? telemetry key), it treats telemetry as off.
  • telemetry_consent: false in the machine record
  • the plugin's new telemetry_enabled option
• The agent filter runs before any config.yml is read, so a non-Konductor session reads no config files. All opt-outs are checked before the machine record is created or any request is made.
• File reads: config.yml, telemetry.json and plugin.json are opened non-blocking, must be regular files, and are read up to 64 KiB. A FIFO can't hang the hook. A non-regular or oversized file counts as unreadable: a config.yml is skipped, a telemetry.json fails closed, and a plugin.json sends nothing.
• Endpoint: always the CLI's default URL. The plugin ignores KONDUCTOR_METRICS_ENDPOINT and telemetry.endpoint, so there's no endpoint to validate. POST JSON, 3 s send timeout, no retries.
• The hook never writes to stdout or stderr and always exits 0. A backstop timer ends it if stdin never closes.

Manifest and assembly

• scripts/claude-plugin.template.json: added the telemetry_enabled boolean option, default true. Claude Code passes it to hooks as CLAUDE_PLUGIN_OPTION_TELEMETRY_ENABLED.
• Added scripts/render-claude-plugin-hooks-json.py. It writes hooks/hooks.json with the SubagentStart matcher ^konductor:(<agents>)$, built from the assembled agents/*.md so a new agent can't be missed. It fails if an agent's name differs from its file name.
• scripts/assemble-claude-plugin-branch.sh copies the hook and docs/telemetry-schema.json into the plugin tree and renders hooks/hooks.json.

Docs

• docs/user-guide/tasks/install-claude-plugin-marketplace.md: new Telemetry section. It says telemetry is on by default, lists what is sent and that the machine ID is shared with the CLI, and gives each opt-out and where config.yml is read. It also notes that the plugin ignores telemetry.endpoint.
• README.md: one paragraph in Data Collection. The published plugin's README is a copy of it.
• generated/claude-plugin/README.md: lists the new files.
• CHANGELOG.md: [Unreleased] / Added entry.

Closes #58

Type of Change

• Infrastructure / pipeline
• Documentation

Testing

• node --test tests/scripts/claude-plugin-telemetry-hook.test.js: 41/41. These cover:
  • Drift: schema field types and patterns read from docs/telemetry-schema.json. The endpoint, solution ID, nil sentinel, instance schema version and payload limit are read from the Rust sources.
  • Opt-outs: each one, including config.yml in a parent directory and $HOME, and eight YAML forms (quoted keys, JSON, BOM, !!bool, anchors and others).
  • Config parsing: a missing enabled and comments don't turn telemetry off. Forms with no plain top-level telemetry key, and content on a leading --- line, read as off.
  • File reads: a FIFO config.yml, telemetry.json or plugin.json exits 0 promptly. A config.yml over 64 KiB is skipped and one at the cap is read. An oversized telemetry.json fails closed. A non-Konductor session opens no config.yml.
  • Hang guards: a request that never responds is dropped after the 3 s send timeout, and a stdin that never closes exits 0 through the backstop. Each test fails with its guard removed.
  • Endpoint: with KONDUCTOR_METRICS_ENDPOINT and telemetry.endpoint both set, the request still goes to the default URL.
  • Machine ID: create, never overwrite, invalid record, symlinked dir, dir mode 0700, short write.
  • Output: silent exit 0 on bad input. Tests use a stub, so nothing reaches the network.
• Full npm test: 17 failures in other test files, all from scripts/brand-config/lib/constants.js, which isn't in the repo. Those files fail on main too, and none of the failures are in this PR's tests.
• python3 -m pytest tests/ -q: 153 passed. make claude-plugin-check passes, and it runs the hook tests first.
• Claude Code session with the plugin installed (local directory marketplace, https.request stubbed, other network calls blocked):
  • konductor:konductor delegating sends one agent_invocation and one subagent_invocation. Both validate against the schema and carry harness: "claude-plugin".
  • Built-in agents and a bare k-developer send nothing.
  • Each opt-out sends nothing.
  • The hook's output is empty.
• CLI install plus the plugin in one config, with https.request and curl stubbed:
  • A bare konductor session sends one event from the CLI (harness: null) and none from the plugin.
  • A konductor:konductor session sends from the plugin only.
  • Both use the same machine UUID.
  • telemetry.enabled: false in $HOME/.konductor/config.yml stops both.
• cd cli && make test: no cli/ changes
• New files carry the SPDX header

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own changes
• I have commented my code where necessary
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added or updated tests that prove my change works

Notes for Reviewers

• Merge order: after ci: run the test suites on PRs, and fix the two tests that block them #62 and fix(plugin): clean candidate tree, skill script paths and k-architect delegation #57. Delegation in a plugin install needs fix(plugin): clean candidate tree, skill script paths and k-architect delegation #57's grant fix.
• Conflicts:
  • scripts/assemble-claude-plugin-branch.sh conflicts with fix(plugin): clean candidate tree, skill script paths and k-architect delegation #57. Keep both steps, with the grant rewrite first.
  • The CHANGELOG [Unreleased] blocks need a manual merge.
• Invalid machine record: when ~/.konductor/telemetry.json is invalid or from a newer schema, the CLI resolves consent to false, so nothing is sent. The hook does the same.
• Unreadable config.yml: the CLI treats it as absent, and so does the hook. The hook also counts a non-regular file or one over 64 KiB as unreadable, which the CLI doesn't.
• Endpoint: the hook ignores KONDUCTOR_METRICS_ENDPOINT and telemetry.endpoint, and the install guide says so. To see what it sends, preload a stub for https.request with NODE_OPTIONS=--require, as the tests do.
• Windows: when HOME is unset, the hook falls back to os.homedir(). On macOS and Linux it sends nothing without HOME, same as the CLI.
• Not tested: a plugin installed from the GitHub marketplace, or Windows.