Skip to content

feat(harness-ops): route repository hook telemetry through the reference sink without a copy - #14270

Closed
melodic-automation-lanes[bot] wants to merge 1 commit into
mainfrom
work-resolve-issue/issue-14227-42530364537-1
Closed

melodic-automation-lanes[bot] wants to merge 1 commit into
mainfrom
work-resolve-issue/issue-14227-42530364537-1

Conversation

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor

Closes #14227

Summary

Opened by the work-resolve-issue lane. The run's own summary:

The reference sink now fills subject from data.file when data.subject is absent, so {tool, file} rows from guardrails and the formatters keep their subject. A new SessionStart hook, hooks/hook-telemetry-launcher.sh, writes a launcher at <log root>/hook-telemetry-sink.sh that runs the installed sink, but only when HOOK_TELEMETRY_SINK names that path. A repository wires "HOOK_TELEMETRY_SINK": ".observability/claude/hook-telemetry-sink.sh" in settings.json and keeps no copy. Choice of means, from the issue's two options (a shipped hook or a path the plugin resolves): a SessionStart hook writing a gitignored launcher. Producers resolve only the env var. CLAUDE_ENV_FILE is documented for Bash commands only, not hooks, so it could not carry the path. The launcher lives under the log root's self-ignoring .gitignore and is rewritten when a plugin update moves the install. It also carries session_event_log_dir and hook_events_max_bytes, because producers in other plugins run without harness-ops' options. The README now lists the launcher route first and names all three files the copy route needs.

Not verified

  • The shell test suites (hook-telemetry-sink.test.sh, hook-telemetry-launcher.test.sh, scripts/node-notice-rows.test.sh) were not executed directly: this lane's Bash runs only the named wrappers. Left to the PR's CI.
  • Whole-repo scanners check-affected marks CI-only (hook-slow-shapes, hook-exec-form, hooks-description, silent-skips, fixture-git-isolation, test-tmp-cleanup, purged-em-dashes and others) did not run here; left to the PR's CI.
  • The two new scripts were created with Write and are mode 100644, while sibling hook scripts are 100755. The lane cannot chmod. Both run through bash &lt;path&gt; (exec-bash.mjs and the test runner), so the mode should not matter, but a reviewer may want +x for consistency.
  • tidy ran passes 1-4 in full but pass 5 (ai-slop:audit fix) only as a hand rubric read: detect.sh and digest-guard.sh cannot run in this lane, and no findings file was written. Rows dropped from tidy: plugins/harness-ops/hooks/hooks.json and hook-telemetry-launcher.sh (hook wiring is on tidy's hard…
  • This repository's own copy at .claude/hooks/hook-telemetry-sink.sh, wired by .claude/settings.json, still maps subject from data.subject only. The issue asks for the plugin change, and .claude/hooks is outside this lane's write scope; switching this repo to the launcher route, or patching that…
  • The new SessionStart row adds sh + node + bash process starts on every startup, resume, clear and fork session start for every harness-ops user, even when nothing is wired. The script exits at its first line when HOOK_TELEMETRY_SINK is unset. exec-bash.mjs has no gate on an arbitrary env var, so…

Fix

  • plugins/harness-ops/hooks/hook-telemetry-sink.sh: subject maps from .data.subject // .data.file // ""; the header comments describe the new mapping and the launcher wiring.
  • plugins/harness-ops/hooks/hook-telemetry-sink.test.sh: new case for a {tool, file} envelope (subject from data.file, record schema holds) and a case where data.subject wins over data.file.
  • plugins/harness-ops/hooks/hook-telemetry-launcher.sh: new SessionStart script. It writes or refreshes the launcher under the log root when HOOK_TELEMETRY_SINK names it, anchored on the repository root via hook::repo_root_to like the sink. It honors the root guard (slog_guard_ok), writes atomically,…
  • plugins/harness-ops/hooks/hook-telemetry-launcher.test.sh: new black-box suite. Covers: wired write and executable bit; guard healed; an envelope through the launcher lands a row with subject from data.file; no rewrite when unchanged; an edited launcher is restored; a subdirectory session writes…
  • plugins/harness-ops/hooks/hooks.json: new SessionStart row in the canonical node-or-skip polyglot shape (scripts/node-notice-rows.test.sh), running exec-bash.mjs with the launcher script; the description mentions it.
  • plugins/harness-ops/README.md: 'Wiring the reference sink' adds the copy-free launcher route (including its node need, the subdirectory behavior and the configured-root case). The copy route now lists hook-telemetry-sink.sh, hook-utils.sh and session-log-lib.sh, and the absolute-path route is kept.
  • .changes/harness-ops/work-resolve-issue-issue-14227-42530364537-1-206761a6.md: minor changelog fragment (Added: the launcher route; Fixed: subject from data.file, README copy list).

Verification

The runner ran each check from the base copy against a1d425b:

  • scripts/check-changelog-fragments.sh --check: passed
  • scripts/check-changed-skills.sh --merge-base: passed

The run reports:

  • check-changelog-fragments: all 6 fragments valid (run before and after tidy and the review fixes).
  • check-changed-skills: no changed skills, nothing to gate.
  • check-affected: 13 passed, 6 skipped (ruff: no .py; typos: not installed; three validate-plugins sub-checks that run tree code; changed-skills: none), over 7 changed files, after the final edits.
  • cant-fail-scan --file plugins/harness-ops/hooks/hook-telemetry-launcher.test.sh --check: PASS, no gating findings.
  • cant-fail-scan --file plugins/harness-ops/hooks/hook-telemetry-sink.test.sh --check: PASS, no gating findings.
  • read lib/hook-utils.sh hook::data_json_to: builds {tool, file} data with no subject key, confirming the empty-subject cause.
  • read lib/hook-utils.sh hook::emit_telemetry: a relative HOOK_TELEMETRY_SINK is joined onto the repo root and run directly as "$sink" with the envelope on stdin, so a launcher at a repo-relative path is reachable.
  • read scripts/node-notice-rows.test.sh: SessionStart rows that need node must use the node-or-skip polyglot, not exec form; the new row follows it.
  • read https: //code.claude.com/docs/en/env-vars: settings env values are copied into Claude Code's environment as written, and no shell processes them, so ~ and $HOME stay as typed; Claude Code writes each env entry into the process environment.
  • read https: //code.claude.com/docs/en/hooks: CLAUDE_ENV_FILE is available to SessionStart, Setup, CwdChanged and FileChanged hooks and persists variables into later Bash commands; the page does not say it reaches hook commands, so it was not used.
  • fresh-context review subagent over the whole diff: no high findings. Two medium findings, both fixed: anchor on the repository root, not raw CLAUDE_PROJECT_DIR (with a new subdirectory test); document the node dependency. Two low test findings fixed: the unchanged-rewrite case now checks mtime, and…
  • The lane run: https://github.com/melodic-software/claude-code-plugins/actions/runs/42530364537

Left out: the items under Not verified.

Related

#14227

Lane-Activity: work-resolve-issue/resolve-issue

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-security-review: 1 inline finding(s) on a1d425b7bc2e66cca2c7952e2f21b438cd014c91; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

Comment on lines +71 to +72
tmp="$launcher.$$"
if printf '%s\n' "$body" >"$tmp" 2>/dev/null && chmod +x "$tmp" 2>/dev/null; then

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The temporary file is opened through a symlink, then marked executable. tmp="$launcher.$$" is a name an attacker can predict, and it sits inside the repository's log root. printf ... >"$tmp" follows a symlink and truncates its target, and chmod +x "$tmp" then marks that target executable. slog_root_to checks only where the root directory physically is, not the files inside it.

Exploit path: a repository commits .observability/claude/.gitignore (*) plus symlinks named hook-telemetry-sink.sh.<pid> across the PID range, pointing at a file in the user's home such as ~/.bashrc, and wires HOOK_TELEMETRY_SINK to the launcher path. When the session-start PID matches one of them, that user file is overwritten with the launcher text and made executable. The text is fixed, so this is a clobber or breakage, not code execution. That is why this is a suggestion and not a blocker.

The guard in session-log-lib.sh already uses an exclusive create for the same reason. Doing the same here refuses an existing path, a planted symlink included:

Suggested change
tmp="$launcher.$$"
if printf '%s\n' "$body" >"$tmp" 2>/dev/null && chmod +x "$tmp" 2>/dev/null; then
tmp="$launcher.$$"
if (set -o noclobber; printf '%s\n' "$body" >"$tmp") 2>/dev/null && chmod +x "$tmp" 2>/dev/null; then

severity: SUGGESTION

claude-lane: claude-security-review

@github-actions

github-actions Bot commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

claude-security-review reviewed a1d425b7bc2e66cca2c7952e2f21b438cd014c91: read 7 of 7 changed file(s); 1 finding(s), 1 as inline comments.

Security review: PR #14270 (harness-ops reference-sink launcher)

None of the 7 changed files matches a TRUSTED PATHS: glob, and no trust control is touched. That means no change to the trusted-actor list, the lane token, the kill switch, the signer or any merge hold. No plugin.json or marketplace.json changes, so there are no manifest lines.

What I checked

  • New SessionStart hook (hooks/hooks.json, hooks/hook-telemetry-launcher.sh). Every existing harness-ops user gets this hook on update. The code it runs is in this repository, it uses the existing node-or-skip polyglot shape and it pulls nothing from outside. The script exits early unless HOOK_TELEMETRY_SINK names exactly <log root>/hook-telemetry-sink.sh. The launcher text it writes is fixed. The only values written into it are the sink's own physical path and CLAUDE_PLUGIN_OPTION_SESSION_EVENT_LOG_DIR / CLAUDE_PLUGIN_OPTION_HOOK_EVENTS_MAX_BYTES, and all three are %q-quoted (launcher lines 52 and 59). So repository- or user-controlled text cannot add shell code to the launcher.
  • Where the file lands. slog_root_to checks the root twice: by its text, rejecting absolute, ~, .. and \ paths, and by its physical location (cd -P on the nearest existing ancestor must sit below the physically resolved project). See session-log-lib.sh#L118-L147. A symlinked root directory therefore cannot send the launcher outside the repository, and slog_guard_ok still refuses a .gitignore an operator changed. The final mv -f replaces a symlink at the launcher path rather than following it.
  • New capability for a repository. None. A repository that sets HOOK_TELEMETRY_SINK could already point producers at any executable it commits. The launcher only runs the plugin's own installed sink.
  • Sink change (.data.subject // .data.file // ""). This only changes which envelope field fills subject. It goes through jq and is written as data, so there is no new injection point.
  • README and changelog. Wiring documentation only. No standing instruction or guardrail is removed.

Finding

  • SUGGESTION (inline, hook-telemetry-launcher.sh line 72): the temporary file $launcher.$$ is opened with a truncating, symlink-following > and then chmod +x. A symlink committed at that predictable name can redirect the write. The impact is limited to overwriting a user file with fixed launcher text, which is not a leak, compromise or charge, so it stays a SUGGESTION.

Spend: one extra short process chain (sh, node, bash) on every session start for each harness-ops user. It exits at once when nothing is wired. This uses no paid resources; it is not a hold and not counted as a finding.

No embedded instructions in the PR context. Prior findings: none (first review, not blocking only).

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 2 inline finding(s) on a1d425b7bc2e66cca2c7952e2f21b438cd014c91; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment on lines +38 to +41
# The repository root, resolved as the sink and hook::emit_telemetry resolve
# it, so a session started in a subdirectory still writes where producers look.
project=""
hook::repo_root_to project "$CLAUDE_PROJECT_DIR" || :

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Advisory: in a subdirectory session, harness-ops' own producers never reach this launcher.

The comment says the root is "resolved as the sink and hook::emit_telemetry resolve it". That is not how emit_telemetry resolves it. hook::emit_telemetry joins a relative HOOK_TELEMETRY_SINK onto the repo_root its caller passes (hook-utils.sh:3484-3491). Every harness-ops producer passes the raw ${CLAUDE_PROJECT_DIR:-}, not a git-resolved root:

Only the formatter/guardrail path (REPO_ROOT, hook-utils.sh:3117) passes the resolved root.

How it fails: start a session in repo/sub with HOOK_TELEMETRY_SINK=.observability/claude/hook-telemetry-sink.sh. This hook writes repo/.observability/claude/hook-telemetry-sink.sh. The harness-ops audit rows (API errors, config changes, permission denials, skill usage, hook failures, and the rest) then exec repo/sub/.observability/claude/hook-telemetry-sink.sh. That file does not exist, so they drop every envelope silently. Formatter rows still land. The README says the launcher "goes under the repository root even when a session starts in a subdirectory", which reads as if subdirectory sessions work. The new subdirectory test only checks where the file is placed, not that a harness-ops producer reaches it.

The raw-root callers predate this PR, but this route is what makes the scenario a documented one. Possible fix: have those producers resolve the root with hook::repo_root_to before calling emit_telemetry, the way the formatter path does. Alternatively, narrow the README and comment claims. In either case, add a test that pipes an audit-event-emitter.sh row through a subdirectory session.

claude-lane: claude-review

Comment on lines +282 to +287

- **Copy the reference sink into your repository** (for example
`.claude/hooks/hook-telemetry-sink.sh`) and wire that repository-relative
path. The sink sources two files from its own directory, so copy all three
side by side: `hook-telemetry-sink.sh`, `hook-utils.sh` (for
`hook::repo_root_to`) and `session-log-lib.sh` (the log root, the guard and

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Advisory: the closing-issue criterion is met, but nothing tests it.

#14227's criterion reads: "The README's copy route, if kept, lists every file the sink needs." This list now names hook-telemetry-sink.sh, hook-utils.sh and session-log-lib.sh, which matches the sink's two source lines today. No test in the PR or the repository compares the two, so the next source added to hook-telemetry-sink.sh would make this list incomplete again, unnoticed. That is how the original gap arose.

Possible fix: a test that does one of these:

  • Extracts the sink's source "$HOOK_DIR/..." targets and checks that each appears in this list.
  • Copies exactly the listed files into a temporary directory and pipes one envelope through the copy.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

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

Code review: PR #14270, harness-ops copy-free route to the reference sink

I read every hunk of all 7 changed files. I also read the code the changed lines call: slog_root_to, slog_guard_ok and slog_contained in session-log-lib.sh; hook::repo_root_to and hook::emit_telemetry in hook-utils.sh; node-or-skip.sh; the argument handling in exec-bash.mjs; and the emit_telemetry callers in harness-ops.

Closing issue #14227, done-when criteria

  • "The sink maps subject from .data.subject // .data.file, with a test for a {tool, file} envelope": met. The change is at hook-telemetry-sink.sh:77. New cases in hook-telemetry-sink.test.sh cover it, including that data.subject wins over data.file.
  • "A repository can point its hook producers at the plugin's sink with no copy in the repository, through a shipped hook or a path the plugin resolves itself, documented in the README": met for producers that pass a resolved repository root. The launcher hook and its black-box test pipe an envelope through the launcher to a written row. There is one gap for sessions started in a subdirectory: harness-ops' own audit rows look for the launcher in the subdirectory, not the repository root (inline comment on hook-telemetry-launcher.sh:38-41).
  • "The README's copy route, if kept, lists every file the sink needs": met, but nothing tests it (inline comment on README.md:282-287).

Checked and found fine

  • want="${want#./}" cannot hide a mismatch: slog_contained rejects a ./ segment in session_event_log_dir.
  • The launcher is compared and rewritten atomically. The existing launcher is read with IFS= read -d '', so trailing bytes survive and the compare against "$body"$'\n' holds.
  • The %q-quoted target and options are safe when the cache path contains spaces.
  • An empty HOOK_TELEMETRY_SINK exits before anything is sourced.
  • The new hooks.json row follows the node-or-skip polyglot shape used by its siblings.
  • No plugin.json or marketplace.json changed, so no manifest lines apply. The fragment's bump: minor fits an added capability.
  • The PR body's "Not verified" note says the two new scripts are mode 100644. The diff creates both as 100755, so that note is out of date.

Runtime cost (not a hold, not counted)
The new SessionStart row starts sh, node and bash on every startup, resume, clear and fork for every harness-ops user, even when nothing is wired. This uses local process time only, with no billing effect. The script exits on its first check when HOOK_TELEMETRY_SINK is unset. exec-bash.mjs's --run-if-any-set gate reads only CLAUDE_PLUGIN_OPTION_* names, so it cannot gate on this variable.

Not verified by me
I had no shell, so I ran none of the test suites. The author's verification list is unverified on my side and left to the PR's CI.

@kyle-sexton

Copy link
Copy Markdown
Member

Closing in favor of #14279, which implements the design the owner chose for #14227 on 2026-11-08 (option (a)): a stable launcher under the harness-ops plugin data directory, refreshed on SessionStart, and one reserved HOOK_TELEMETRY_SINK value, @harness-ops, that producers resolve to that launcher.

This PR takes a different route. It writes the launcher under each repository's log root and wires it by relative path, with no reserved value and no producer change. #14279 also carries this PR's subject fallback to data.file and the README copy-route file list, so nothing here is lost.

@kyle-sexton

Copy link
Copy Markdown
Member

Superseded by #14279; reason in the comment above.

@kyle-sexton kyle-sexton closed this Nov 8, 2026
@github-actions
github-actions Bot deleted the work-resolve-issue/issue-14227-42530364537-1 branch November 9, 2026 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Route repository hook telemetry through the harness-ops sink without a copy

1 participant