feat(framework): a skill that proves the telemetry pipeline fires

[alexsoyes]

As a developer who has just installed AIDD telemetry
I want a skill that tells me, line by line, whether each link actually produces data
So that I never build a decision on figures an inert installation left incomplete

Acceptance

• The skill prints one line per independently verifiable claim, and no line that is a summary of the others.
• A hook whose configuration exists but that has never fired reads FAIL, not ok.
• A hook whose last observed write is older than the current session's start reads FAIL.
• A complete installation whose identifier is missing from the export reads FAIL — the OTEL_METRICS_INCLUDE_SESSION_ID=false case.
• A session that emitted a run file but no telemetry datapoints is named as such, and not counted as healthy.
• The four uncovered tools are named explicitly, never passed over in silence.
• On a public repository the skill reports telemetry as disabled until the repository has opted in.
• The skill consumes no model quota beyond its own invocation, and makes no network call other than to the local sink.

Expected output

enabled for this repository        ok
plugin installed                   ok    aidd-telemetry
hook observed                      ok    last write 4 min ago
export configured                  ok    OTLP to 127.0.0.1:4318
identifier joinable                ok    session.id present in the export
sessions journaled                 ok    12 over 7 days
step names readable                FAIL  OTEL_LOG_TOOL_DETAILS unset, steps collapse to third-party
not covered                        --    codex, copilot, cursor, opencode

Why a skill and not a CLI command

The diagnostic answers a question asked from inside a session, about the session that is running. A skill can read the run journal and see whether the current session has a file — which is precisely the "did the hook fire" check, and it is stronger from inside than from outside.

The CLI keeps one job only: turning the export on. Everything that reads belongs to the plugin.

Why this is the most important issue in the milestone

The measurement campaign (#632) found that no probe worked on the first attempt, and never for a different reason. Every tool gates its hooks differently. A hook installed without lifting the gate is silent and raises nothing.

That is not an edge case, it is the nominal case. Hence the central requirement: the skill does not check that a file exists, it checks that a hook fired.

Out of scope

• Per-tool inert-state detection for Codex, Copilot and Cursor. Those tools are out of scope for this milestone; naming them as uncovered is the correct answer, and parsing their trust state is days of work with no bearing on the promise.
• Any figure. Reading cost belongs to the consultation skill.

Relations

Field	Value
parent	#631
depends_on	#620, #646, #647
related	#629, #632

[alexsoyes]

Verified against the five vendors' official docs (2026-08-11)

One agent per tool, one page per claim. Full write-up with citations lives in the dashboard repo at aidd_docs/memory/kpi/probes/03-hooks-et-identifiants-session.md; the hook-authoring reference is corrected under #618.

The finding that changes this issue

None of the five tools documents that the session id seen by a hook is the one in its telemetry export. Not Claude Code, not Codex, not Cursor, not Copilot, and OpenCode has neither. The join this issue assumed is nowhere guaranteed.

One cross-surface join is guaranteed, by Claude Code only: its hook prompt_id "matches the prompt.id attribute on OpenTelemetry events, so you can correlate hook output with telemetry for a single prompt" (requires 2.1.196+; 2.1.218 observed locally). It is per turn, not per session — which fits an interval model better than the session ever did.

Consequence for the scope above: the marker must carry an AIDD-owned run id, with the vendor identifier stored beside it as a typed attribute (session_id on Claude Code and Codex, conversation_id on Cursor, sessionId on Copilot — four names). Task-to-execution attribution then owes nothing to a vendor. Cost joining stays borrowed and stays explicit, per tool.

Capability per tool

Tool	Session structure	Cost join	Note
Claude Code	native	derived	session.id in OTLP, but disableable via OTEL_METRICS_INCLUDE_SESSION_ID
Codex	native	unknown	telemetry key never published; docs say "conversation id" in prose only
Cursor	native	unknown	Admin API conversationId carries tokens and cost, but is never tied to hooks
Copilot	native	unknown	OTLP gen_ai.conversation.id with cost, off by default; Metrics API is day/user only
OpenCode	unknown	unavailable	plugins only, no session-end event, no session id in plugin context

New acceptance criteria this requires

• A telemetry handler exits 0 unconditionally, on every tool. On Copilot a preToolUse handler that exits non-zero denies the tool call — an observer that throws stops the agent from committing. This is a safety criterion, not hygiene.
• The marker records run_id, the vendor identifier, and the identifier kind.
• status detects an installation that is present but inert: Codex hook trust review pending or [features] hooks = false, Copilot disableAllHooks, Claude Code OTEL_METRICS_INCLUDE_SESSION_ID=false.
• Per-tool support is declared as native / derived / unavailable / unknown, and unknown blocks that tool rather than shipping a partial claim.
• For the pilot, correlate on prompt_id / prompt.id rather than on session equality.

Smaller facts worth keeping

• Copilot reads the repository's .claude/settings.json for inline hooks: one Claude-format entry covers two tools.
• Codex SessionEnd exists (the earlier claim that it does not was wrong) but its timeout is 1 s, 3 s max, and it does not fire for subagents.
• Codex documents subagent propagation explicitly ("Subagent hooks use the parent session id"). Cursor does the opposite: subagents get their own id plus a separate parent_conversation_id. Claude Code documents neither.
• Copilot's built-in general-purpose agent emits neither subagentStart nor subagentStop.
• Cursor exposes beforeShellExecution with the command at the top level, cleaner than filtering a generic tool event.
• On OpenCode, tool.execute.before can mutate output.args.command: the only one of the five where a trailer could be injected without a git hook.

Still unverified, and load-bearing

No vendor documents what happens to the session identifier across a resume, clear, compaction or fork. All five expose a source / reason discriminant at those boundaries and none says whether the value is kept. Measure before relying on it.

[blafourcade]

Resserrage pour une v1 testable, 2026-08-14

Échéance du jalon dans une semaine. Cette issue porte deux moitiés indépendantes ; seule la seconde entre dans la v1.

L'hypothèse porteuse est levée

Le troisième critère d'acceptation — « the stamped id matches the session.id seen in the provider's OpenTelemetry export » — est mesuré, sur quatre outils.

Outil	Champ côté hook	Attribut côté export	Même valeur	Coût du test
Claude Code	session_id	session.id	oui, deux sessions	deux sessions réelles
Codex CLI	session_id	conversation.id sur codex.sse_event	oui	zéro token
GitHub Copilot	sessionId	gen_ai.conversation.id sur invoke_agent	oui	zéro crédit
OpenCode	—	session.id sur ai.streamText	export prouvé	une session

Les identifiants sont fabriqués côté client, avant l'appel au modèle : un fournisseur pointé sur une adresse morte démarre quand même la session, fait tirer le hook et émet la télémétrie. Codex et Copilot se vérifient donc gratuitement, ce qui met cette vérification dans l'intégration continue plutôt que dans une case à cocher de fin de parcours.

Le risque a changé de place

Aucune sonde n'a fonctionné du premier coup, et jamais pour une raison différente : chaque outil verrouille ses hooks à sa façon (détail dans #618). Un hook installé sans lever son verrou est muet et ne lève aucune erreur.

C'est exactement ce que cette issue voulait attraper avec « an installed-but-inert state must read as failed ». La campagne montre que ce n'est pas un cas limite mais le cas nominal. Donc status ne doit pas vérifier qu'un fichier existe, mais qu'un hook a tiré.

Ce qui reste dans cette issue pour la v1

La commande d'état, et elle seule. Une ligne par affirmation vérifiable, jamais un verdict agrégé, avec la détection des états inertes par outil.

Ce qui en sort

Le trailer de commit — marqueur PreToolUse, prepare-commit-msg, détection du gestionnaire de hooks. Raison : le journal des exécutions (#620) couvre déjà les sessions sans commit, qui sont les plus chères et les plus mal comptées. Le trailer ajoute de la précision par commit, pas la capacité à mesurer. Suivi dans une issue dédiée.

Contradiction interne à corriger au passage

La section « Scope » fait écrire au marqueur « the session_id from the event payload », alors que la décision du 2026-08-12 pose que le trailer porte le run_id AIDD. Deux valeurs pour un même trailer.

Sur #585

Déclaré bloquant, mais .aidd/config.yml n'existe dans aucun code et la CLI n'a aucun analyseur YAML. La v1 lit .aidd/telemetry.json, format déjà manipulé par la CLI. Quand #585 arrive, c'est une ligne de lecture à déplacer.

Plan : aidd_docs/plans/2026_08_14-telemetry-v1/.