Opus High Review Response: Token Optimization Plan

Meta

• Reviewer: Claude Opus 4.6 (1M context)
• Data: 27 marzo 2026
• Documenti revisionati: opus-high-token-optimization-review.md, opus-high-operational-plan.md
• Codebase verificata: /home/ubuntu/Documents/Progetti Interni/BeDefended Agentic Pentesting Platform/bd_app/
• Metodo: esplorazione diretta del repository con lettura dei file, misura delle dimensioni, analisi dei meccanismi di loading, verifica incrociata delle evidenze

---

1. Approved As-Is

Workstream 0: Misurazione Prima di Cambiare

APPROVATO senza riserve.

Il principio "misura prima di ottimizzare" e' metodologicamente corretto. Lo schema JSONL e' ben disegnato. La tassonomia di classificazione run (useful, rate_limited_immediate, rate_limited_midrun, dead_run_short, error) e' completa.

Aggiunta raccomandata: includere prompt_supporting_files_count e prompt_supporting_files_bytes nel record metriche per misurare l'impatto reale del lazy loading una volta implementato.

Workstream 6: Workspace & Search Hygiene

APPROVATO senza riserve.

Creare .rgignore per escludere .claude/worktrees/, node_modules/, payloads/, log runtime e' a rischio zero e previene inquinamento accidentale del contesto. Implementabile in meno di un'ora.

Oltre a .rgignore, verificare se la versione di Claude Code in uso supporta .claudeignore per prevenire che payloads/ (145MB), .claude/worktrees/ (102MB) e ingest/data/ (25MB) entrino nel contesto tool.

Workstream 1: Loop Hardening

Il singleton lock, il rate-limit sentinel globale, la classificazione dead-run e il control plane unificato sono tutti requisiti di design corretti per il BB loop.

Le specifiche nel piano sono solide: - Lock atomico globale con recovery di lock stale - Cooldown progressivo (15min -> 30min -> blocco fino a reset reale) - Sessione morta = <=3 turni o <90s o rate limit immediato - Backoff reale, non restart ogni 10 secondi

La logica di rate-limit parsing in scripts/pentest-autoresume.py (14+ pattern regex, parse wait time, persistence su JSON) e' riusabile direttamente nel BB loop senza riscriverla.

---

2. Approved With Conditions

Workstream 2: Context Slimming & Prompt Capsules

APPROVATO con quattro condizioni.

Condizione 1: Decomporre skill-boilerplate.md per primo, non CLAUDE.md

skill-boilerplate.md a 61.4KB e' caricato da ogni subprocess di test. Contiene sezioni con profili di necessita' molto diversi:

Sezione	Dimensione stimata	Necessita'
PATH isolation	~2KB	SEMPRE
Stealth mode check	~3KB	SEMPRE
Structured logging	~2KB	SEMPRE
Kill switch (45min/500req)	~2KB	SEMPRE
Token counting	~1KB	SEMPRE
Auth setup	~3KB	SEMPRE
Proxy rotation	~4KB	SOLO SE PROXY
Scope routing	~5KB	SKILL-SPECIFIC
Advanced stealth config	~8KB	SOLO SE STEALTH
Rate-limit handler reference	~15KB+	LAZY (on first 429)

Proposta di split:

• skill-boilerplate-core.md (~15KB): PATH, stealth check, logging, kill switch, token counting, auth
• skill-boilerplate-stealth.md (~8KB): configurazione stealth avanzata, caricato solo se stealth mode attivo
• skill-boilerplate-ratelimit.md (~15KB): handler rate-limit completo, caricato on-demand al primo 429

Impatto: risparmio di ~30-45K token per subprocess quando stealth e' off o rate limits non scattano. Su 36 subprocessi: 1M-1.6M token risparmiati per pentest completo. Questo e' il singolo cambiamento con ROI piu' alto dell'intero piano.

CLAUDE.md (26KB) va toccato solo con trim leggero di sezioni chiaramente verbose. E' gia' snello e ben organizzato. Ristrutturarlo rischia di rompere riferimenti impliciti usati dalle skill.

Condizione 2: Rispettare il meccanismo supporting-files: esistente

Il piano propone "router + micro-pack" ma non riconosce che supporting-files: nel YAML frontmatter gia' fornisce loading selettivo per skill. Il fix reale e':

1. Rendere il routing --scope piu' stretto: quando viene passato --scope sqli, la skill dovrebbe dichiarare nel frontmatter solo i file rilevanti per SQLi, non tutti i sottotipi
2. Splittare i SKILL.md monolitici in sezioni scope-specific caricabili condizionalmente
3. Non reinventare un nuovo meccanismo di loading — estendere quello esistente

Concretamente per test-injection, invece di un unico SKILL.md da 150.5KB con 8 supporting files:

test-injection/          (attuale: 1 SKILL.md + 8 supporting)
  -> test-injection-sqli/   (SKILL.md ~30KB + 2 supporting: knowledge-sqli, cheatsheet-sqli)
  -> test-injection-xss/    (SKILL.md ~25KB + 2 supporting: knowledge-xss, cheatsheet-xss)
  -> test-injection-ssti/   (SKILL.md ~20KB + 2 supporting: knowledge-ssti, cheatsheet-ssti)
  -> test-injection-xxe/    (SKILL.md ~15KB + 1 supporting: knowledge-xxe)
  -> test-injection-cmdi/   (SKILL.md ~15KB + 2 supporting: knowledge-cmdi, cheatsheet-cmdi)

Il router originale test-injection diventa un dispatcher leggero (~5KB) che chiama la sub-skill corretta in base allo scope.

Condizione 3: Prioritizzare test-injection come proof of concept

A 150.5KB (solo SKILL.md) + 148KB (supporting files dichiarati), e' la skill singola piu' costosa. Decomporla per prima: - valida l'approccio - massimizza il risparmio iniziale - produce un template riusabile per le altre decomposizioni

Condizione 4: Non toccare CLAUDE.md in modo aggressivo

CLAUDE.md (26KB) e' caricato automaticamente da Claude Code in ogni sessione. Il contenuto e' gia' prevalentemente invarianti, safety e routing. Il piano propone "distillarlo", ma spostare dettagli in helper file rischia di rompere riferimenti impliciti. Solo trim di sezioni chiaramente verbose; nessuna ristrutturazione.

Workstream 3: Skinny Context Before Fork

APPROVATO con una correzione.

Il meccanismo di dispatch (claude -p "Run /test-injection $TARGET --scope sqli") gia' passa una stringa prompt compatta. I subagent non ereditano il contesto conversazionale del parent — partono freschi. Il costo reale ereditato e':

1. CLAUDE.md (26KB): architetturale, difficile da evitare — Claude Code lo carica automaticamente
2. supporting-files della skill invocata: questo e' il vero target di ottimizzazione
3. context.json letto dal boilerplate: gia' compatto (fingerprint, tech stack, auth, endpoints)

La proposta run-brief (runtime/dispatch-brief.json) aggiunge valore principalmente per stato cross-sessione: prior findings, prior blockers, next steps. Va implementata come capsule opzionale, ma senza over-engineering.

Correzione: il piano descrive il problema del "contesto grasso ereditato" come se fosse grave. In realta' il dispatch via claude -p gia' isola i subagent. Il costo che va attaccato non e' il "context: fork" generico, ma specificamente le dimensioni dei file caricati nella nuova sessione (CLAUDE.md + supporting-files + boilerplate on-demand).

Workstream 4: Differential Rediscovery

APPROVATO come specifica di design

La logica proposta e' corretta: - Freshness manifest (homepage hash, robots/sitemap hash, JS manifest hash, tech stack fingerprint, auth surface fingerprint, endpoint set hash) - Delta check leggero all'inizio di ogni ritorno - Full rediscovery se delta supera soglia, reuse baseline se non cambia

Trigger aggiuntivi mancanti dal piano:

Trigger	Razionale
Nuovi metodi HTTP su endpoint esistenti (PUT/PATCH/DELETE)	Superficie di attacco ampliata
Nuovi response header (CORS changes, nuovi auth headers)	Cambio di policy o framework
Cambio formato errori (diversa versione framework)	Nuova tech stack sotto lo stesso hostname
Endpoint WebSocket	Superficie completamente diversa
Force full rediscovery ogni N cicli	Safety net contro false negative

Il fallback periodico (force full rediscovery ogni N cicli, indipendentemente dal delta) e' critico per non accumulare debt di copertura su programmi con cambiamenti sottili non catturati dal manifest.

Workstream 5: Proxy Analyzer

APPROVATO con reframing.

Va costruito con:

• Novelty gate ON di default
• Semantic dedup (method + normalized route + param names + status bucket + response content-type + response shape hash)
• auto_analyze=False come default, opt-in per sessione
• Analisi manuale single-request sempre disponibile
• Threshold recall-oriented: mai scartare 4xx/5xx interessanti, nuove route, nuovi content-type, nuovi auth patterns, reflection, token leakage, redirect params, callback/webhook, GraphQL, upload, admin/internal

Workstream 7: Model Routing

APPROVATO solo Lane A (nessun downgrade di modello). Lane B richiede shadow validation.

Lane A (nessun downgrade) e' safe: nessun cambio di modello, nessun rischio.

Lane B (routing di task deterministici su modello piu' economico) ha rischio reale: fingerprinting e policy parsing possono far emergere segnali inattesi che modelli piu' economici mancano. Shadow mode con parity gate e' l'approccio corretto, ma va deferrito a dopo che i Workstream 0-6 sono validati.

Task candidati per Lane B (dopo shadow validation): - Clustering di endpoint equivalenti - Normalizzazione route - Hash di response body - Parsing di sitemap/robots - Diff di JS manifest

Task dove Opus resta mandatory: - Exploit reasoning - Stuck resolution - Verification - Chain discovery - Final finding acceptance - Qualsiasi task dove un falso negativo = finding perso

---

3. Rischi e Blind Spot

Rischio 1: La decomposizione delle skill puo' frammentare la metodologia

Severita': MODERATA

Quando test-injection e' una skill monolitica, l'agente vede tutti i tipi di injection simultaneamente e puo' individuare segnali cross-type: - Reflection XSS che suggerisce SSTI - Error message da SQLi che rivela path per CMDi - Behaviour di encoding che indica sia XSS che SQLi blind - Response differenziale che suggerisce NoSQLi dove si stava testando SQLi

Decomporre in micro-skill con contesto isolato perde questa cross-pollination.

Mitigazione obbligatoria: ogni micro-skill deve includere una sezione "signal forwarding" nel preamble:

## Cross-Type Signal Forwarding
Se durante il test SQLi osservi uno di questi indicatori:
- Template syntax in error messages (Jinja2, Twig, Freemarker) -> emit signal SSTI
- Command output patterns in responses -> emit signal CMDi
- Reflection of input in HTML context -> emit signal XSS
- XML parsing errors -> emit signal XXE

Emetti il segnale in: $EDIR/signals/cross-type-signals.jsonl
Formato: {"source_skill": "sqli", "signal": "ssti", "evidence": "...", "endpoint": "..."}

Il router deve consumare questi segnali e dispatchare di conseguenza. Questo meccanismo non e' nel piano corrente e va aggiunto prima di qualsiasi decomposizione.

Rischio 2: --max-turns one-size-fits-all

Severita': BASSA-MODERATA

Tutte le skill usano --max-turns 250 (o 200 via runner). Infrastructure scanning, crypto checks e client-side tests raramente necessitano di 250 turni. Logic e injection testing a volte li usano tutti.

Il piano non propone budget di turni per skill.

Mitigazione: assegnare budget per classe di complessita':

Classe	Skill	Max turns
Deterministic	test-infra, test-crypto, test-client	80-120
Medium	test-api, test-ssrf, test-cloud	150
High	test-injection, test-auth, test-access, test-logic	250
Very High	test-advanced (chaining)	250+

Risparmio stimato: ~30-50% di turni sprecati sulle skill piu' semplici, zero rischio di coverage perche' le skill complesse mantengono il budget pieno.

Rischio 3: Le prompt capsules possono diventare stale

Severita': BASSA

Capsule compilate (brief-compact.json, attack-surface-compact.json) sono snapshot. Se lo stato dell'engagement diverge mid-pentest (nuovi endpoint scoperti, scope changes), le capsule diventano misleading.

Mitigazione: ogni capsule deve avere un TTL o timestamp di generazione. Qualsiasi capsule piu' vecchia dell'ultima discovery phase va rigenerata prima del dispatch.

Rischio 4: Overhead dei feature flag

Severita': BASSA

Sette feature flag aggiungono branching condizionale a shell script e markdown. Gestibile ma aumenta la complessita' di debugging.

Mitigazione: usare variabili d'ambiente con default chiari. Documentare quali flag sono "graduated" (always-on dopo validazione) vs ancora sperimentali. Dopo 2 cicli di validazione positiva, graduare il flag rimuovendo il condizionale.

Rischio 5: False negative nel differential rediscovery

Severita': MODERATA

Se il freshness check manca una nuova superficie di attacco (nuova versione API dietro lo stesso hostname, nuovo endpoint GraphQL non nel sitemap, route SPA cambiate senza riflesso nel JS hash), il sistema salta la full rediscovery e perde finding.

Mitigazione: gia' dettagliata nella sezione Workstream 4 sopra. Il punto critico e' il fallback periodico: force full rediscovery ogni N cicli a prescindere dal delta.

Rischio 6: Assunzione implicita di uniformita' del costo per subprocess

Severita': BASSA

Il piano tratta tutti i subprocess come se avessero lo stesso costo. In realta': - test-injection --scope sqli (con sqlmap, blind testing, time-based) puo' usare 200+ turni - test-crypto (verifica certificati, cipher suite) tipicamente ne usa 20-40

L'ottimizzazione dovrebbe essere proporzionale: i subprocess piu' costosi (injection, auth, logic) meritano piu' attenzione di ottimizzazione rispetto a quelli gia' leggeri.

---

4. Ottimizzazioni Mancanti

Mancante 1: Budget --max-turns per skill (ALTO ROI, ZERO RISCHIO)

Come dettagliato nel Rischio 2. Le skill deterministiche non necessitano di 250 turni. Ridurre i turni inutili senza impatto sulla coverage.

Mancante 2: Split di skill-boilerplate.md (ROI SINGOLO PIU' ALTO)

Il piano menziona "prompt capsules" in modo astratto ma non identifica il target singolo piu' grande: skill-boilerplate.md a 61.4KB caricato da ogni subprocess. Lo split in core (15KB) + moduli opzionali risparmia ~46KB x 36 subprocess = ~1.6M token per pentest completo.

Mancante 3: test-llm nella priority di decomposizione

A 204KB, test-llm/SKILL.md e' il secondo file skill piu' grande. Quando attivo, e' il dispatch singolo piu' costoso. Va aggiunto alla priority list dopo test-injection.

Mancante 4: Compattazione di agent-dispatch.md (37.5KB)

Contiene il protocollo di wave dispatch, tabelle di model routing e thinking budget. E' caricato dall'orchestratore pentest. Gran parte del contenuto sono tabelle di lookup esprimibili come JSON compatto invece che markdown narrativo:

{
  "wave_config": {
    "max_waves": 12,
    "agents_per_wave": 3,
    "agents_per_wave_fast": 5
  },
  "model_routing": {
    "test-injection": {"model": "opus", "thinking": 24000},
    "test-auth": {"model": "opus", "thinking": 16000},
    "test-infra": {"model": "haiku", "thinking": 2000}
  }
}

Risparmio stimato: ~50-60% del costo token di questo file.

Mancante 5: Centralizzazione safety rules duplicate

16 skill di test contengono ciascuna 3-5KB di regole safety specifiche per dominio. Le regole non sono identiche (ogni skill ha vincoli domain-specific), ma il framing boilerplate attorno ad esse e' duplicato:

## SAFETY: [skill-specific warning]
### Shared Initialization
**Run all initialization code from `pentest/helpers/skill-boilerplate.md`** before any test logic below.
This sets up: PATH isolation, stealth mode, structured logging, kill switch...

Estrarre il frame comune in un preamble safety condiviso e tenere solo il delta skill-specific in ogni skill risparmia ~40-50KB totali. Non e' un risparmio enorme per singola skill, ma su 16 skill diventa significativo.

Mancante 6: Cross-type signal forwarding (CRITICO per no-regression)

Come dettagliato nel Rischio 1. Senza questo meccanismo, la decomposizione delle skill in micro-pack rischia di perdere finding che emergono da cross-pollination tra tipi di vulnerabilita'. Questo e' l'unico punto dove l'ottimizzazione proposta potrebbe effettivamente ridurre la qualita' dei finding se non gestito.

---

5. Tabella Riassuntiva per Workstream

Workstream	Verdetto	Condizioni	Rischio regressione
WS0: Misurazione	APPROVATO	Aggiungere metriche supporting-files	Nessuno
WS1: Loop Hardening	APPROVATO	Reframe come nuova costruzione	Nessuno (build new)
WS2: Context Slimming	APPROVATO con condizioni	Boilerplate split prima di CLAUDE.md; rispettare supporting-files; signal forwarding prima di decomposizione	Moderato senza signal forwarding
WS3: Skinny Fork	APPROVATO con correzione	Fork gia' skinny; ottimizzare supporting-files e boilerplate, non il contesto conversazionale	Basso
WS4: Differential Rediscovery	APPROVATO	Aggiungere trigger mancanti; force full rediscovery periodico	Moderato su false negative
WS5: Proxy Analyzer	APPROVATO	Reframe come design spec; auto_analyze=False di default	Nessuno (build new)
WS6: Search Hygiene	APPROVATO	Nessuna	Nessuno
WS7: Model Routing	Lane A APPROVATA; Lane B richiede shadow	Deferire Lane B dopo WS0-6	Moderato per Lane B

---

6. Risparmio Complessivo Atteso

Sul flusso pentest corrente (Fasi 1-3)

Componente	Token risparmiati per pentest	Fonte
Boilerplate split (core vs optional)	~1.0-1.6M	36 subprocess x 30-45K risparmiati ciascuno
Skill decomposition (scope-specific)	~0.5-1.0M	12-15 dispatch pesanti x 40-70K risparmiati ciascuno
Max-turns budget per skill	~0.3-0.5M	15-20 skill semplici con turni dimezzati
agent-dispatch.md compaction	~0.1-0.2M	Singolo file, caricato dall'orchestratore
Totale stimato	~2.0-3.3M token per pentest completo	50-70% riduzione sul flusso corrente

Sul BB loop (Fase 4, quando costruito)

Componente	Riduzione stimata
Singleton lock + cooldown globale	40-85% del burn attuale da spawn storm
Dead-run classification + backoff	Incluso sopra
Differential rediscovery (programmi stabili)	30-70% addizionale sui cicli di ritorno
Proxy novelty gate (se attivo)	60-95% del background proxy burn
Totale stimato	70-90% riduzione complessiva

---

Conclusione

Il piano puo' consegnare una riduzione del 50-70% del consumo token totale sul flusso pentest corrente e una riduzione del 70-90% sul BB loop.

Nessuna regressione di qualita' finding o copertura e' attesa da nessun cambiamento approvato, a condizione che:

• Il cross-type signal forwarding sia implementato insieme alla decomposizione skill
• I budget max-turns per skill siano validati contro dati storici di utilizzo turni
• Il model routing (Lane B) passi attraverso shadow validation prima del rollout
• Il differential rediscovery includa force full rediscovery periodico come safety net

La metodologia del progetto e' eccezionale. Il lavoro di ottimizzazione riguarda rendere piu' magro il veicolo di consegna, non cambiare cosa consegna.