Skip to content

fix(session-telemetry): register only the event categories the session event log records - #16665

Merged
kyle-sexton merged 6 commits into
mainfrom
feat/15976-session-event-log-sec-default
Nov 17, 2026
Merged

kyle-sexton merged 6 commits into
mainfrom
feat/15976-session-event-log-sec-default

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

Closes #15976

Summary

With session_event_log_categories set, the session event log's hooks module now registers only the classic.* events in the enabled categories, plus SessionEnd always, for retention. Before this change it registered all 28 observable events. An event outside the list started node and bash only to be filtered out by the script, and where the built-in guard sec-default holds classic.* hooks, it was reported as skipped even though the user never asked to record it. This is the owner's 2026-11-13 decision recorded in the issue: the minimum fix plus the category filter (part A). Part B, the setup warning, is #15993.

The log moved from harness-ops into plugins/session-telemetry/ in #16519 after this issue was written. The paths below are the new ones; the intent is unchanged. Nothing here loosens or detects the guard: the module only registers fewer hooks.

Fix

  • plugins/session-telemetry/hooks/register.ts: exports categoryFilter, which parses the option exactly as slog_category_enabled does: unset or empty means all; commas, spaces, tabs and newlines separate; matches are case-sensitive; \r is not a separator. Each generated on('classic.<Event>', …) is guarded by if (wants('<category>')), and each event name stays a literal. SessionEnd is always hooked; it runs session-event-log.sh only when session is enabled, and session-retention.sh always.
  • scripts/gen-hook-event-registry.sh: mod_ts writes the guarded block from the registry's category field, and SessionEnd unguarded. The block was applied by hand from the --check diff, so registry as_of stamps are unchanged.
  • Docs:
    • session-telemetry README: registration follows the categories; SessionEnd is kept for retention; where sec-default loads (managed settings, managed-mcp.json, or a Team or Enterprise /login); the /plugin note and the 2.1.304+ per-event lines; no user off switch; the two administrator routes, linked to the mods admin page. No claim that the /plugin note shrinks.
    • Option descriptions updated, and the README options table regenerated.
    • harness-ops setup skill: cost sentence.
    • ADR 0065: amendment, which narrows the Decision and supersedes nothing.
  • Changelog fragments: session-telemetry patch, harness-ops patch.
  • The script's own category filter stays in place as a backstop.
  • The three paths the issue names in its admission text (pr-test-platforms.yml, work-resolve-issue.yml, .claude/rules/mod-authoring.md) are unchanged: no done-when item requires editing them.

Verification

Counter (the binding gate). Switch on, categories permission,tool, every $.classic key fired:

origin/main branch
events that start a process 28 5
process runs in total 29 (baseline figure from the issue) 5

On main, the new category-budget test fails, and its toEqual diff lists all 28 events; the SessionEnd "turn" case also fails (it runs both scripts), and category-filter.test.ts fails to load. Result: 14 pass, 3 fail. The run total of 29 is the issue's baseline: on main the test stops at the event list before it reaches the total.

On the branch, claude plugin test plugins/session-telemetry (Claude Code 2.1.326): 27 pass, 0 fail.

Wall time, same host (Linux), 5 interleaved rounds per arm, using the issue's script (it times the script path, which this change does not touch):

arm main median (max) branch median
filtered-out Stop 54.9 ms (58.6) 56.2 ms
in-set PostToolBatch 59.1 ms (60.3) 53.5 ms

Other checks:

  • session-event-log.test.sh: PASS=205, including the shared 11-row parse table against slog_category_enabled.
  • gen-hook-event-registry.test.sh: PASS=26.
  • gen-hook-event-registry.sh --check: clean.
  • claude plugin validate --json on session-telemetry and on harness-ops: success: true.
  • scripts/check-affected.sh: 18 passed, 1 skipped.
  • check-changelog-fragments.sh --check and --check-required origin/main: pass. The bare command the issue's AC8 names now exits with a usage error, so these two forms were run in its place.
  • sync-plugin-options-docs.py --check: up to date.
  • cant-fail-scan --check on the new tests: no gating findings.

Not run: /code-metrics:audit, /simplify, /review:quality-gate, /verification:confirm. Waste pass by reading the diff: the only new runtime work is one categoryFilter call per SessionEnd; there are no added process starts, loops or git calls. Behavior under the guard rests on the docs read, since claude plugin test cannot load sec-default.

The ADR amendment is dated 2026-11-16; correct it if the merge lands on another day.

Related

🤖 Generated with Claude Code

kyle-sexton and others added 6 commits November 16, 2026 18:49
…cords

With session_event_log_categories set, the hooks module now hooks only
the classic events in the enabled categories, plus SessionEnd always for
retention; SessionEnd writes its record only when the session category
is enabled. An event outside the list starts no process, and where the
built-in guard holds classic.* events only the chosen events are held.

categoryFilter restates slog_category_enabled; one parse table pins both.
The generator writes each observed event behind wants('<category>').

Refs: #15976

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README, option descriptions, harness-ops setup cost sentence and
ADR 0065 amendment now say registration follows
session_event_log_categories, SessionEnd stays hooked for retention,
where sec-default loads and which administrator actions let the log run
there. Adds the session-telemetry changelog fragment and tightens the
new code comments.

Refs: #15976

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tence

Refs: #15976

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…heck

Refs: #15976

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ctly

The module header and README cost paragraph no longer say every event
records and SessionEnd always runs both scripts; the guard paragraph
limits its claim to the per-event skip lines, not the /plugin note.

Refs: #15976

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dget

The two descriptions this change extended stay within the 300-character
option-description budget.

Refs: #15976

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 17, 2026 00:02
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T00:05:04.013100Z 2bca240 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.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 43984396088

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 2bca240fe858a4f9e3e43f6aa36a5e63076e43f9: read 12 of 12 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16665 (head 2bca240)

No security issues found. I read the whole diff for all 12 changed files.

critical-findings: 0

What I checked

  • plugins/session-telemetry/hooks/register.ts: the change only narrows what gets registered. The new categoryFilter parses session_event_log_categories into a Set and only checks membership. That value never reaches a shell, a path or an eval. Each event name is still a string literal. The session_event_log_enabled !== true early return is unchanged, so a default-off install still hooks nothing. SessionEnd now skips session-event-log.sh when the session category isn't listed. session-retention.sh still runs, behind the same switch as before, so session_log_pre_prune_command's trust boundary is unchanged. When recorded is false, false goes into Promise.all, which is harmless.
  • scripts/gen-hook-event-registry.sh: mod_ts now puts the registry's .category field into the generated TS (wants('<category>')). The registry is a committed file in this repository, so only a commit could change what gets written there, and --check diffs the generated block against the module. Nobody outside the repository can reach it.
  • Tests (category-filter.test.ts, session-event-log.test.{sh,ts}, gen-hook-event-registry.test.sh): test code only. The bash filter_case passes the option value to env as one quoted argument and runs a fixed bash -c string. Untrusted input doesn't reach it.
  • Docs, ADR 0065 amendment, harness-ops setup SKILL.md, changelog fragments: prose only. The SKILL.md edit rewords a cost sentence and removes no rule, so the instruction-surface lens finds nothing.
  • Trusted paths: none of the changed files match a TRUSTED PATHS: glob. No trust control, token scope, kill switch or merge hold is touched.

Plugin manifest (plugins/session-telemetry/.claude-plugin/plugin.json)

  • manifest userConfig.session_event_log_enabled.description: pass (a userConfig key's description is in the inert set; type and default: false are unchanged)
  • manifest userConfig.session_event_log_categories.description: pass (a userConfig key's description is in the inert set; type and default: "" are unchanged)

PR context

The description and the closing-issue comment contain no embedded instructions to the review lane.

Cost

No billing surface. The change starts fewer local processes, not more.

@github-actions

Copy link
Copy Markdown
Contributor

claude-review reviewed 2bca240fe858a4f9e3e43f6aa36a5e63076e43f9: read 12 of 12 changed file(s); 0 finding(s), 0 as inline comments.

Code review: no findings

I read the whole diff (all 12 listed files), plus the code the changed lines call: register.ts at head, session-event-log.test.ts at head, and slog_category_to / slog_category_enabled in plugins/session-telemetry/hooks/session-log-lib.sh.

Correctness checks

  • categoryFilter parsing. register.ts:30-35 parses the option the same way slog_category_enabled does:
    • unset or empty enables every category;
    • commas become spaces, then the value splits on space, tab and newline only;
    • " " enables nothing, because it leaves only an empty token;
    • \r is not a separator.
      The hooks scripts never change IFS before the call, so the bash side uses the default split.
  • Category table. Every wants('<category>') in the generated block matches the event's category in slog_category_to (session-log-lib.sh:512-531), so no event is registered for one category and filtered under another.
  • SessionEnd. It stays unguarded. Retention always runs, and session-event-log.sh is skipped only when session is not enabled. false inside Promise.all is harmless.
  • Generator. In gen-hook-event-registry.sh, jq's sort_by(.name) sorts by codepoint, which is the same as the old LC_ALL=C sort for ASCII names. The new output matches the hand-applied block in register.ts and the new EXPECTED_BLOCK.
  • Tests. In the new category-budget test, world(..., every) stubs every $.classic key, so events that are not registered still resolve. fire settles the clock, so the deferred writes are counted.

Closing issue #15976 (part A).

  • Each code criterion has a test that could fail:
    • the category budget, 5 events and 5 runs;
    • the three SessionEnd cases;
    • the shared 11-row parse table, run against both categoryFilter and slog_category_enabled;
    • the rewritten EXPECTED_BLOCK.
  • The doc items are present:
    • README registration and guard text;
    • the tested-version line raised to 2.1.326;
    • the .gitignore guard wording;
    • the option descriptions and the regenerated options table;
    • the setup skill's cost sentence;
    • the ADR 0065 amendment and Status line;
    • the patch fragments.
  • The PR's test and timing results are claimed by the author and not checked here; this lane ran nothing. The ADR amendment date (2026-11-16) stands in for the merge date, as the PR body notes.

Plugin manifest (plugins/session-telemetry/.claude-plugin/plugin.json; only two userConfig descriptions change):

  • manifest userConfig default: pass (no default changed and no field removed)
  • manifest userConfig options: pass (none added or changed)
  • manifest version: pass (fragment bump: patch fits a fix that only narrows which hooks register)
  • manifest description: pass (the top-level description still matches what ships)

Path-scoped rule. .claude/rules/mod-authoring.md matches plugins/session-telemetry/hooks/**. It asks the author to load a skill and read a convention before editing, which a reviewer cannot check from the diff. The on() calls keep string-literal event names, as the mods validation rule requires.

Embedded text. None of the PR context asks the lane to approve, skip or drop anything.

Spend. None: the change registers fewer hooks and adds no paid resources.

Verifier dropped 0 of 0 candidates.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 3b36caf Nov 17, 2026
80 checks passed
@kyle-sexton
kyle-sexton deleted the feat/15976-session-event-log-sec-default branch November 17, 2026 00:29
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Post-merge mutation testing

Killed 1, survived 6, timeout 0, no coverage 0, invalid 0, not run 0.
Covered-code score 14%; mutation score 14%.

File Killed Survived Timeout No coverage Invalid Not run
plugins/session-telemetry/hooks/register.ts 0 6 0 0 0 0
scripts/gen-hook-event-registry.sh 1 0 0 0 0 0

Surviving mutants

Location Operator Disposition Cause
plugins/session-telemetry/hooks/register.ts:31 ROR unclassified none
plugins/session-telemetry/hooks/register.ts:32 SBR unclassified none
plugins/session-telemetry/hooks/register.ts:33 other unclassified none
plugins/session-telemetry/hooks/register.ts:72 LCR unclassified none
plugins/session-telemetry/hooks/register.ts:85 other unclassified none
plugins/session-telemetry/hooks/register.ts:106 SBR unclassified none

The run's summary has the full report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(harness-ops): make the session event log run where sec-default holds classic.*

1 participant