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>
This commit is contained in:
parent
759daa7201
commit
fcfb2979ef
9 changed files with 399 additions and 13 deletions
71
scanners/agent-listing-scanner.mjs
Normal file
71
scanners/agent-listing-scanner.mjs
Normal file
|
|
@ -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);
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue