Repository navigation
fix(aidd-context): source-backed tool references, with dates and unverified cells #618
Description
Problem
plugins/aidd-context/skills/08-hook-generate/references/tool-paths.md stated that Codex CLI has no session-end moment. Codex documents SessionEnd explicitly. The claim was wrong, and it propagated: a downstream design decision was taken on it before anyone re-read the source.
The failure is structural, not a typo. Not one cell in that table carried a URL or a date. Nothing distinguished "read in the docs" from "assumed in 2026-06 and never re-checked", so the only way to audit one cell was to re-verify all of them. A reference that cannot be audited cell by cell decays silently, and agents quote it with full confidence.
These references are load-bearing: a skill reads them instead of the vendor docs, so an error there becomes an error in every artefact the skill generates.
Scope
Applies to reference files that make per-tool factual claims, starting with 08-hook-generate/references/tool-paths.md.
- Per-claim verification marks.
[v]= read in the official docs on the stated date.[?]= not re-read, unverified. An unverified cell stays unverified; it is never filled with a plausible value. - Sources section. Every page actually read, with its URL, plus the date of the pass. Redirects noted with their target (
developers.openai.com/codex/hooksanddocs.github.com/.../hooks-configurationboth moved). - Re-verification trigger. State when a
[v]becomes stale and must be re-read. - Extend to the other per-tool references in
aidd-contextonce the shape is agreed (11-explore/references/ai-mapping.md,03-context-generate/references/ai-mapping.md).
A first pass over tool-paths.md is written and ready to land with this issue: marks, sources, verification date, plus the corrections below.
Corrections found while verifying (5 tools, official docs, 2026-08-11)
- Codex has
SessionEnd. Previously recorded as absent. Timeout is 1 s by default, 3 s max, and it does not run for subagents. - Copilot casing is not an alias. The configured casing selects the payload format (camelCase fields vs snake_case) and sometimes the event name itself:
agentStopbecomesStop,userPromptSubmittedbecomesUserPromptSubmit. The file described it as accepting both names. - Failure semantics differ per tool, and one denies. A
preToolUsehandler that exits non-zero on Copilot denies the tool call. An observer hook that throws stops the agent. Not documented anywhere in the file before. - OpenCode confirmed as plugins-only, with no session-end event and no session identifier in the plugin context.
- Session identifier field names differ across all four supported tools (
session_id,conversation_id,sessionId) and none of the five documents whether the value survives a resume, clear, compaction or fork.
Acceptance criteria
- Every factual cell in
tool-paths.mdcarries[v]or[?]. - A
Sourcessection lists each page read, with the date of the pass. - The five corrections above are reflected in the file.
- A
[?]cell is never silently promoted to[v]without a re-read. - The shape is agreed before extending to the other reference files.
Prior art in this repo
plugins/aidd-context/skills/08-hook-generate/references/tool-paths.md— the file this issue fixes.plugins/aidd-context/skills/08-hook-generate/references/hook-authoring.md— R1-R7, which delegate every per-tool fact totool-paths.md.AGENTS.md— "Don't guess APIs, signatures, flags, or behavior" and "Don't assume your knowledge is current" already carry the intent. This issue does not add a rule; it makes the existing ones auditable in the file that holds the claims.
Relations
| Field | Value |
|---|---|
| related | #617 |
Verified against: Claude Code hooks and monitoring-usage, Codex hooks and config-advanced, Cursor hooks, Copilot hooks-reference, OpenCode plugins and config schema.
Activity
blafourcade commentedon Aug 14, 2026
Corrections mesurées, 2026-08-13/14
Campagne de sondes sur les cinq outils, sessions réelles et documentations officielles. Six corrections à porter dans
tool-paths.md, toutes vérifiables.SessionEndPermissionRequest,PostCompact,SubagentStartcursor-agentlit bien.cursor/hooks.json— mesuré, la doc ne décrit que des moments d'éditeursession_id,conversation_id,generation_id, égaux sur une session à un tourexperimental.openTelemetrydansopencode.jsonLe manque le plus important : les verrous
Aucune sonde n'a fonctionné du premier coup, et jamais pour une raison différente. Écrire le fichier de hook ne suffit pas.
--enable hooks+--dangerously-bypass-hook-trust.github/hooks/*.json$COPILOT_HOME/hooks/, non soumis à la confiance--trustou approbation interactiveUn hook posé sans lever le verrou est installé, silencieux, et ne lève aucune erreur. C'est le pire état pour une couche de mesure : la configuration paraît complète et la donnée n'existe pas. Ce tableau manque au fichier et conditionne #617.
Sur OpenCode, correction d'une correction
La ligne « OpenCode n'a aucune télémétrie » était fausse, et je l'ai écrite deux fois avant de la mesurer. La bascule est une clé de configuration, pas une variable d'environnement. Activée, ses spans
ai.streamTextportentgen_ai.usage.input_tokens,gen_ai.usage.output_tokensetsession.idsur le même span. Il honore aussiOTEL_RESOURCE_ATTRIBUTES. Réserve : 495 spans pour une session triviale, tout étant instrumenté jusqu'aux lectures de fichier.Détail complet et sources dans
aidd_docs/brainstorm/2026_08_13-telemetry-layer.md.blafourcade commentedon Aug 16, 2026
Out of the week's scope, 2026-08-16
Milestone 14 is scoped to what produces a trustworthy figure in five days: #620 the journal, #646 the switch, #647 the sink, #663 the step boundaries, #629 the figure, #617 the proof it is honest. Plus #658, which ships with them because the published documentation currently promises the opposite of what we are about to release.
This issue is not in that set. It keeps its value and its content; it simply is not what the week is measured on. It returns to the milestone board once the first figure exists.
No milestone is assigned rather than a later one, because where it lands depends on what the first week actually teaches.
blafourcade commentedon Sep 10, 2026
I suggest keeping this open as a bug, with a narrower first pass.
tool-paths.mdstill states that Codex has noSessionEnd, and it still has neither verification marks nor source links. Current Codex documentation confirmsSessionEndfor the main thread, not subagents. The 1-second default and 3-second maximum found in the earlier note apply toInterrupt, so they should not be copied toSessionEndwithout a direct source.First deliverable: correct
tool-paths.mdand add a compact evidence record for each factual claim: source URL, checked date, and verified or unverified status. Validate that shape there before extending it to the other mappings.I would keep this outside a milestone as decided, but set its Roadmap priority to High: this reference drives generated hook configurations.
fix(aidd-context): document Codex SessionEnd
fix(aidd-context): document Codex SessionEnd (#905)