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
|
|
@ -1,12 +1,13 @@
|
|||
/**
|
||||
* v5.6 C added the OST (Output-Style Validation) scanner — a 14th orchestrated
|
||||
* scanner. The frozen v5.0.0 byte-equal baselines predate it (13 scanners), so
|
||||
* this strips the additive OST scanner entry before comparison, the same way
|
||||
* strip-hotspot-load-pattern.mjs handles B2's additive hotspot fields. Stripping
|
||||
* (rather than re-seeding the frozen snapshots) keeps the strongest invariant:
|
||||
* the ORIGINAL 13 scanners still emit byte-identical output, and the frozen
|
||||
* snapshots stay free of post-v5.0.0 drift (the hotspot triple, ancestor token
|
||||
* counts) that re-seeding would bake in.
|
||||
* Post-v5.0.0 additive scanners that the frozen v5.0.0 byte-equal baselines
|
||||
* predate: OST (Output-Style Validation, v5.6 C), OPT (Optimization Lens, v5.7),
|
||||
* and AGT (Agent-Listing Budget, v5.9 B1). The baselines froze the original
|
||||
* scanner set, so this strips these additive scanner entries before comparison,
|
||||
* the same way strip-hotspot-load-pattern.mjs handles B2's additive hotspot
|
||||
* fields. Stripping (rather than re-seeding the frozen snapshots) keeps the
|
||||
* strongest invariant: the ORIGINAL scanners still emit byte-identical output,
|
||||
* and the frozen snapshots stay free of post-v5.0.0 drift (the hotspot triple,
|
||||
* ancestor token counts) that re-seeding would bake in.
|
||||
*
|
||||
* Removing a zero-finding scanner entry only moves `aggregate.scanners_ok`
|
||||
* (OST is always status 'ok' and emits nothing on the deterministic fixture, so
|
||||
|
|
@ -17,7 +18,7 @@
|
|||
* return stripAddedScanners(stripHotspotLoadPattern(out));
|
||||
*/
|
||||
|
||||
const ADDED_SCANNERS = new Set(['OST', 'OPT']);
|
||||
const ADDED_SCANNERS = new Set(['OST', 'OPT', 'AGT']);
|
||||
|
||||
function stripFromEnvelope(env) {
|
||||
if (!env || typeof env !== 'object' || !Array.isArray(env.scanners)) return;
|
||||
|
|
@ -58,5 +59,5 @@ export function stripAddedScanners(payload) {
|
|||
*/
|
||||
export function stripAddedScannerStderr(text) {
|
||||
if (typeof text !== 'string') return text;
|
||||
return text.replace(/^[ \t]*\[(OST|OPT)\][^\n]*\n/gm, '');
|
||||
return text.replace(/^[ \t]*\[(OST|OPT|AGT)\][^\n]*\n/gm, '');
|
||||
}
|
||||
|
|
|
|||
174
tests/scanners/agent-listing-scanner.test.mjs
Normal file
174
tests/scanners/agent-listing-scanner.test.mjs
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
import { describe, it } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { join } from 'node:path';
|
||||
import { mkdir, writeFile, rm } from 'node:fs/promises';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { resetCounter } from '../../scanners/lib/output.mjs';
|
||||
import { scan } from '../../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 the model knows which subagents it can delegate to. With ~100
|
||||
* agents that listing is a large always-loaded cost. UNLIKE the skill listing,
|
||||
* the agent-listing mechanism is NOT documented (agents are absent from CC's
|
||||
* deferred / always-loaded context breakdown), so AGT findings are an INFERRED
|
||||
* upper-bound estimate, not a verified truncation like SKL-001. The aggregate
|
||||
* budget is a config-audit heuristic anchored on a conservative 200k window.
|
||||
*
|
||||
* Token heuristic mirrors estimateTokens('markdown'): ceil(chars/4).
|
||||
* 16 agents * 1000 desc-chars = 16000 chars -> 4000 tok == budget (NOT over).
|
||||
* 17 agents * 1000 desc-chars = 17000 chars -> 4250 tok > budget (over).
|
||||
*/
|
||||
const AGGREGATE_BUDGET_TOKENS = 4000; // heuristic: 0.02 * 200_000 (anchored, disclosed)
|
||||
|
||||
function uniqueDir(suffix) {
|
||||
return join(tmpdir(), `config-audit-agt-${suffix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* The AGT scanner enumerates active agents via process.env.HOME. Tests must
|
||||
* override HOME, run, restore — never rely on the developer's real ~/.claude.
|
||||
*/
|
||||
async function runScannerWithHome(home) {
|
||||
resetCounter();
|
||||
const original = process.env.HOME;
|
||||
process.env.HOME = home;
|
||||
try {
|
||||
return await scan('/unused', { files: [] });
|
||||
} finally {
|
||||
process.env.HOME = original;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write one user agent (name + description of `descLen` chars) into a HOME. */
|
||||
async function addUserAgent(home, name, descLen) {
|
||||
const dir = join(home, '.claude', 'agents');
|
||||
await mkdir(dir, { recursive: true });
|
||||
const desc = 'a'.repeat(descLen);
|
||||
await writeFile(
|
||||
join(dir, `${name}.md`),
|
||||
`---\nname: ${name}\ndescription: ${desc}\n---\nYou are the ${name} agent. Body of the agent prompt.\n`,
|
||||
);
|
||||
}
|
||||
|
||||
/** Build a fake HOME with `count` user agents, each description `descLen` chars. */
|
||||
async function homeWithNUserAgents(count, descLen, prefix = 'agg') {
|
||||
const home = uniqueDir(`${prefix}-${count}x${descLen}`);
|
||||
for (let i = 0; i < count; i++) {
|
||||
await addUserAgent(home, `${prefix}${i}`, descLen);
|
||||
}
|
||||
return home;
|
||||
}
|
||||
|
||||
const findAggregate = (findings) => findings.find(f => /agent listing/i.test(f.title));
|
||||
|
||||
describe('AGT scanner — basic structure', () => {
|
||||
it('reports scanner prefix AGT', async () => {
|
||||
const home = uniqueDir('empty');
|
||||
try {
|
||||
await mkdir(join(home, '.claude'), { recursive: true });
|
||||
const result = await runScannerWithHome(home);
|
||||
assert.equal(result.scanner, 'AGT');
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('finding IDs match CA-AGT-NNN pattern', async () => {
|
||||
const home = await homeWithNUserAgents(17, 1000);
|
||||
try {
|
||||
const result = await runScannerWithHome(home);
|
||||
for (const f of result.findings) assert.match(f.id, /^CA-AGT-\d{3}$/);
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('AGT scanner — aggregate always-loaded budget', () => {
|
||||
it('fires a low-severity finding when the agent listing exceeds the 200k-anchored budget', async () => {
|
||||
const home = await homeWithNUserAgents(17, 1000); // 17000 chars -> ~4250 tok > 4000
|
||||
try {
|
||||
const result = await runScannerWithHome(home);
|
||||
const agg = findAggregate(result.findings);
|
||||
assert.ok(agg, `expected an aggregate finding; got: ${result.findings.map(f => f.title).join(' | ')}`);
|
||||
assert.equal(agg.severity, 'low', `aggregate should be low severity, got ${agg.severity}`);
|
||||
assert.match(agg.id, /^CA-AGT-\d{3}$/);
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('does NOT fire when only a few small agents are active', async () => {
|
||||
const home = await homeWithNUserAgents(3, 1000); // 3000 chars -> 750 tok < 4000
|
||||
try {
|
||||
const result = await runScannerWithHome(home);
|
||||
assert.equal(findAggregate(result.findings), undefined,
|
||||
`expected no aggregate finding; got: ${result.findings.map(f => f.title).join(' | ')}`);
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('treats the budget as a strict boundary: 16x1000 (at budget) no fire, 17x1000 (over) fires', async () => {
|
||||
const atBudget = await homeWithNUserAgents(16, 1000, 'at'); // 16000 chars -> 4000 tok == budget
|
||||
try {
|
||||
const result = await runScannerWithHome(atBudget);
|
||||
assert.equal(findAggregate(result.findings), undefined,
|
||||
'aggregate exactly at the budget must not fire (strictly-greater rule)');
|
||||
} finally {
|
||||
await rm(atBudget, { recursive: true, force: true });
|
||||
}
|
||||
const overBudget = await homeWithNUserAgents(17, 1000, 'over'); // 17000 chars -> 4250 tok
|
||||
try {
|
||||
const result = await runScannerWithHome(overBudget);
|
||||
assert.ok(findAggregate(result.findings), 'aggregate one step over the budget must fire');
|
||||
} finally {
|
||||
await rm(overBudget, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('DISCLOSES the inferred mechanism + upper-bound estimate + anchor (intellectual honesty)', async () => {
|
||||
const home = await homeWithNUserAgents(17, 1000);
|
||||
try {
|
||||
const result = await runScannerWithHome(home);
|
||||
const agg = findAggregate(result.findings);
|
||||
assert.ok(agg, 'expected an aggregate finding');
|
||||
const ev = String(agg.evidence);
|
||||
assert.match(ev, /infer/i, 'evidence must disclose the always-loaded mechanism is INFERRED, not documented');
|
||||
assert.match(ev, /estimate|upper.?bound/i, 'evidence must flag the figure as an estimate / upper bound');
|
||||
assert.match(ev, new RegExp(String(AGGREGATE_BUDGET_TOKENS)), 'evidence must state the budget');
|
||||
assert.match(ev, /200k/, 'evidence must anchor the budget on a 200k window');
|
||||
assert.match(ev, /1,000,000|1M|20,000/, 'evidence must note the 1M-context scaling');
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('recommends the reduction levers (disable unused plugins / trim descriptions)', async () => {
|
||||
const home = await homeWithNUserAgents(17, 1000);
|
||||
try {
|
||||
const result = await runScannerWithHome(home);
|
||||
const agg = findAggregate(result.findings);
|
||||
assert.ok(agg, 'expected an aggregate finding to carry remediation');
|
||||
const rec = String(agg.recommendation);
|
||||
assert.match(rec, /disable|plugin/i, 'recommendation should mention disabling unused plugins');
|
||||
assert.match(rec, /trim|description/i, 'recommendation should mention trimming descriptions');
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('an empty HOME (no agents) yields zero findings', async () => {
|
||||
const home = uniqueDir('noagents');
|
||||
try {
|
||||
await mkdir(join(home, '.claude'), { recursive: true });
|
||||
const result = await runScannerWithHome(home);
|
||||
assert.equal(result.findings.length, 0);
|
||||
} finally {
|
||||
await rm(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
|
|
@ -103,7 +103,7 @@ describe('scan-orchestrator humanizer wiring (Step 5)', () => {
|
|||
assert.ok(actual.meta, 'meta present');
|
||||
assert.ok(Array.isArray(actual.scanners), 'scanners array present');
|
||||
assert.ok(actual.aggregate, 'aggregate present');
|
||||
assert.equal(actual.scanners.length, 15, 'all 15 scanners present');
|
||||
assert.equal(actual.scanners.length, 16, 'all 16 scanners present');
|
||||
});
|
||||
|
||||
it('preserves scanner shape (scanner/status/findings/counts)', async () => {
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
{
|
||||
"kind": "text",
|
||||
"payload": "`[CML] CLAUDE.md Linter`: 1 finding(s) (0ms)\n `[SET] Settings Validator`: 0 finding(s) (0ms)\n `[HKV] Hook Validator`: 0 finding(s) (0ms)\n `[RUL] Rules Validator`: 0 finding(s) (0ms)\n `[MCP] MCP Config Validator`: 0 finding(s) (0ms)\n `[IMP] Import Resolver`: 0 finding(s) (0ms)\n `[CNF] Conflict Detector`: 0 finding(s) (0ms)\n `[GAP] Feature Gap Scanner`: 17 finding(s) (0ms)\n `[TOK] Token Hotspots`: 1 finding(s) (0ms)\n `[CPS] Cache-Prefix Stability`: 0 finding(s) (0ms)\n `[DIS] Disabled-In-Schema`: 0 finding(s) (0ms)\n `[COL] Plugin Skill Collision`: 0 finding(s) (0ms)\n `[SKL] Skill-Listing Budget`: 0 finding(s) (0ms)\n `[OST] Output-Style Validation`: 0 finding(s) (0ms)\n `[OPT] Optimization Lens`: 0 finding(s) (0ms)\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n Configuration health\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n Health: A (98/100) — Healthy setup, only minor polish needed\n 9 areas reviewed\n\n Area scores\n ───────────\n `CLAUDE.md` ........... A (90) `Settings` ............ A (100)\n `Hooks` ............... A (100) `Rules` ............... A (100)\n `MCP` ................. A (100) `Imports` ............. A (100)\n `Conflicts` ........... A (100) `Token Efficiency` .... A (90)\n `Plugin Hygiene` ...... A (100)\n\n 17 ways you could get more out of Claude Code — see /config-audit feature-gap\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
"payload": "`[CML] CLAUDE.md Linter`: 1 finding(s) (0ms)\n `[SET] Settings Validator`: 0 finding(s) (0ms)\n `[HKV] Hook Validator`: 0 finding(s) (0ms)\n `[RUL] Rules Validator`: 0 finding(s) (0ms)\n `[MCP] MCP Config Validator`: 0 finding(s) (0ms)\n `[IMP] Import Resolver`: 0 finding(s) (0ms)\n `[CNF] Conflict Detector`: 0 finding(s) (0ms)\n `[GAP] Feature Gap Scanner`: 17 finding(s) (0ms)\n `[TOK] Token Hotspots`: 1 finding(s) (0ms)\n `[CPS] Cache-Prefix Stability`: 0 finding(s) (0ms)\n `[DIS] Disabled-In-Schema`: 0 finding(s) (0ms)\n `[COL] Plugin Skill Collision`: 0 finding(s) (0ms)\n `[SKL] Skill-Listing Budget`: 0 finding(s) (0ms)\n `[AGT] Agent-Listing Budget`: 0 finding(s) (0ms)\n `[OST] Output-Style Validation`: 0 finding(s) (0ms)\n `[OPT] Optimization Lens`: 0 finding(s) (0ms)\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n Configuration health\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n Health: A (98/100) — Healthy setup, only minor polish needed\n 9 areas reviewed\n\n Area scores\n ───────────\n `CLAUDE.md` ........... A (90) `Settings` ............ A (100)\n `Hooks` ............... A (100) `Rules` ............... A (100)\n `MCP` ................. A (100) `Imports` ............. A (100)\n `Conflicts` ........... A (100) `Token Efficiency` .... A (90)\n `Plugin Hygiene` ...... A (100)\n\n 17 ways you could get more out of Claude Code — see /config-audit feature-gap\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -569,6 +569,20 @@
|
|||
"info": 0
|
||||
}
|
||||
},
|
||||
{
|
||||
"scanner": "AGT",
|
||||
"status": "ok",
|
||||
"files_scanned": 0,
|
||||
"duration_ms": 0,
|
||||
"findings": [],
|
||||
"counts": {
|
||||
"critical": 0,
|
||||
"high": 0,
|
||||
"medium": 0,
|
||||
"low": 0,
|
||||
"info": 0
|
||||
}
|
||||
},
|
||||
{
|
||||
"scanner": "OST",
|
||||
"status": "ok",
|
||||
|
|
@ -610,7 +624,7 @@
|
|||
"risk_score": 11,
|
||||
"risk_band": "Medium",
|
||||
"verdict": "PASS",
|
||||
"scanners_ok": 14,
|
||||
"scanners_ok": 15,
|
||||
"scanners_error": 0,
|
||||
"scanners_skipped": 1
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue