docs(hook-observability): record the three output-cap deltas from the hooks-reference audit

[kyle-sexton]

Closes #3754

Summary

The 2026-09-04 doc-alignment audit confirmed docs/conventions/hook-observability/README.md accurate on its channel claims but found three cap facts the hooks reference states and the convention did not carry. This PR records them, docs only.

Fix

A new ### Output caps stated by the reference subsection under the three surfaces, re-read 2026-09-05 by the rung-1 route (raw hooks.md, 317,632 bytes, first heading and llms.txt slug checked, SHA-256 recorded), carrying one four-part upstream-drift record per delta with the quoted basis:

1. Output over 10,000 characters overflows to a file with a preview and path; it is not truncated. The typos-format self-cap is named as the adopting reference.
2. The additionalContext cap is per value, with no pool shared across hooks.
3. The 2,000-character shared cap belongs to classifierContext (PostToolUse only, ignored for background hooks, discarded on read-only lookups), not to either channel this doc owns. The peer misreading that filed the typos-format 8,000-character self-cap as a bug is recorded so the next reader finds the answer here.

Three consequential edits:

• classifierContext fired the "Not a UI feature" bullet's recheck trigger as worded ("adds a hook-output field beyond the three"). Per upstream-drift's firing procedure the firing is recorded in place, the rule re-derived unchanged (the field reaches the classifier, not the user or the model), and the clause narrowed to fields addressed to the user or the model.
• The prompt_id paragraph pointed at feat(conventions): add prompt_id correlation to the hook-telemetry envelope #930, which is closed; it now points at feat(claude-ops): per-session hook logging pipeline, default off #3750 (the per-session event log that records prompt_id) and hook-telemetry: session_id on every producer, then promote the correlation keys into the envelope spine (1.1) #3758 (the envelope-spine promotion).
• The same stale feat(conventions): add prompt_id correlation to the hook-telemetry envelope #930 pointer in docs/conventions/hook-telemetry/README.md's routing note now names hook-telemetry: session_id on every producer, then promote the correlation keys into the envelope spine (1.1) #3758 (Codex finding).

Verification

• npx --no-install markdownlint-cli2 --config .markdownlint-cli2.jsonc on both files: 0 issues.
• typos on both files: clean.
• Acceptance from docs(hook-observability): record the three output-cap deltas from the 2026-09-04 hooks-reference audit #3754: grep -c '10,000' prints 5, grep -c 'classifierContext' prints 2, each occurrence under a dated stamp.
• scripts/affected-tests.sh --explain: both files are a recorded no-suite class (hygiene lane covers them); no shell suite selected.
• No em dash added; the two in the diff's added lines are re-wrapped pre-existing text.

Related

• Refs feat(claude-ops): per-session hook logging pipeline, default off #3750 (the audit's FINDINGS, in the branch history before the prune commit) and hook-telemetry: session_id on every producer, then promote the correlation keys into the envelope spine (1.1) #3758.

🤖 Generated with Claude Code

https://claude.ai/code/session_019DaWEB8Daq1xAXy2Xj1Pme

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T17:25:39.935448Z	e694917	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 3m 1s —— View job

---

CI code review

• Gather context (PR diff, CLAUDE.md, skill instructions)
• Apply skip gate (open, not draft, meaningful review surface — proceeded)
• Review changed file against criteria
• Post findings

Scope: docs/conventions/hook-observability/README.md only (+63/-6), per /review:code-review's code-review lane (correctness + maintainability; no security lane exists in this repo to defer to, but the change carries no security surface anyway).

Findings: none blocking.

Cross-checks performed against the diff's own claims, beyond what the PR body already reports:

• plugins/typos-format/hooks/typos-format.sh:705-706 confirms the cited cap figures exactly: truncate_to "$SYSMSG" 4000 / truncate_to "$CTX" 8000 — the doc's "4,000 for systemMessage, 8,000 for additionalContext" is accurate, not just asserted.
• grep -c '10,000' → 5 and grep -c 'classifierContext' → 2 against the working tree, matching the acceptance criteria from docs(hook-observability): record the three output-cap deltas from the 2026-09-04 hooks-reference audit #3754.
• The two em dashes in added lines (data_json construction —, beyond the three in [the three surfaces] —) are confirmed pre-existing by diffing against the corresponding removed lines — genuinely re-wrapped, not newly introduced, so no vendor-docs-are-not-style concern.
• All new anchors resolve: #output-caps-stated-by-the-reference (new heading, correct GFM slug) and #the-rungs (existing heading in docs/conventions/upstream-drift/README.md).
• The three new cap records each carry the doc's own required four parts (claim, quoted basis, as-of date, recheck trigger) and cite basis line numbers in increasing order (913, 993, 1999/2019–2021), consistent with a single sequential fetch.
• The "Trigger firing" callout is internally consistent: it explains the old wording of the recheck clause fired on classifierContext, the rule was re-derived unchanged (field reaches the classifier, not the user/model), and the clause is narrowed going forward — no logical gap between the firing record and the narrowed clause it sits under.
• The #930 → #3750/#3758 reroute reads correctly in isolation; I could not confirm the three issues' actual GitHub state (gh issue view required approval this lane doesn't have — sandboxed, no network) or run markdownlint-cli2/typos/scripts/affected-tests.sh myself, so those specific items in the PR's Verification section are author-claimed and unverified by me, not independently confirmed.

One non-blocking observation, not raised as a finding: the new ### Output caps stated by the reference subsection sits between enumerated items 2 and 3 of "The three surfaces," breaking that list's numbering flow. Placement there makes sense (it documents caps on the two channels just covered before item 3 introduces the envelope), so this is a matter of taste, not a defect — flagging only in case the author prefers it after item 3 or under its own ## heading.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e694917990

ℹ️ 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".

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.