Kjell Tore Guttormsen
fcfb2979ef
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>
71 lines
3.2 KiB
JavaScript
71 lines
3.2 KiB
JavaScript
/**
|
|
* 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);
|
|
}
|