docs(claude-ops): state the sink's real route in its header - #3796
Conversation
0.42.11 moved the reference sink's routing to the envelope spine (`.session_id // .data.session_id`) and left the header saying the route is "decided by the envelope's `data.session_id`". That header is the file's only description of the rule, so a reader of the sink got the pre-1.1 answer while docs/conventions/hook-telemetry/README.md gave the right one. Both copies carry it: the plugin's and the repo-local .claude/hooks/ one. They differ only in how they reach their shared sources, by design, so the header had drifted identically in both. Comment only. hook-telemetry-sink.test.sh 41/41, shellcheck clean. Found by a fresh-context verifier auditing what actually shipped on main after the four PRs of this topic landed together. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019DaWEB8Daq1xAXy2Xj1Pme
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @kyle-sexton's task in 1m 27s —— View job
|
|
Claude finished @kyle-sexton's task in 34s —— View job Security review
Skip gate hit: no security-relevant surface. This PR changes only:
No executable logic, control flow, input handling, or trust boundaries change in either shell script — verified against |
|
Last security-reviewed head: |
|
Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a87ea83c0d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The header this branch just corrected replaced one inaccuracy with a smaller one: it said `session_id` is "carried by every 1.1 producer". Contract 1.1 makes the four correlation keys OPTIONAL — "copied verbatim from the hook payload by hook::emit_telemetry when present and well-formed, omitted otherwise" — so a 1.1 producer whose payload carries no session id, or a malformed one, puts nothing on the spine and this sink takes the legacy route. The header now says the producer carries it when its payload held a well-formed one and omits it otherwise, which is what the emitter does and what the contract promises. Both copies. Reported by Codex on this PR. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019DaWEB8Daq1xAXy2Xj1Pme
…-review-ji6rl5 # Conflicts: # plugins/claude-ops/CHANGELOG.md
2 participants
No related issue: a documentation inaccuracy found by a post-merge verification of this topic's four PRs, small enough to fix directly rather than file.
Summary
#3769 (claude-ops 0.42.11) moved the reference sink's routing to the envelope spine,
.session_id // .data.session_id, and left the file header saying the route is "decided by the envelope'sdata.session_id". That header is the sink's only description of its own routing rule, so a reader of the file got the pre-1.1 answer.docs/conventions/hook-telemetry/README.mdstates it correctly, which is what makes this an oversight rather than a disagreement about intent.Fix
The header now names the spine key first and the
data.session_idfallback second, matching line 62, and states the spine key as optional: contract 1.1 has a producer carrysession_idwhen its payload held a well-formed one and omit it otherwise, in which case this sink takes the legacy route. Applied to both copies,plugins/claude-ops/hooks/hook-telemetry-sink.shand the repo-local.claude/hooks/hook-telemetry-sink.sh.Those two files are not byte-identical and are not meant to be — the repo-local copy reaches
hook-utils.shandsession-log-lib.shby relative path because they are not colocated with it, and says so in its own comment. The stale header had drifted identically in both, so both needed the same correction.Comment only. No behavior change. claude-ops 0.42.16 to 0.42.17.
Review findings, both addressed
session_idis "carried by every 1.1 producer", which overstates a contract that makes the four correlation keys optional and hashook::emit_telemetryomit absent or malformed ones. Both citations checked before changing anything; reworded ina1713a1f, thread resolved.mainshipped claude-ops 0.42.16 in perf(hooks): cut leftover Bash parse and dirname tax on the hot path #3788 while this PR was open. Renumbered to 0.42.17 in the merge commit, with perf(hooks): cut leftover Bash parse and dirname tax on the hot path #3788's released 0.42.16 entry kept intact beneath this change's.Verification
shfmt -mn(a real shell parser) gives matching SHA-256 per file pair across base and head; every one of the 8 changed lines begins with#. File modes unchanged.plugins/claude-ops/hooks/hook-telemetry-sink.test.sh: PASS=41 FAIL=0.scripts/check-changelog-parity.sh --check-bump origin/main,--check,--check-preserved origin/main,scripts/validate-plugins.sh,scripts/sync-hook-utils.sh --check,scripts/check-hook-wiring-liveness.sh: all pass. shellcheck clean on both files.scripts/affected-tests.sh --run: only pre-existing failures,cache-content-check.test.sh's two "process budget" cases, which reproduce on unmodifiedmain.Related
session_idon every producer, then promote the correlation keys into the envelope spine (1.1) #3758, the contract it serves; perf(hooks): cut leftover Bash parse and dirname tax on the hot path #3788, which took 0.42.16.🤖 Generated with Claude Code
https://claude.ai/code/session_019DaWEB8Daq1xAXy2Xj1Pme