oder auf die klassische Weise:```
pip install halo-record
halo demo --serve

Ein `from halo import ...`-Convenience-Shim wird ebenfalls mitgeliefert — aber der Name `halo` auf PyPI gehört zu einem unabhängigen Terminal-Spinner-Paket, und wenn dieses Paket installiert ist, gewinnt es den Import. `halo_record` ist eindeutig, daher verwenden die Beispiele es.

Ohne `log=` gehen Records nach `~/.halo/my-agent.jsonl` (eine Chain pro Agent). Der Wrapper versiegelt die Run-Grenze; die Evidenz liegt in den Per-Call-Records. Erfasse diese mit einem Framework-Adapter (Matrix unten) — oder explizit, was auch zeigt, wie Delegation verknüpft:```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)

Der Quickstart endet, wenn du den Runtime Report deines eigenen Agenten im Browser siehst. Wenn du eine JSONL-Datei und keinen Report bekommen hast, stimmt etwas nicht: Öffne ein Issue.

### Der Verifikationsblock

Wenn eine Guardrail- oder Policy-Schicht die Aktion geprüft hat, kann ihr Urteil auf dem Datensatz mitgeführt werden — ein optionaler Block, der festhält, was das Gate entschieden hat, versiegelt in der Hash-Kette wie jedes andere Feld:```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(...)` akzeptiert dasselbe `verification=`-Schlüsselwort. `status` ist innerhalb des Blocks erforderlich; `verifier`, `policy_ref` und `checked_at` sind optional. Was die einzelnen Status bedeuten:

| Status | Was das Gate meldet | Wurde die Aktion ausgeführt? |
|---|---|---|
| `allowed` | es hat die Aktion erlaubt | ja — die Aktion wurde fortgesetzt |
| `blocked` | es hat die Aktion verweigert | bestimmt durch die Integration, nicht durch dieses Feld — ein Datensatz kann dennoch ein Ergebnis tragen, und ein Block beweist für sich genommen keine Nichtausführung |
| `modified` | es hat die Aktion vor der Ausführung verändert — `action.input` beschreibt die Aktion **wie ausgeführt**, nach der Modifikation | ja, in der veränderten Form |
| `unverified` | es lief (oder wurde konsultiert), traf aber keine Feststellung — verschieden von einem fehlenden Block, was bedeutet, dass überhaupt keine Verifikationsaussage gemacht wurde | ja — die Aktion wurde ohne Urteil fortgesetzt |

Der Block wird vom Integration-Code des Betreibers bereitgestellt und zeichnet auf, was dieser als Aussage des Gates meldet — dieselbe Vertrauenshaltung wie bei `principal` (siehe [LIMITS](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#11-verification-status-is-the-gates-report-not-halos-finding)). Das Versiegeln beweist, dass der Status nachträglich nicht verändert wurde; es beweist nicht, dass die Prüfung stattgefunden hat, dass das Urteil korrekt war oder dass eine blockierte Aktion nicht ausgeführt wurde. Dies ist keine unabhängige Verifikation.

Damit `policy_ref` als Nachweis verwendbar ist, verwenden Sie einen Content-Hash des Regelsatzes und bewahren Sie das Regelsatz-Artefakt auf — ein nicht auflösbares Label macht das Feld dekorativ.

## Anbinden an das, was Sie bereits betreiben

| An der Grenze erfasst | Aus vorhandener Telemetrie eingespeist |
|---|---|
| Nativer Recorder (`from halo_record import trace`) | OpenTelemetry GenAI Spans |
| MCP-Interceptor | LiteLLM-Callbacks |
| LangChain / LangGraph-Callback | Langfuse-Export |
| OpenAI Agents SDK Hooks | Jedes Gateway- / Reverse-Proxy-Log |
| Claude Agent SDK Hook | Claude Code und Codex CLI `PostToolUse` Hooks (feuern, nachdem das Tool lief) |

Framework-Adapter und Ingestion-Pfade versehen jeden Datensatz mit einem `source`-Tag, sodass der Bericht offenlegt, wie jeder Nachweis erhoben wurde. Erfasste und eingespeiste Datensätze leben in derselben Kette.

Für LangChain / LangGraph ist es ein 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

Für Gateway- oder Proxy-Logs (Cloudflare AI Gateway, Portkey, nginx vor dem Modell) wird eine Log-Zeile in die Kette eingefügt – explizit als ingestiert gekennzeichnet, nicht als Boundary-captured:```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"})

Füge das zu `~/.claude/settings.json` hinzu, und Einträge landen in `~/.halo/audit.jsonl` (überschreibbar mit `$HALO_LOG`). Reine Orchestrierungswerkzeuge, die keine Daten, Netzwerk oder externen Zustand berühren, werden übersprungen — die Kette zeichnet Vertrauensgrenzaktionen auf, nicht Denken. Setze `HALO_HASH_ONLY=1`, um Inhalts-Hashes ohne Zusammenfassungen aufzuzeichnen. Setze `HALO_AGENT_VERSION` (und optional `HALO_AGENT_MODEL`), um jeden Eintrag an den Agenten-Build zu binden, der ihn erzeugt hat — wenn ein Auditor nach der Version fragt, die in einem bestimmten Zeitfenster lief, antwortet der Export spaltenweise statt aus dem Gedächtnis.

Codex CLI liefert dieselben Lifecycle-Hooks mit derselben Ereignisform (Hooks sind standardmäßig aktiviert). Füge dies zu `~/.codex/hooks.json` hinzu, und Codex' Shell-Befehle, `apply_patch`-Bearbeitungen und MCP-Aufrufe landen in derselben Kette:```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

| `--config` | Pfad zur Konfigurationsdatei (Standard: `config.yaml`) |
| `--output` | Ausgabeverzeichnis für Berichte (Standard: `reports/`) |
| `--format` | Ausgabeformat: `json`, `html`, `csv` (Standard: `json`) |
| `--verbose` | Ausführliche Protokollierung aktivieren |
| `--quiet` | Alle Ausgaben außer Fehlern unterdrücken |

### Verwendungsbeispiele

```bash
# Grundlegende Ausführung mit Standardkonfiguration
python -m scanner --config config.yaml

# Ausführung mit benutzerdefiniertem Ausgabeverzeichnis und HTML-Bericht
python -m scanner --config config.yaml --output ./results --format html

# Ausführung im ausführlichen Modus
python -m scanner --config config.yaml --verbose

targets:
  - https://example.com
  - https://test.example.org

timeout: 60
threads: 20
retry: 5
log_level: DEBUG

{
  "scan_id": "abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "targets": [
    {
      "url": "https://example.com",
      "status": "success",
      "findings": []
    }
  ]
}

pip install -r requirements.txt

Der Snapshot wird in dieselbe Hash-Kette wie die Action-Records eingefügt. Ein guter Standard ist ein Session-Level-Snapshot zu Beginn, plus ein neuer Snapshot, wenn sich Regeln, Skills, Hooks, MCP-Tool-Registries oder die Compaction-Policy ändern. Um lange Sessions schlank zu halten, werden aufeinanderfolgende Records mit derselben `authority.snapshot_id` nach dem ersten vollständigen Snapshot kompaktiert: spätere Records behalten nur `{"snapshot_id": "...", "same_as_previous": true}`. Der Pointer bleibt hash-verkettet, aber der umfangreiche refs/omissions/stale-if-Block wird nicht bei jeder Action wiederholt. (Die Compaction erfolgt pro Recorder-Prozess: Bei Hook-artiger Erfassung, die pro Tool-Aufruf einen Prozess startet, wird der vollständige Body jedes Mal neu gespeichert, wenn der vorherige vollständige Snapshot nicht der Tail-Record ist, sodass kurzlebige Prozesse Ketten-Größe gegen den Wiederverwendungs-Guard eintauschen.)

SDK-Nutzer hängen denselben Block direkt an — `build(..., authority={...})` oder `record_call(..., authority={...})`; Hash-only-Erfassung ist dieselbe Oberfläche (`summaries=False` bei jedem von ihnen):```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")

Jede Agent-Runtime, die einen Post-Action-Hook bereitstellt, kann denselben Befehl einspeisen — der Hook liest ein Ereignis als JSON von stdin und hängt einen Datensatz an.

Eine Chain, ein Writer zur Zeit. Eine Chain ist eine verkettete Liste: Zwei Writer, die denselben Head lesen und beide anhängen, spalten sie auf (zwei Datensätze, die denselben Vorgänger beanspruchen), und die Verifikation wird die betroffenen Datensätze benennen. `Recorder` serialisiert seine eigenen Anhänge mit einem Sidecar-Lock (hier POSIX `flock`; ein Lock-Verzeichnis im TypeScript-Paket), und `halo hook` hängt über `Recorder` an, sodass das obige Hook-Setup abgedeckt ist. Alles, was die Chain-Datei direkt schreibt — ein handgeschriebener Hook, parallele Worker, ein Log-Shipper — muss einen äquivalenten exklusiven Lock über die Sequenz Read-Head-dann-Append halten oder in prozessspezifische Chains schreiben. [LIMITS.md Abschnitt 9](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#9-single-writer-chains) behandelt dies vollständig, einschließlich der sprachübergreifenden Grenze.

## Wenn die Aufzeichnung fehlschlägt

Die beiden Integrationsstile schlagen absichtlich in entgegengesetzte Richtungen fehl — wähle denjenigen, dessen Fehlverhalten du verkraften kannst:

- **Framework-Adapter (LangChain, Hooks über Callback-Manager) schlagen offen fehl.** Wenn ein Datensatz nicht geschrieben werden kann (Festplatte voll, Berechtigungen), wird die Aktion des Agenten normal abgeschlossen und der Datensatz geht verloren. Der LangChain-Handler gibt eine laute Warnung an stderr aus und zählt den Verlust (`handler.lost_records`), aber nichts in der Chain selbst kann einen Datensatz anzeigen, der nie geschrieben wurde — eine stagnierende Chain verifiziert trotzdem. Witness-Checkpoints in regelmäßigen Abständen sind das, was eine stagnierende Chain sichtbar macht: Ein erwarteter Checkpoint, der nie eintrifft, ist der Alarm.
- **Der native `trace()`-Wrapper schlägt geschlossen fehl.** Wenn der Datensatz nicht geschrieben werden kann, breitet sich die Ausnahme in die Aktion des Agenten aus — keine Evidenz, keine Aktion. Strenger, und es kann deinen Agenten unterbrechen.

Keine der beiden Standardeinstellungen ist für alle richtig; wisse, welche du ausführst.

## Integrität vs. Vollständigkeit (lies diesen Teil)

Sei präzise darüber, was jede Schicht beweist — denn es sind unterschiedliche Behauptungen, und die Unterschiede sind der Punkt:

Eine selbst gehaltene Chain beweist **Integrität relativ zu einem etablierten Head**: Gegeben ein Chain-Head, den jemand bereits hält, wird jede Bearbeitung, Umordnung oder Löschung in den Datensätzen dahinter erkennbar. Für sich genommen — bevor jemand außerhalb des Betreibers einen Head gesehen hat — beweist eine Chain interne Konsistenz, nicht Historie: Ein Betreiber könnte einen Datensatz weglassen und neu versiegeln, und die neue Datei würde verifizieren. Die Chain wird **historisch festgeschrieben** in dem Moment, in dem ihr Head die Kontrolle des Betreibers verlässt.

Das ist der Witness: Eine Partei außerhalb des Betreibers, die periodische Checkpoints der Chain hält — die Subject-ID, eine Datensatzanzahl und zwei Chain-Fingerabdrücke (der Head und die Chain-Root); die exakte Payload, und nichts anderes. Checkpoints machen das Umschreiben festgeschriebener Historie erkennbar, und ein verpasster Checkpoint ist selbst ein sichtbares Ereignis:```
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` bestätigt, dass das Token an diesen Chain-Zustand gebunden ist, und liest dessen bestätigte Zeit, aber es validiert **nicht** die Signatur der TSA — das wird bewusst einem Standardwerkzeug überlassen, damit ein Prüfer keinem Code von uns vertrauen muss. Um die Zeit unabhängig zu verifizieren (das ist es, was Sie einem Sicherheitsprüfer aushändigen):```
# 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"

Keine Einstellung erzwingt dies — es ist eine Disziplin darin, wie du den Recorder aufrufst.
Es macht die Löschung handhabbar; es ist keine Anonymisierung, und es gibt noch keine
integrierte Aufbewahrung oder Bereinigung.
[LIMITS.md Abschnitt 13](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#13-personal-data-and-erasure) enthält die vollständige Feldliste,
erklärt, warum der gespeicherte Eingabe-Fingerabdruck einen erratbaren Wert bestätigen kann, selbst
nachdem die Zuordnung entfernt wurde, und endet mit Fragen, die ein Prüfer stellen sollte.

Zeichne einen Modellaufruf auf (die erste Frage des Käufers: „Welches Modell hat meine Daten gesehen?"):```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

Dies schreibt zwei Dateien für das Audit-Fenster: die CSV (eine Zeile pro aufgezeichneter Aktion, von links nach rechts gruppiert als *wann → was geschah → wer → unter welcher Berechtigung → was markiert wurde → Provenienz → wie zu verifizieren*, einschließlich einer redigierten Zusammenfassung des Aufrufs und seines Ergebnisses in einfacher Sprache, des Agent-Builds und -Modells, die jeweils erzeugt wurden, der Identität, in deren Namen er ausgeführt wurde, des Datensatzes, durch den er verursacht wurde, seiner Autorisierungsentscheidung und seines Geltungsbereichs sowie etwaiger Kategorien personenbezogener Daten oder aufgenommener Bedrohungsmarkierungen) und ein Manifest (`evidence.csv.manifest.json`), das die CSV mit ihrer Quelle verknüpft — der Head-Hash der Chain verbindet sie mit dem verifizierbaren Log, aus dem sie stammt, und `csv_sha256` ist der eigene Hash der exportierten Datei, sodass eine nach dem Export bearbeitete CSV nicht mehr zu ihrem Manifest passt. Grenzen Sie die Grundgesamtheit mit `--tool` ein, wenn eine Kontrolle nur bestimmte Aktionen abdeckt; das Manifest zeichnet den Filter auf, sodass ein eingegrenzter Export offenlegt, dass er eine Teilmenge ist, statt als die gesamte Grundgesamtheit gelesen zu werden. Laden Sie beide gegen Ihre Logging- oder Monitoring-Kontrolle hoch; fügen Sie den Runtime Report HTML bei, wenn ein Prüfer die Chain selbst verifizieren möchte. Der Export weigert sich, auf einer Chain zu laufen, die die Verifikation nicht besteht.

Eine native Push-Integration — bei der Evidenz automatisch in Ihrer Plattform landet — befindet sich auf der Roadmap. Der obige Dateipfad funktioniert heute mit jeder Plattform, die hochgeladene Evidenz akzeptiert.

## 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