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>

tests/fixtures/hooks-additional-context/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "bash ./scripts/chatty.sh", "timeout": 5000 }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bash ./scripts/filtered.sh", "timeout": 5000 }] }
+    ]
+  }
+}

tests/fixtures/hooks-additional-context/hooks/scripts/chatty.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Chatty hook: dumps unfiltered command output straight into additionalContext.
+# Every SessionStart this whole payload enters Claude's context (not just stdout).
+NOTES="$(cat ./STATE.md)"
+LOG="$(git log --oneline)"
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s\n%s"}}' "$NOTES" "$LOG"

tests/fixtures/hooks-additional-context/hooks/scripts/filtered.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Bounded hook: greps the log down to only failures before injecting context.
+# This is the filter-before-Claude-reads pattern — should NOT be flagged.
+ERRORS="$(cat ./test.log | grep -E 'FAIL|ERROR' | head -20)"
+printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}' "$ERRORS"

tests/scanners/feature-gap-scanner.test.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { resetCounter } from '../../scanners/lib/output.mjs';
-import { scan, opportunitySummary, bundledSkillsLeverFinding, cliOverMcpLeverFinding } from '../../scanners/feature-gap-scanner.mjs';
+import { scan, opportunitySummary, bundledSkillsLeverFinding, cliOverMcpLeverFinding, filterHookLeverFinding } from '../../scanners/feature-gap-scanner.mjs';
 import { discoverConfigFiles } from '../../scanners/lib/file-discovery.mjs';
 import { withHermeticHome } from '../helpers/hermetic-home.mjs';
 
@@ -364,3 +364,50 @@ describe('cliOverMcpLeverFinding (CLI-over-MCP lever, v5.10 B4)', () => {
     assert.match(f.recommendation || '', /\bgh\b|\baws\b|\bgcloud\b/);
   });
 });
+
+describe('filterHookLeverFinding (filter-before-Claude-reads lever, v5.10 B5)', () => {
+  it('returns null when no chatty hook was detected', () => {
+    assert.equal(filterHookLeverFinding({ flaggedHooks: [] }), null);
+    assert.equal(filterHookLeverFinding({}), null);
+    assert.equal(filterHookLeverFinding(), null);
+  });
+
+  it('fires an info opportunity when ≥1 chatty hook is detected', () => {
+    resetCounter();
+    const f = filterHookLeverFinding({
+      flaggedHooks: [{ event: 'SessionStart', scriptPath: '/x/hooks/scripts/chatty.sh' }],
+    });
+    assert.ok(f, 'expected a lever finding');
+    assert.equal(f.severity, 'info');
+    assert.equal(f.category, 'token-efficiency');
+    assert.match(f.description || '', /filter-test-output\.sh|filter/i);
+    assert.match(f.evidence || '', /chatty_hooks=1/);
+  });
+});
+
+describe('GAP scanner — filter-before lever wiring (chatty hook fixture)', () => {
+  it('emits the filter-before lever when scanning a repo with a chatty hook', async () => {
+    resetCounter();
+    const discovery = await fixtureDiscovery('hooks-additional-context');
+    const result = await withHermeticHome(() =>
+      scan(resolve(FIXTURES, 'hooks-additional-context'), discovery),
+    );
+    const lever = result.findings.find(
+      f => f.scanner === 'GAP' && /chatty_hooks=/.test(f.evidence || ''),
+    );
+    assert.ok(lever, `expected filter-before lever; got: ${result.findings.map(x => x.title).join(' | ')}`);
+    assert.equal(lever.severity, 'info');
+  });
+
+  it('does NOT emit the lever for a repo with only quiet hooks', async () => {
+    resetCounter();
+    const discovery = await fixtureDiscovery('hooks-quiet');
+    const result = await withHermeticHome(() =>
+      scan(resolve(FIXTURES, 'hooks-quiet'), discovery),
+    );
+    const lever = result.findings.find(
+      f => f.scanner === 'GAP' && /chatty_hooks=/.test(f.evidence || ''),
+    );
+    assert.equal(lever, undefined, `expected no filter-before lever; got id=${lever?.id}`);
+  });
+});

tests/scanners/hook-additional-context.test.mjs

@@ -0,0 +1,90 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { assessHookAdditionalContext } from '../../scanners/lib/hook-additional-context.mjs';
+
+// B5 (v5.10) — pure heuristic: does a hook script build
+// hookSpecificOutput.additionalContext from un-grepped / verbose command output?
+// Low precision by design (ships as an info advisory, never severity-bearing).
+
+describe('assessHookAdditionalContext — not applicable', () => {
+  it('empty / missing input → not flagged', () => {
+    assert.equal(assessHookAdditionalContext({}).flagged, false);
+    assert.equal(assessHookAdditionalContext({ scriptContent: '' }).flagged, false);
+    assert.equal(assessHookAdditionalContext().flagged, false);
+  });
+
+  it('script with no additionalContext reference → not flagged even if it cats a file', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent: 'CONTENT="$(cat /var/log/big.log)"\necho "$CONTENT"\n',
+    });
+    assert.equal(a.buildsAdditionalContext, false);
+    assert.equal(a.flagged, false);
+  });
+});
+
+describe('assessHookAdditionalContext — shell hooks', () => {
+  it('additionalContext built from an unfiltered cat → flagged', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent:
+        'BODY="$(cat /tmp/notes.md)"\n' +
+        'echo "{\\"hookSpecificOutput\\":{\\"additionalContext\\":\\"$BODY\\"}}"\n',
+    });
+    assert.equal(a.buildsAdditionalContext, true);
+    assert.equal(a.hasVerboseCapture, true);
+    assert.equal(a.hasFilter, false);
+    assert.equal(a.capturesUnfiltered, true);
+    assert.equal(a.flagged, true);
+  });
+
+  it('additionalContext from a git log → flagged', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent:
+        'LOG="$(git log --oneline)"\n' +
+        'printf \'{"hookSpecificOutput":{"additionalContext":"%s"}}\' "$LOG"\n',
+    });
+    assert.equal(a.flagged, true);
+  });
+
+  it('additionalContext from cat piped through grep → NOT flagged (filtered)', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent:
+        'BODY="$(cat /tmp/test.log | grep ERROR)"\n' +
+        'echo "{\\"hookSpecificOutput\\":{\\"additionalContext\\":\\"$BODY\\"}}"\n',
+    });
+    assert.equal(a.hasFilter, true);
+    assert.equal(a.capturesUnfiltered, false);
+    assert.equal(a.flagged, false);
+  });
+
+  it('additionalContext from a cheap command only ($(date)) → NOT flagged', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent:
+        'NOW="$(date)"\n' +
+        'echo "{\\"hookSpecificOutput\\":{\\"additionalContext\\":\\"$NOW\\"}}"\n',
+    });
+    assert.equal(a.hasVerboseCapture, false);
+    assert.equal(a.flagged, false);
+  });
+});
+
+describe('assessHookAdditionalContext — node hooks', () => {
+  it('execSync(git log) into additionalContext with no slice → flagged', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent:
+        "const out = execSync('git log --oneline').toString();\n" +
+        "process.stdout.write(JSON.stringify({ hookSpecificOutput: { additionalContext: out } }));\n",
+    });
+    assert.equal(a.flagged, true);
+  });
+
+  it('readFileSync sliced before additionalContext → NOT flagged (bounded)', () => {
+    const a = assessHookAdditionalContext({
+      scriptContent:
+        "const raw = readFileSync('big.log', 'utf8');\n" +
+        "const out = raw.slice(0, 400);\n" +
+        "process.stdout.write(JSON.stringify({ hookSpecificOutput: { additionalContext: out } }));\n",
+    });
+    assert.equal(a.hasFilter, true);
+    assert.equal(a.flagged, false);
+  });
+});

tests/scanners/hook-validator.test.mjs

@@ -101,6 +101,46 @@ describe('HKV scanner — verbose hook output (v5 M5)', () => {
   });
 });
 
+describe('HKV scanner — additionalContext injection advisory (v5.10 B5)', () => {
+  it('flags a hook that injects unfiltered command output into additionalContext (info advisory)', async () => {
+    resetCounter();
+    const path = resolve(FIXTURES, 'hooks-additional-context');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    const f = result.findings.find(
+      x => x.scanner === 'HKV' && /additional_context_unfiltered=true/.test(x.evidence || ''),
+    );
+    assert.ok(f, `expected additionalContext advisory; got: ${result.findings.map(x => x.title).join(' | ')}`);
+    assert.equal(f.severity, 'info', `expected info (advisory), got ${f.severity}`);
+    // The chatty.sh script (SessionStart) is the one flagged, not filtered.sh.
+    assert.match(f.file || '', /chatty\.sh$/);
+    // Precision caveat must be disclosed in the description (low-precision advisory).
+    assert.match(f.description || '', /every time|enters Claude's context|advisory/i);
+  });
+
+  it('does NOT flag the filtered (grep|head) sibling hook', async () => {
+    resetCounter();
+    const path = resolve(FIXTURES, 'hooks-additional-context');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    const filtered = result.findings.find(
+      x => x.scanner === 'HKV' && /additional_context_unfiltered=true/.test(x.evidence || '') && /filtered\.sh$/.test(x.file || ''),
+    );
+    assert.equal(filtered, undefined, `filtered.sh should not be flagged; got id=${filtered?.id}`);
+  });
+
+  it('does NOT flag a quiet hook with no additionalContext', async () => {
+    resetCounter();
+    const path = resolve(FIXTURES, 'hooks-quiet');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    const f = result.findings.find(
+      x => x.scanner === 'HKV' && /additional_context_unfiltered=true/.test(x.evidence || ''),
+    );
+    assert.equal(f, undefined, `expected no additionalContext advisory; got id=${f?.id}`);
+  });
+});
+
 describe('HKV scanner — CC 2.1.152 MessageDisplay event (Batch 1 false-positive fix)', () => {
   // The pre-write path-guard blocks committing settings.json/hooks.json, so
   // this suite materializes a hermetic temp fixture at runtime.