config-audit/scanners/agent-listing-scanner.mjs

/**
 * 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  per-agent description over the soft bloat cap (low, advisory)
 *   CA-AGT-NNN  aggregate agent-listing estimate exceeds the listing budget (low)
 *
 * Per-agent advisories are emitted FIRST (mirroring SKL 001→002). They are a
 * soft bloat heuristic (the 500-char threshold TOK pattern F uses for SKILL.md
 * descriptions), NOT a truncation finding — agents have no verified per-
 * description cap, so nothing is dropped; the description is simply re-sent in
 * full every turn.
 *
 * 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,
  PER_AGENT_DESC_SOFT_CAP,
  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 { agents, aggregate } = await measureActiveAgentListing();

  // Per-agent advisory (emitted FIRST so the common "long agent + aggregate"
  // case reads 001=per-agent, 002=aggregate, mirroring SKL). This is a soft
  // heuristic, NOT a truncation finding — agents have no verified per-description
  // cap, so the framing is "this is large and re-sent every turn", never "Claude
  // Code drops the tail".
  for (const agent of agents) {
    if (agent.descLength <= PER_AGENT_DESC_SOFT_CAP) continue;

    const sourceLabel = agent.source === 'plugin'
      ? `plugin:${agent.pluginName}`
      : 'user';

    findings.push(finding({
      scanner: SCANNER,
      code: 'description-bloat',
      severity: SEVERITY.low,
      title: 'Agent description is long (re-sent every turn in the always-loaded listing)',
      description:
        `Agent "${agent.name}" (${sourceLabel}) has a description of ${agent.descLength} ` +
        `characters (>${PER_AGENT_DESC_SOFT_CAP}). Claude Code injects every active agent's ` +
        'name+description into the agent listing on every turn so it knows which subagents it ' +
        'can delegate to, so every character of this description re-enters context each turn ' +
        'whether or not you delegate. Unlike the skill listing there is no verified ' +
        'per-description cap, so nothing is dropped — this is a bloat advisory, not a ' +
        'hard-cap finding.',
      file: agent.path,
      evidence:
        `description_chars=${agent.descLength}; soft_cap=${PER_AGENT_DESC_SOFT_CAP} ` +
        `(heuristic, same bloat threshold TOK pattern F uses for SKILL.md descriptions; agents ` +
        `have NO verified per-description cap); agent="${agent.name}"; source=${sourceLabel}`,
      recommendation:
        'Trim the description toward its trigger phrases / "when to use this agent" cues and move ' +
        'long examples into the agent body, or disable the plugin if you never delegate to this ' +
        'agent (the whole agent block then leaves the always-loaded listing).',
      category: 'token-efficiency',
    }));
  }

  if (aggregate.overBudget) {
    findings.push(finding({
      scanner: SCANNER,
      code: 'aggregate-listing-budget',
      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);
}