Layer 3: applicazione della doctrine a claude-agent-sdk-demos
Il cohort-bridge di AIDB ha impacchettato in automatico il glue layer SDK dell'email-agent di anthropics/claude-agent-sdk-demos e l'ha sottoposto a architect.validate. La doctrine che gira dentro Claude Code via MCP sta ora valutando la dimostrazione di Anthropic stessa di come è costruito il substrato di Claude Code. Il validator si è impegnato in modo mechanism-specific con codice che non è mai stato ottimizzato per la production governance — per esplicita dichiarazione di Anthropic.
Fatti chiave
Verdetto
22/F · high_risk · draft
Blocker production
7 dei 10 principi
Finding più alto
P8 Approvals · sev 95/100
Metodologia
Scan single-pass · commit-pinned
Cosa è stato scansionato e cosa no
Repository: `anthropics/claude-agent-sdk-demos` al commit `826b2685…`. Il bridge ha selezionato otto file da `email-agent/ccsdk/*` — il glue layer SDK che collega il Claude Agent SDK ai manager di listener/action, custom tools, UI state e message queue del demo. Bundle totale: 53 KB.
Il README di Anthropic dichiara che i demo sono per sviluppo locale, non per deployment production. Lo scan applica la doctrine dei 10 principi di AIDB al codice di riferimento al valore facciale. I finding sono mechanism-specific — nominano la funzione, la lista di tool, il checkpoint mancante. Non sono critiche all'engineering di Anthropic. Sono esempi di cosa la doctrine rivela quando applicata a codice fuori dalla superficie di ottimizzazione production-governance.
Commit pinnato al momento dello scan: 826b268506a5f3707623c9e6140b200befcbebae
Tre layer, tre audit
1Layer 1 — il validator valuta il proprio codice sorgente. Self-audit cert-confermato, 14 round precedenti.
2Layer 2 — il validator valuta un agente governato. Baseline canary 100/A pulito, 18/F iniettato.
3Layer 3 — il validator valuta il suo substrato. Questo case study. La doctrine di AIDB gira sopra il Claude Agent SDK di Anthropic; la doctrine ora valuta il demo di come costruirci sopra.
Verdetto
Il finding di apertura del validator sul bundle è che tool di mutazione mailbox raggiungono il contesto dell'agente senza un break di approvazione esplicito, in un substrato che spedisce con `Bash`, `Edit` e `Write` abilitati di default. Lo score e le severità sono le ricevute: 22/F · high_risk · draft. Sette blocker production su P1, P2, P5, P7, P8, P9, P10. Tre finding hardening_recommended su P3, P4, P6. Un principio (P8) ha avuto verdetto high_risk a severità 95 — l'unico principio nel run dove il validator ha escalato oltre needs_changes.
La code-classification del validator etichetta il bundle come `autonomous_agentic_workflow`: "Il codice non è un semplice componente API sincrono: AIClient.queryStream esegue sessioni multi-turn del Claude Agent SDK con accesso ai tool, ListenersManager.checkEvent esegue handler di listener triggherati da evento, e i manager caricano script custom eseguibili da agent/custom_scripts. La presenza di listener background, action, message queue, tool call e helper di mutazione email rende questo un autonomous agentic workflow."
Il finding P8, verbatim
P8 (Approvazioni & blocker) è l'unico principio con verdetto high_risk e la severità più alta nel run. Il testo è del validator, non dell'autore del case study:
HIGH_RISK95/100
L'handling di approvazione e blocker è il boundary critico che fallisce. Gli handler dei listener automatici ricevono `archiveEmail`, `starEmail`, `markAsRead` e `addLabel` in `createContext()` e possono mutare lo stato della mailbox senza un break `awaiting_approval`. `AIClient.defaultOptions.allowedTools` permette `Bash`, `Edit`, `Write`, `WebFetch` e `Task`; l'hook `PreToolUse` blocca solo scritture `.js`/`.ts` fuori da `agent/custom_scripts`, quindi altre scritture, comandi shell e action di rete possono procedere. `custom-tools.ts` inietta corpi email non fidati nel contesto dell'agente, creando un path di prompt-injection dal contenuto email esterno a tool potenti. I blocker sono per lo più `console.error` o response di errore testuali, e `MessageQueue.close()` può lasciare consumer pendenti non risolti.
Blocker production
Sette principi hanno ricevuto una severity class `production_blocker`. Il validator ha nominato la funzione, il data path e il checkpoint mancante in ognuno. Le severità sono del validator; la prosa del razionale è del validator; questo case study riordina per severità per leggibilita'.
P8 · Hand-offs, approvals, and blockersmake-hand-offs-approvals-and-blockers-explicit
HIGH_RISK95/100
Gli handler dei listener automatici ricevono `archiveEmail`, `starEmail`, `markAsRead` e `addLabel` in `createContext()` e possono mutare lo stato della mailbox senza un break `awaiting_approval`. `AIClient.defaultOptions.allowedTools` permette `Bash`, `Edit`, `Write`, `WebFetch` e `Task`; l'hook `PreToolUse` blocca solo scritture `.js`/`.ts` fuori da `agent/custom_scripts`. `custom-tools.ts` inietta corpi email non fidati nel contesto dell'agente, creando un path di prompt-injection dal contenuto email esterno a tool potenti.
P10 · Steering, not only initiatingoptimise-for-steering-not-only-initiating
NEEDS_CHANGES75/100
`AIClient.queryStream` passa `maxTurns` e `resume`, ma non c'è abort controller, comando pause/resume, update dinamico dei vincoli, o checkpoint di side-effect in questo layer. `ListenersManager.checkEvent` esegue i listener che matchano fino al completamento una volta triggherati; gli helper di mutazione email non controllano cancellation o policy cambiata prima di agire. `ActionsManager.executeAction` esegue un handler una volta e ritorna un risultato — retry, rollback, ri-prioritizzazione e correzione mid-run non sono rappresentati.
P7 · Trust through inspectabilityestablish-trust-through-inspectability
NEEDS_CHANGES70/100
Non c'è un `run_id` persistente che correla i messaggi di `AIClient.queryStream`, le invocazioni di listener, le mutazioni email, gli update di UI state, e le esecuzioni di action. `callAgent()` non registra prompt, modello, schema, response, o razionale di tool-use; le write di log dei listener sono fire-and-forget; i file JSONL non sono tamper-evident. `custom-tools.ts` scrive risultati email completi formattati, incluso `body`, in log locali — tracciabile ma crea una superficie audit di dati sensibili senza governance.
P1 · Design for delegationdesign-for-delegation-rather-than-direct-manipulation
NEEDS_CHANGES65/100
`createContext()` consegna ad ogni listener abilitato helper come `archiveEmail`, `starEmail`, `markAsRead`, `addLabel`, `callAgent` e `uiState.set` senza un envelope di authority persistente, scope di permessi per-listener, o controlli di lifecycle oltre `config.enabled`. `AIClient.defaultOptions.allowedTools` concede tool ampi inclusi `Task`, `Bash`, `Edit`, `Write`, `WebFetch` e `WebSearch` senza legarli ai vincoli dichiarati dall'utente.
P5 · Replace implied magic with clear mental modelsreplace-implied-magic-with-clear-mental-models
NEEDS_CHANGES60/100
Il prompt in `EMAIL_AGENT_PROMPT` distingue `Listeners = Automatici/event-triggered` da `Actions = User-triggered/on-demand`, ma le capacità runtime reali sono molto più ampie. `AIClient.defaultOptions.allowedTools` include `Bash`, `Edit`, `Write`, `Task`, `WebFetch` e `WebSearch`; `custom-tools.ts` ritorna contenuto `body` email non fidato nel contesto dell'agente; e gli handler dei listener ricevono funzioni di mutazione email senza una spiegazione esplicita dei permessi.
P2 · Background work remains perceptibleensure-that-background-work-remains-perceptible
NEEDS_CHANGES60/100
`ListenersManager` scrive un `ListenerLogEntry` dopo che l'handler finisce e opzionalmente chiama `logBroadcastCallback`, mentre `ActionsManager.logExecution` appende log JSONL, ma non c'è un record di run persistente che mostri `queued`, `active`, `blocked`, `awaiting approval`, o `failed` durante l'esecuzione. `this.logWriter.appendLog(...).catch(...)` è fire-and-forget. `MessageQueue.close()` setta `closed = true` e droppa `resolvers` senza risolvere le chiamate `next()` pendenti, lasciando waiter strandati in silenzio.
P9 · Delegated work as a systemrepresent-delegated-work-as-a-system-not-merely-as-a-conversation
NEEDS_CHANGES60/100
`AIClient.queryStream` produce messaggi SDK, `ActionsManager.instances` e `ComponentManager.instances` sono mappe in-memory, le invocazioni di listener sono loop per-event, e i log sono file JSONL separati. Non c'è un run graph, una task timeline, un dependency model, o un record di orchestrazione condiviso che leghi una sessione agente alle action create dai listener, allo state dei componenti, alle letture email e alle mutazioni email.
Perché questo conta operativamente
La doctrine che valuta gli applicanti della cohort è la stessa doctrine che gira dentro Claude Code via MCP. Quando quella doctrine è applicata a una codebase di riferimento pubblicata dal vendor del substrato, i finding che il validator emerge non sono prosa generica di best-practice. Sono mechanism-specific: `createContext()` distribuisce helper di mutazione mailbox; la lista di tool permessi include `Bash`/`Edit`/`Write`; `PreToolUse` blocca solo una classe di estensione; i corpi email fluiscono nel contesto agente non filtrati.
Questi finding sono utili in due direzioni. Per un applicante che costruisce sopra il Claude Agent SDK, i finding nominano i boundary che hanno bisogno di governance esplicita prima che il pattern demo raggiunga production. Per AIDB, lo scan layer-3 dimostra che la doctrine emerge meccanismi reali — non platitudini — quando applicata a codice fuori dalla propria superficie.
Il framing di Anthropic è preservato. I finding del validator sono preservati. Entrambi sono veri. Un practitioner che adatta questo pattern verso production ha bisogno di entrambi.
Cosa stabilisce lo scan layer-3
Tre layer di integrità ricorsiva hanno ora ricevute pubbliche: validator-su-validator, validator-su-agente-governato, validator-su-substrato. Stesso rubric dei 10 principi, stesso engagement mechanism-specific, tre superfici di codice, tre verdetti. Le ricevute sono l'artefatto.
Sulla serie comparativa
Questo è il primo di una serie pianificata che applica la doctrine di AIDB ai principali substrati di agent-SDK. I prossimi case study seguiranno la stessa metodologia e lo stesso bridge selector, con ogni scan che pubblica il proprio run_id e statement di scope. Le analisi comparative tra vendor sono pubblicate separatamente.
Tre case study, tre faccette
Questa è la faccetta di substrate-validation della triade di integrità ricorsiva. Le altre due faccette sono pubbliche: lo scan di self-validation sull'orchestratore cohort-bridge che seleziona cosa alimentare al validator, e lo scan di reference-honesty sul nostro stesso esempio del protocollo A2A. Stessa doctrine, tre superfici di codice, tre verdetti diversi.
Rigiocabile dal run_id: /readiness-review/056929ab…. Il ragionamento completo per principio, le severità, le raccomandazioni e il razionale di code-classification sono persistiti server-side. Il fingerprint della doctrine dei 10 principi è lo stesso fingerprint che ha valutato ogni precedente run layer-1 e layer-2.
Politica di ricorrenza
Questo scan riflette il substrato al commit 826b2685 del 2026-05-12. Man mano che Anthropic aggiorna `claude-agent-sdk-demos`, i finding qui diventano storici, non correnti. Eventuali rescan futuri, se AIDB li conduce, verrebbero pubblicati come case study separati con run_id e statement di scope propri.
