o nel modo classico:```
pip install halo-record
halo demo --serve

Anche uno shim di comodità `from halo import ...` viene fornito — ma il nome `halo` su PyPI appartiene a un pacchetto terminal-spinner non correlato, e se quel pacchetto è installato vince l'import. `halo_record` è inequivocabile, quindi gli esempi lo usano.

Senza `log=`, i record vanno in `~/.halo/my-agent.jsonl` (una catena per agente). Il wrapper sigilla il confine di esecuzione; l'evidenza risiede nei record per chiamata. Catturali con un adattatore di framework (matrice sotto) — o esplicitamente, il che mostra anche come si collegano le deleghe:```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")

with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:            # one sealed record per tool call
    call.result = crm.lookup("acct-9")

with record_call(rec, "payments.refund", {"amount": 120},
                 parent_id=rec.last_record_id()) as call:                      # child links to the action that spawned it
    call.result = payments.refund(120)

Il quickstart termina quando stai guardando il Runtime Report del tuo agente in un browser. Se hai ottenuto un file JSONL e nessun report, qualcosa non va: apri una issue.

### Il blocco di verifica

Se un guardrail o un livello di policy ha controllato l'azione, il suo verdetto può viaggiare sul record — un blocco opzionale che registra ciò che il gate ha deciso, sigillato nella catena di hash come ogni altro campo:```python
from halo_record import build

build("tool_call", "security", tool="payments.refund",
      verification={"status": "allowed", "verifier": "gate/1.2",
                    "policy_ref": "sha256:1f3a...",
                    "checked_at": "2026-08-01T12:00:00Z"})

`record_call(...)` accetta la stessa keyword `verification=`. `status` è obbligatorio all'interno del blocco; `verifier`, `policy_ref` e `checked_at` sono opzionali. Cosa significa ogni stato:

| Stato | Cosa riporta il gate | L'azione è stata eseguita? |
|---|---|---|
| `allowed` | ha permesso l'azione | sì — l'azione è proceduta |
| `blocked` | ha negato l'azione | determinato dall'integrazione, non da questo campo — un record può comunque riportare un esito, e un blocco di per sé non prova la mancata esecuzione |
| `modified` | ha alterato l'azione prima dell'esecuzione — `action.input` descrive l'azione **così come eseguita**, dopo la modifica | sì, nella forma alterata |
| `unverified` | è stato eseguito (o consultato) ma non ha prodotto alcuna determinazione — distinto da un blocco assente, che significa che non è stata avanzata alcuna pretesa di verifica | sì — l'azione è proceduta senza un verdetto |

Il blocco è fornito dal codice di integrazione dell'operatore e registra ciò che esso riporta che il gate abbia detto — la stessa postura di fiducia di `principal` (vedi [LIMITS](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#11-verification-status-is-the-gates-report-not-halos-finding)). La sigillatura prova che lo stato non è stato modificato a posteriori; non prova che il controllo sia avvenuto, che il verdetto fosse corretto, o che un'azione bloccata non sia stata eseguita. Questa non è una verifica indipendente.

Affinché `policy_ref` sia utilizzabile come prova, usa un hash del contenuto del ruleset e conserva l'artefatto del ruleset — un'etichetta non risolvibile rende il campo decorativo.

## Connettiti a ciò che già esegui

| Catturato al confine | Acquisito dalla telemetria esistente |
|---|---|
| Recorder nativo (`from halo_record import trace`) | Span OpenTelemetry GenAI |
| Intercettore MCP | Callback LiteLLM |
| Callback LangChain / LangGraph | Esportazione Langfuse |
| Hook OpenAI Agents SDK | Qualsiasi log di gateway / reverse-proxy |
| Hook Claude Agent SDK | Hook `PostToolUse` di Claude Code e Codex CLI (si attivano dopo l'esecuzione dello strumento) |

Gli adattatori di framework e i percorsi di acquisizione marcano ogni record con un tag `source`, così il report divulga come ogni elemento di prova è stato raccolto. I record catturati e quelli acquisiti risiedono nella stessa catena.

Per LangChain / LangGraph, è un callback handler:```python
from halo_record import Recorder
from halo_record.integrations.langchain import HaloCallbackHandler

recorder = Recorder("audit.jsonl")
result = my_chain.invoke(inputs, config={"callbacks": [HaloCallbackHandler(recorder)]})   # every tool call becomes a record

Per i log di gateway o proxy (Cloudflare AI Gateway, Portkey, nginx davanti al modello), mappare una riga di log nella catena — esplicitamente contrassegnata come acquisita, non catturata al confine:```python
from halo_record.integrations.gateway import record_log

record_log(Recorder("audit.jsonl"), {"tool": "gen_ai:gpt-4o", "model": "gpt-4o", "status": 200, "subject": "acme-corp"})

Aggiungilo a `~/.claude/settings.json` e i record finiscono in `~/.halo/audit.jsonl` (sovrascrivibile con `$HALO_LOG`). Gli strumenti di pura orchestrazione che non toccano dati, rete o stato esterno vengono saltati — la catena registra le azioni sui confini di fiducia, non il pensiero. Imposta `HALO_HASH_ONLY=1` per registrare gli hash dei contenuti senza riepiloghi. Imposta `HALO_AGENT_VERSION` (e facoltativamente `HALO_AGENT_MODEL`) per associare ogni record alla build dell'agente che l'ha prodotto — quando un auditor chiede informazioni sulla versione in esecuzione in una determinata finestra, l'export risponde per colonna invece che a memoria.

Codex CLI fornisce gli stessi hook del ciclo di vita con la stessa forma degli eventi (gli hook sono attivi per impostazione predefinita). Aggiungi questo a `~/.codex/hooks.json` e i comandi shell di Codex, le modifiche di `apply_patch` e le chiamate MCP finiscono nella stessa catena:```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

## Installazione

### Requisiti

- Python 3.8+
- pip (gestore di pacchetti Python)

### Installazione da PyPI

```bash
pip install pyxam

git clone https://github.com/example/pyxam.git
cd pyxam
pip install -e .

docker pull example/pyxam:latest
docker run -it example/pyxam --help

from pyxam import Xam

# Inizializza il client
client = Xam(api_key="your-api-key")

# Esegui una scansione
result = client.scan(target="example.com")
print(result)

pyxam scan --target example.com --output results.json

from pyxam import Xam

client = Xam()
result = client.scan(target="https://example.com")
print(f"Trovate {len(result.vulnerabilities)} vulnerabilità")

targets = ["example.com", "test.com", "demo.com"]
for target in targets:
    result = client.scan(target=target)
    print(f"{target}: {result.status}")

Lo snapshot è sigillato nella stessa catena di hash dei record delle azioni. Un buon valore predefinito è uno snapshot a livello di sessione all'inizio, più un nuovo snapshot quando cambiano regole, Skills, hook, registri di strumenti MCP o policy di compattazione. Per mantenere snelle le sessioni lunghe, i record consecutivi con lo stesso `authority.snapshot_id` vengono compattati dopo il primo snapshot completo: i record successivi mantengono solo `{"snapshot_id": "...", "same_as_previous": true}`. Il puntatore rimane concatenato tramite hash, ma il blocco voluminoso refs/omissions/stale-if non viene ripetuto a ogni azione. (La compattazione è per processo del recorder: la cattura in stile hook che genera un processo per ogni chiamata di strumento ri-archivia il corpo completo ogni volta che lo snapshot completo precedente non è il record di coda, quindi i processi di breve durata scambiano dimensione della catena con la protezione di riutilizzo.)

Gli utenti dell'SDK allegano lo stesso blocco direttamente — `build(..., authority={...})` o `record_call(..., authority={...})`; la cattura solo-hash è la stessa superficie (`summaries=False` su uno qualsiasi di essi):```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"},
                 authority={"snapshot_id": "auth_1", "rules_hash": "sha256:..."},
                 summaries=False) as call:              # hash-only: no summaries, no excerpts
    call.result = crm.lookup("acct-9")

Qualsiasi runtime di agente che espone un hook post-azione può alimentare lo stesso comando — l'hook legge un evento come JSON su stdin e aggiunge un record.

Una catena, un solo scrittore alla volta. Una catena è una lista concatenata: due scrittori che leggono la stessa testa e aggiungono entrambi la ramificheranno (due record che rivendicano lo stesso predecessore), e la verifica nominerà i record interessati. `Recorder` serializza i propri append con un lock sidecar (POSIX `flock` qui; una directory di lock nel pacchetto TypeScript), e `halo hook` aggiunge tramite `Recorder`, quindi la configurazione dell'hook sopra è coperta. Qualsiasi cosa che scriva direttamente il file della catena — un hook artigianale, worker paralleli, un log shipper — deve mantenere un lock esclusivo equivalente attraverso la sequenza read-head-then-append, oppure scrivere su catene per-processo. [LIMITS.md sezione 9](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#9-single-writer-chains) copre questo in modo completo, incluso il confine cross-linguaggio.

## Quando la registrazione fallisce

I due stili di integrazione falliscono in direzioni opposte, di proposito — scegli quello la cui modalità di fallimento puoi sopportare:

- **Gli adattatori di framework (LangChain, hook tramite callback manager) falliscono aperti.** Se un record non può essere scritto (disco pieno, permessi), l'azione dell'agente si completa normalmente e il record viene perso. L'handler LangChain stampa un avviso evidente su stderr e conta la perdita (`handler.lost_records`), ma nulla nella catena stessa può mostrare un record che non è mai stato scritto — una catena bloccata verifica comunque. I checkpoint del witness a cadenza sono ciò che rende visibile una catena bloccata: un checkpoint atteso che non arriva mai è l'allarme.
- **Il wrapper nativo `trace()` fallisce chiuso.** Se il record non può essere scritto, l'eccezione si propaga nell'azione dell'agente — nessuna prova, nessuna azione. Più rigoroso, e può interrompere il tuo agente.

Nessuno dei due default è giusto per tutti; sappi quale stai eseguendo.

## Integrità vs. completezza (leggi questa parte)

Sii preciso su ciò che ogni livello dimostra — perché sono affermazioni diverse, e le differenze sono il punto:

Una catena auto-detentua dimostra **integrità rispetto a una testa stabilita**: data una testa di catena che qualcuno già detiene, qualsiasi modifica, riordino o cancellazione nei record dietro di essa diventa rilevabile. Di per sé — prima che qualcuno esterno all'operatore abbia visto una testa — una catena dimostra coerenza interna, non storia: un operatore potrebbe eliminare un record e ri-sigillare, e il nuovo file verificherebbe. La catena diventa **storicamente impegnata** nel momento in cui la sua testa lascia il controllo dell'operatore.

Questo è il witness: una parte esterna all'operatore che detiene checkpoint periodici della catena — l'id del soggetto, un conteggio dei record, e due impronte della catena (la testa e la radice della catena); il payload esatto, e nulla di più. I checkpoint rendono rilevabile la riscrittura della storia impegnata, e un checkpoint mancato è esso stesso un evento visibile:```
halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

`--check` conferma che il token è vincolato a questo stato della catena e ne legge il tempo attestato, ma **non** convalida la firma della TSA — ciò è deliberatamente lasciato a uno strumento standard affinché un revisore non debba fidarsi di alcun nostro codice. Per verificare il tempo in modo indipendente (questo è ciò che si consegna a un revisore di sicurezza):```
# tsa.token_b64 lives in the witness log; decode the latest one to a standard .tsr file
python3 -c 'import json,base64; cps=[json.loads(l) for l in open("witness.jsonl") if l.strip()]; t=[c["tsa"] for c in cps if c.get("tsa")][-1]; open("token.tsr","wb").write(base64.b64decode(t["token_b64"])); print(t["digest"])'
curl -s -o tsa-ca.pem https://freetsa.org/files/cacert.pem     # CA for the default TSA (a commercial TSA publishes its own)
openssl ts -verify -digest <the digest printed above> -in token.tsr -CAfile tsa-ca.pem   # → "Verification: OK"

Nessuna impostazione impone questo — è una disciplina nel modo in cui chiami il recorder.
Rende la cancellazione gestibile; non è anonimizzazione, e non esiste ancora
una retention o una potatura integrate.
[LIMITS.md sezione 13](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#13-personal-data-and-erasure) contiene l'elenco completo dei campi,
spiega perché l'impronta dell'input memorizzata può confermare un valore indovinabile anche
dopo che la mappatura è sparita, e termina con le domande che un revisore dovrebbe porre.

Registra una chiamata al modello (la prima domanda dell'acquirente: "quale modello ha visto i miei dati?"):```python
from halo_record import record_model_call

record_model_call(rec, provider="anthropic", model="claude-sonnet-4-6",
                  zdr=True, purpose="draft support reply",
                  subject="acme")   # tool=model.generate, scope=model:anthropic

Questo scrive due file per la finestra di audit: il CSV (una riga per ogni azione registrata, raggruppate da sinistra a destra come *quando → cosa è successo → chi → sotto quale autorità → cosa è stato segnalato → provenienza → come verificare*, inclusa una sintesi in linguaggio semplice e redatta della chiamata e del suo risultato, la build dell'agente e il modello che ha prodotto ciascuna, l'identità per conto della quale è stata eseguita, il record che l'ha causata, la sua decisione di autorizzazione e l'ambito, e qualsiasi categoria di dati personali o flag di minaccia acquisiti) e un manifest (`evidence.csv.manifest.json`) che collega il CSV alla sua origine — l'hash di testa della catena lo collega al log verificabile da cui proviene, e `csv_sha256` è l'hash del file esportato stesso, quindi un CSV modificato dopo l'esportazione non corrisponde più al suo manifest. Restringi la popolazione con `--tool` quando un controllo copre solo determinate azioni; il manifest registra il filtro, quindi un'esportazione con ambito limitato dichiara di essere un sottoinsieme anziché essere letta come l'intera popolazione. Carica entrambi in base al tuo controllo di logging o monitoraggio; allega il Runtime Report HTML quando un revisore vuole verificare la catena autonomamente. L'esportazione rifiuta di essere eseguita su una catena che non supera la verifica.

Un'integrazione push nativa — con le prove che arrivano automaticamente nella tua piattaforma — è in programma. Il percorso file sopra funziona oggi con qualsiasi piattaforma che accetta prove caricate.

## CLI```
halo verify   validate schema + hash chain (exit 1 broken, 3 empty chain; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo policy   corroborate a chain against a declarative policy pack
              (per-rule pass / violation / evidence-gap; exit 1 violated, 3 nothing in scope)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo viewers  list who has unlocked a gated report
halo anchor   witness a chain head, or --check completeness (exit 1 incomplete, 3 unwitnessed)
halo witness-serve  run a witness over HTTP: vendors anchor chain heads, viewers fetch checkpoints
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook