feat(disk-hygiene): adopt HOOK_TELEMETRY_SINK on both wired hooks

[kyle-sexton]

Problem

docs/conventions/hook-observability/README.md requires that every hook wired in a plugin's
hooks.json emit a HOOK_TELEMETRY_SINK envelope "for each meaningful outcome it produces (a check
that ran and returned ok / blocked / skipped-for-cause)", with the carve-out limited to "a pure
inapplicability short-circuit before any check logic runs".

disk-hygiene emits nothing. A search across plugins/disk-hygiene/ finds zero references to
HOOK_TELEMETRY_SINK or hook::emit_telemetry. That covers both wired hooks:

• PreToolUse — skills/clean/scripts/destructive_guard.py (pre-existing, wired before fix(disk-hygiene): surface silent destructive-guard launch failures #1465)
• Stop — skills/clean/scripts/guard_launch_monitor.py (added by fix(disk-hygiene): surface silent destructive-guard launch failures #1465)

A guard failure found and reported is a meaningful outcome, so the inapplicability exemption does not
apply. Fleet telemetry silently omits the guard failures the detector exists to expose.

Why this is deferred rather than fixed in #1465

Every current emitter in the marketplace goes through the bash hooks/hook-utils.sh
hook::emit_telemetry helper (typos-format, ruff-format, markdown-format, powershell-format,
go-format, eol-normalizer, guardrails, claude-ops, desktop-notification, rate-limit-guard). There is
no Python telemetry emitter anywhere in the marketplace.

Emitting the envelope from guard_launch_monitor.py would stand up the fleet's first Python
telemetry producer — hand-rolled envelope construction plus fire-and-forget sink dispatch — inside a
module whose stated contract is stdlib-only with a near-zero failure surface and a "never fail
loudly" guarantee. That is a reuse-or-replace decision (reuse the established bash helper, or
deliberately stand up a second, parallel Python way and record the decision) that #1465's diff does
not settle. Adopting it on one of the plugin's two wired hooks while the primary guard still emits
nothing would also be half an adoption.

#836 (fleet OTel-envelope adoption) is closed, so this issue is the tracker.

Scope

Both wired hooks, not just the new one — a fix that instruments only guard_launch_monitor.py
leaves the plugin's primary safety gate silent and does not close this.

Re-open / close trigger

Closed when both disk-hygiene wired hooks emit HOOK_TELEMETRY_SINK envelopes for their meaningful
outcomes, through whichever mechanism the reuse-or-replace call selects, with the language choice
recorded if it is a new parallel Python path.

Source

Codex review finding (P2) on #1465,
plugins/disk-hygiene/skills/clean/scripts/guard_launch_monitor.py:258.

[kyle-sexton]

This was generated by AI during triage.

Triage

Verified. Searched plugins/disk-hygiene/ at origin/main (efb6c271, current tip as of triage) for HOOK_TELEMETRY_SINK and emit_telemetry — zero matches. Confirmed both wired hooks (destructive_guard.py on PreToolUse, guard_launch_monitor.py on Stop) emit no telemetry envelope. This matches the report exactly.

Classification

• Type: Task — this is instrumenting two already-shipped hooks with observability, not a new user-facing capability; commit-type granularity (feat(...) in the title) stays at the commit layer per this repo's type-axis convention, not the issue type.
• Priority: priority: medium — a real fleet-observability gap (guard failures are invisible to telemetry aggregation even though they still reach the user via systemMessage/deny), but it is not a functional-correctness defect and carries no deadline; tracks the source Codex review's P2 severity.
• Route: human-gated, not decision-defaulted. The issue frames this correctly as a reuse-or-replace decision the source PR deliberately left unsettled: every existing hook::emit_telemetry producer in the marketplace is a bash helper (hooks/hook-utils.sh), and this would be the fleet's first Python telemetry producer. The "obvious" default — shell out to the bash helper from Python — is not a safe default here: guard_launch_monitor.py's stated contract is stdlib-only with a near-zero failure surface, and this repo's CI enforces cross-platform (Windows/PowerShell) portability, which a bash-subprocess dependency would put at risk on native Windows. That leaves no single low-cost, maintainer-vetoable default — it's a genuine architecture call (reuse via subprocess vs. a new native Python emitter, and if the latter, how much of the envelope-construction/sink-dispatch logic to duplicate vs. share). Evaluated independently from fix(disk-hygiene): guard-launch detector's tail window slides forward, so a failure pushed past 2 MB is never reported #1514: same source PR review round, different decision (telemetry-emitter language/reuse choice here vs. read-window/cursor architecture there) — not one shared decision carrier.

Agent Brief

Type: Task
Summary: Instrument both of disk-hygiene's wired hooks (the pre-existing PreToolUse guard and the Stop-registered launch-failure detector) to emit HOOK_TELEMETRY_SINK envelopes for their meaningful outcomes, per docs/conventions/hook-observability/README.md.

Current behavior: Neither hook emits any telemetry envelope. A check that ran and returned ok/blocked, or a guard-launch failure the detector found and reported, is invisible to fleet telemetry aggregation even though the guard's own guarded-command result and the detector's systemMessage are still visible to the operator directly.

Desired behavior: Both hooks emit a HOOK_TELEMETRY_SINK envelope for each meaningful outcome they produce (a check that ran and returned ok/blocked/skipped-for-cause), consistent with every other emitter in the marketplace, via whichever mechanism the reuse-or-replace decision below selects.

Key interfaces:

• The established bash hook::emit_telemetry helper (hooks/hook-utils.sh) — the fleet's current sole telemetry-emission path; used by every other emitting hook (typos-format, ruff-format, markdown-format, powershell-format, go-format, eol-normalizer, guardrails, claude-ops, desktop-notification, rate-limit-guard).
• A prospective native Python telemetry emitter (envelope construction + fire-and-forget sink dispatch) for a hook implemented in Python, if the decision favors not depending on bash/subprocess from a stdlib-only, near-zero-failure-surface module.

Acceptance criteria:

• Both disk-hygiene wired hooks emit a HOOK_TELEMETRY_SINK envelope for every meaningful outcome (checked/ok, blocked, skipped-for-cause) they produce — not just the newer detector.
• The reuse-or-replace call is recorded (which mechanism was chosen and why) at the point it is implemented, since it establishes precedent for future Python-based hooks in the marketplace.
• The chosen mechanism does not compromise guard_launch_monitor.py's existing guarantees: it never blocks, never fails loudly, and stays low-cost on every Stop.
• The chosen mechanism does not introduce a cross-platform (Windows-native) portability regression this repo's CI already guards against.

Out of scope:

• Re-litigating whether telemetry should exist at all — feat(conventions): hook-observability fleet convention + fleet adoption #836 (fleet OTel-envelope adoption) already settled that; this issue is the tracker for disk-hygiene's own adoption.
• Instrumenting only the newer Stop detector while leaving the pre-existing PreToolUse guard silent — the issue is explicit that a fix must cover both.

Why human: Establishing the fleet's first Python telemetry emission path (or deliberately depending on the bash helper from Python) is an architecture precedent decision with cross-plugin implications and a real Windows-portability tradeoff, not a mechanical instrumentation change.

[kyle-sexton]

Frontier disposition (drain session)

Ruling: promoted to agent-ready. The hook-observability convention already mandates HOOK_TELEMETRY_SINK envelopes per meaningful outcome, disk-hygiene emits nothing, and other plugins provide the emission pattern to copy. Scoped adoption on two wired hooks; no human decision outstanding.

[kyle-sexton]

🔒 claim: cursor/fix-1505-disk-hygiene-telemetry-2ae1