feat(hooks): additionalContext injection advisory + filter-before lever (v5.10 B5) [skip-docs]

HKV now flags hooks that build hookSpecificOutput.additionalContext from
un-grepped command output as an INFO advisory (weight 0, never severity-bearing
— excluded from the self-audit nonInfo set). That field enters Claude's context
every time the hook fires (plain stdout on exit 0 does not), so an unfiltered
payload is a recurring per-turn token cost.

- New lib scanners/lib/hook-additional-context.mjs: pure assessHookAdditionalContext
  (unit-tested, no IO) + IO wrapper assessHookContextForRepo (walk hooks->scripts).
  Heuristic: additionalContext + verbose-prone capture (cat/git log/execSync/…) &&
  no filter (grep/head/jq/.slice). Deliberately low precision -> advisory only.
- HKV: emits the advisory inline on scripts it already reads (after the M5 verbose
  check). Additive, info severity -> frozen v5.0.0 + SC-5 snapshots untouched.
- feature-gap: new filterHookLeverFinding companion, fires ONLY when >=1 chatty
  hook is detected — surfaces the filter-before-Claude-reads lever (CC
  filter-test-output.sh). Silent otherwise (opportunity, not noise).
- docs: README HKV + GAP scanner rows; scanner-internals.md HKV row + full B5
  implementation note. CLAUDE.md kept lean ([skip-docs]); B5 fully documented in
  README + scanner-internals.

Mechanism verified 2026-06-23 against code.claude.com/docs context-window.md
(additionalContext enters context; plain stdout does not). Suite 1239 -> 1254 green.
Version/badges/CHANGELOG wait for the v5.10 release cut.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scanners/feature-gap-scanner.mjs

@@ -14,6 +14,7 @@ import { SEVERITY } from './lib/severity.mjs';
 import { findImports, parseJson, parseFrontmatter } from './lib/yaml-parser.mjs';
 import { measureActiveSkillListing, isBundledSkillsDisabled, BUDGET_CALIBRATION_NOTE } from './lib/skill-listing-budget.mjs';
 import { assessMcpDeferralForRepo } from './lib/mcp-deferral.mjs';
+import { assessHookContextForRepo } from './lib/hook-additional-context.mjs';
 
 const SCANNER = 'GAP';
 
@@ -175,6 +176,41 @@ export function cliOverMcpLeverFinding({ assessment } = {}) {
   });
 }
 
+/**
+ * filter-before-Claude-reads lever — remediation companion to HKV's B5 advisory
+ * (v5.10). Fires ONLY when ≥1 active hook was detected injecting unfiltered
+ * command output into additionalContext, i.e. when there is a measured chatty
+ * hook to fix. When no such hook exists there is nothing to recommend and we
+ * stay silent — opportunity, not noise (same "fire only under measured pressure"
+ * contract as the cliOverMcp / bundledSkills levers).
+ *
+ * Pure and exported for unit testing.
+ *
+ * @param {{ flaggedHooks: Array<{event:string, scriptPath:string}> }} args
+ * @returns {object|null} a GAP finding, or null when no chatty hook was detected
+ */
+export function filterHookLeverFinding({ flaggedHooks } = {}) {
+  const hooks = Array.isArray(flaggedHooks) ? flaggedHooks : [];
+  if (hooks.length === 0) return null;
+  const scripts = hooks.map((h) => h.scriptPath.split('/').slice(-1)[0]).join(', ');
+  return finding({
+    scanner: SCANNER,
+    severity: SEVERITY.info,
+    title: 'Filter hook output before it enters context',
+    description:
+      `${hooks.length} active hook${hooks.length === 1 ? '' : 's'} build hookSpecificOutput.additionalContext ` +
+      "from un-grepped command output (see HKV advisory). That field enters Claude's context on every fire, " +
+      'so filtering verbose output down to what matters BEFORE Claude reads it reclaims per-turn tokens — the ' +
+      'documented filter-test-output.sh pattern (grep ERROR and return only matches instead of a 10,000-line log).',
+    evidence: `chatty_hooks=${hooks.length}; scripts=${scripts} (companion to HKV additionalContext advisory)`,
+    recommendation:
+      'In each flagged hook, pipe the command output through grep/head/jq to keep only the actionable lines ' +
+      'before assigning additionalContext. Reserve additionalContext for concise signals; leave bulk diagnostics ' +
+      'on plain stdout (exit 0) so they go to the debug log, not context.',
+    category: 'token-efficiency',
+  });
+}
+
 /** @type {GapCheck[]} */
 const GAP_CHECKS = [
   // --- Tier 1: Foundation ---
@@ -489,6 +525,12 @@ export async function scan(targetPath, sharedDiscovery) {
   const cliLever = cliOverMcpLeverFinding({ assessment: mcpAssessment });
   if (cliLever) findings.push(cliLever);
 
+  // filter-before-Claude-reads lever — companion to HKV's B5 advisory: fires
+  // only when an active hook injects unfiltered output into additionalContext.
+  const flaggedHooks = await assessHookContextForRepo(discovery);
+  const hookLever = filterHookLeverFinding({ flaggedHooks });
+  if (hookLever) findings.push(hookLever);
+
   const filesScanned = discovery.files.length;
   return scannerResult(SCANNER, 'ok', findings, filesScanned, Date.now() - start);
 }