feat(scanner): add AGT agent-listing always-loaded budget finding (v5.9 B1)

New AGT scanner flags the aggregate always-loaded cost of the agent listing
(every active agent's name+description is injected each turn so the model
knows what it can delegate to). Mirrors the SKL skill-listing pattern but
encodes the key honesty caveat: the agent-listing mechanism is INFERRED
(agents are absent from Claude Code's documented context breakdown), so the
token figure is an UPPER-BOUND estimate and the aggregate budget is a
config-audit heuristic anchored on 200k — not a CC-documented allotment.

- scanners/agent-listing-scanner.mjs + scanners/lib/agent-listing-budget.mjs
- 8 TDD tests (tests/scanners/agent-listing-scanner.test.mjs)
- AGT folds into the Token Efficiency health area (scoring.mjs)
- byte-stability: AGT added to strip-added-scanner (frozen v5.0.0 baselines
  left untouched, same as OST/OPT); SC-5 default-output snapshot refreshed
- suite 1168 -> 1176 green

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

scanners/agent-listing-scanner.mjs

@@ -0,0 +1,71 @@
+/**
+ * AGT Scanner — Agent-listing always-loaded token budget
+ *
+ * Claude Code injects a listing of every active agent's name+description into the
+ * system prompt so it knows which subagents it can delegate to. That listing is
+ * re-sent on EVERY turn, whether or not a delegation happens — so with many
+ * installed agents it is a large always-loaded cost (on a heavily-plugged machine
+ * the dominant single always-loaded source).
+ *
+ * Detection:
+ *   CA-AGT-NNN  aggregate agent-listing estimate exceeds the listing budget (low)
+ *
+ * INTELLECTUAL-HONESTY CONTRACT (the reason this is `low`, not a hard finding):
+ * unlike the skill listing, the agent-listing mechanism is NOT documented (agents
+ * are absent from Claude Code's published context breakdown). So the finding is an
+ * INFERRED, UPPER-BOUND ESTIMATE, the budget is a config-audit heuristic (no
+ * documented agent allotment) anchored on a conservative 200k window, and the
+ * evidence discloses all of that. The cap, budget, and enumerate-and-measure step
+ * live in `lib/agent-listing-budget.mjs` — AGT only constructs the finding.
+ *
+ * Zero external dependencies.
+ */
+
+import { finding, scannerResult } from './lib/output.mjs';
+import { SEVERITY } from './lib/severity.mjs';
+import {
+  AGGREGATE_BUDGET_TOKENS,
+  BUDGET_CALIBRATION_NOTE,
+  measureActiveAgentListing,
+} from './lib/agent-listing-budget.mjs';
+
+const SCANNER = 'AGT';
+
+/**
+ * Main scanner entry point.
+ *
+ * @param {string} _targetPath unused (agent listing is HOME-scoped)
+ * @param {object} _discovery unused (ignores project discovery)
+ */
+export async function scan(_targetPath, _discovery) {
+  const start = Date.now();
+  const findings = [];
+
+  const { aggregate } = await measureActiveAgentListing();
+
+  if (aggregate.overBudget) {
+    findings.push(finding({
+      scanner: SCANNER,
+      severity: SEVERITY.low,
+      title: 'Aggregate agent listing may exceed the always-loaded budget',
+      description:
+        `The ${aggregate.scanned} active agents carry about ${aggregate.aggregateTokens} tokens of ` +
+        'name+description text that Claude Code injects every turn so it knows which subagents it can ' +
+        `delegate to — above the ${AGGREGATE_BUDGET_TOKENS}-token budget this scanner anchors on a 200k ` +
+        'context window. Every one of those tokens is re-sent on every turn whether or not you delegate. ' +
+        'Note: unlike the skill listing, the agent-listing always-loaded mechanism is inferred (not ' +
+        'documented), so this is an upper-bound estimate (see evidence).',
+      evidence:
+        `active_agents_scanned=${aggregate.scanned}; description_chars=${aggregate.aggregateChars}; ` +
+        `description_tokens~${aggregate.aggregateTokens}; budget@200k=${AGGREGATE_BUDGET_TOKENS} tok; ` +
+        `over_by~${aggregate.overBy} tok - ${BUDGET_CALIBRATION_NOTE}`,
+      recommendation:
+        'Shrink the always-loaded agent listing: disable plugins whose agents you do not use (the whole ' +
+        'agent block leaves the listing), remove dead user agents from ~/.claude/agents/, and trim long ' +
+        'agent descriptions toward their trigger phrases.',
+      category: 'token-efficiency',
+    }));
+  }
+
+  return scannerResult(SCANNER, 'ok', findings, aggregate.scanned, Date.now() - start);
+}

scanners/lib/agent-listing-budget.mjs

@@ -0,0 +1,123 @@
+/**
+ * Agent-listing budget — single source of truth for the AGT scanner.
+ *
+ * Claude Code injects a listing of every active agent's name+description into the
+ * system prompt so the model knows which subagents it can delegate to. With many
+ * installed agents that listing is a large always-loaded cost: re-sent every turn
+ * whether or not a delegation actually happens.
+ *
+ * CRUCIAL HONESTY CAVEAT — this is why AGT differs from SKL. Unlike the skill
+ * listing (documented ~2% allotment, CC 2.1.32; verified 1,536-char truncation
+ * cap, CC 2.1.105), the agent-listing mechanism is NOT documented — agents are
+ * absent from Claude Code's published context breakdown. Therefore:
+ *   - "always-loaded" is INFERRED (reasoned from the skill analogue + agents'
+ *     absence from the deferred/on-demand list), not documented.
+ *   - the token figure is an UPPER-BOUND ESTIMATE, not measured telemetry.
+ *   - there is no documented per-listing allotment, so the aggregate budget is a
+ *     config-audit heuristic anchored — by analogy to the skill listing — on a
+ *     conservative 200k window, and the evidence says so loudly.
+ *   - there is no verified per-description truncation cap, so (unlike CA-SKL-001)
+ *     each description contributes its FULL length to the aggregate.
+ *
+ * Zero external dependencies.
+ */
+
+import { estimateTokens, enumeratePlugins, enumerateAgents } from './active-config-reader.mjs';
+import { readTextFile } from './file-discovery.mjs';
+import { parseFrontmatter } from './yaml-parser.mjs';
+import { CONTEXT_WINDOW_ANCHOR, LARGE_CONTEXT_WINDOW, withCommas } from './context-window.mjs';
+
+// Heuristic budget by analogy to the skill listing's documented ~2% allotment.
+// Agents have NO documented allotment of their own — disclosed loudly in
+// BUDGET_CALIBRATION_NOTE so the number is never mistaken for a CC guarantee.
+export const BUDGET_FRACTION = 0.02;
+export const AGGREGATE_BUDGET_TOKENS = Math.round(BUDGET_FRACTION * CONTEXT_WINDOW_ANCHOR); // 4000
+export const LARGE_CONTEXT_BUDGET_TOKENS = Math.round(BUDGET_FRACTION * LARGE_CONTEXT_WINDOW); // 20000
+export { CONTEXT_WINDOW_ANCHOR, LARGE_CONTEXT_WINDOW, withCommas };
+
+// The honest framing required because (a) the mechanism is inferred and (b) the
+// budget depends on a context window we cannot observe. Appended to overflow evidence.
+export const BUDGET_CALIBRATION_NOTE =
+  'the agent-listing always-loaded mechanism is INFERRED, not documented (agents are absent from ' +
+  "Claude Code's published context breakdown), so this token figure is an UPPER-BOUND ESTIMATE, not " +
+  'measured telemetry. unlike the skill listing there is no documented per-listing allotment, so this ' +
+  'budget is a config-audit heuristic anchored on a conservative 200k window; at ' +
+  `${withCommas(LARGE_CONTEXT_WINDOW)} context the budget is ~${withCommas(LARGE_CONTEXT_BUDGET_TOKENS)} ` +
+  'tok and you are likely within it';
+
+/**
+ * @typedef {object} AgentBudgetAssessment
+ * @property {number} scanned          - number of agent descriptions assessed
+ * @property {number} aggregateChars   - sum of description lengths (no cap; no verified truncation)
+ * @property {number} aggregateTokens  - estimateTokens(aggregateChars, 'markdown')
+ * @property {number} budgetTokens     - AGGREGATE_BUDGET_TOKENS (the 200k-anchored heuristic)
+ * @property {boolean} overBudget      - aggregateTokens strictly greater than budgetTokens
+ * @property {number} overBy           - tokens over budget (0 when not over)
+ */
+
+/**
+ * Pure aggregate-budget assessment. Each description contributes its full length:
+ * agents have no verified truncation cap, so nothing is dropped from the estimate.
+ *
+ * @param {number[]} descLengths - one entry per active agent (description char count)
+ * @returns {AgentBudgetAssessment}
+ */
+export function assessAgentListingBudget(descLengths) {
+  let aggregateChars = 0;
+  for (const len of descLengths) {
+    const safe = (typeof len === 'number' && Number.isFinite(len) && len > 0) ? len : 0;
+    aggregateChars += safe;
+  }
+  const aggregateTokens = estimateTokens(aggregateChars, 'markdown');
+  const overBudget = aggregateTokens > AGGREGATE_BUDGET_TOKENS;
+  return {
+    scanned: descLengths.length,
+    aggregateChars,
+    aggregateTokens,
+    budgetTokens: AGGREGATE_BUDGET_TOKENS,
+    overBudget,
+    overBy: overBudget ? aggregateTokens - AGGREGATE_BUDGET_TOKENS : 0,
+  };
+}
+
+/**
+ * @typedef {object} ActiveAgentEntry
+ * @property {string} name
+ * @property {'user'|'plugin'} source
+ * @property {string|null} pluginName
+ * @property {string} path
+ * @property {number} descLength
+ */
+
+/**
+ * Enumerate every active agent (user + plugin) and measure the listing budget.
+ * HOME-scoped (mirrors the skill listing): resolves ~/.claude via process.env.HOME
+ * and excludes project-scoped agents — those load only inside their own repo.
+ * Callers that run under test MUST override HOME (runScannerWithHome pattern).
+ *
+ * @returns {Promise<{ agents: ActiveAgentEntry[], aggregate: AgentBudgetAssessment }>}
+ */
+export async function measureActiveAgentListing() {
+  const plugins = await enumeratePlugins();
+  // enumerateAgents yields project + user + plugin; drop project (repo-local).
+  const allAgents = await enumerateAgents('', plugins);
+
+  const agents = [];
+  for (const agent of allAgents) {
+    if (!agent || agent.source === 'project' || typeof agent.path !== 'string') continue;
+    const content = await readTextFile(agent.path);
+    if (!content) continue;
+    const fm = parseFrontmatter(content)?.frontmatter || null;
+    const desc = (fm && typeof fm.description === 'string') ? fm.description : '';
+    agents.push({
+      name: agent.name,
+      source: agent.source,
+      pluginName: agent.pluginName,
+      path: agent.path,
+      descLength: desc.length,
+    });
+  }
+
+  const aggregate = assessAgentListingBudget(agents.map((a) => a.descLength));
+  return { agents, aggregate };
+}

scanners/lib/scoring.mjs

@@ -166,6 +166,7 @@ const SCANNER_AREA_MAP = {
   TOK: 'Token Efficiency',
   CPS: 'Token Efficiency',
   SKL: 'Token Efficiency',
+  AGT: 'Token Efficiency',
   DIS: 'Settings',
   COL: 'Plugin Hygiene',
   OST: 'Settings',

scanners/scan-orchestrator.mjs

@@ -29,6 +29,7 @@ import { scan as scanCachePrefix } from './cache-prefix-scanner.mjs';
 import { scan as scanDisabledInSchema } from './disabled-in-schema-scanner.mjs';
 import { scan as scanCollision } from './collision-scanner.mjs';
 import { scan as scanSkillListing } from './skill-listing-scanner.mjs';
+import { scan as scanAgentListing } from './agent-listing-scanner.mjs';
 import { scan as scanOutputStyle } from './output-style-scanner.mjs';
 import { scan as scanOptimizationLens } from './optimization-lens-scanner.mjs';
 
@@ -66,6 +67,7 @@ const SCANNERS = [
   { name: 'DIS', fn: scanDisabledInSchema, label: 'Disabled-In-Schema' },
   { name: 'COL', fn: scanCollision, label: 'Plugin Skill Collision' },
   { name: 'SKL', fn: scanSkillListing, label: 'Skill-Listing Budget' },
+  { name: 'AGT', fn: scanAgentListing, label: 'Agent-Listing Budget' },
   { name: 'OST', fn: scanOutputStyle, label: 'Output-Style Validation' },
   { name: 'OPT', fn: scanOptimizationLens, label: 'Optimization Lens' },
 ];