또는 고전적인 방식:```
pip install halo-record
halo demo --serve

`from halo import ...` 편의 심(shim)도 함께 제공되지만, PyPI의 `halo` 이름은 무관한 터미널 스피너 패키지에 속해 있으며, 해당 패키지가 설치되어 있으면 임포트에서 우선권을 가진다. `halo_record`는 모호하지 않으므로 예제에서는 이를 사용한다.

`log=`가 없으면 레코드는 `~/.halo/my-agent.jsonl`로 간다(에이전트당 체인 하나). 래퍼는 실행 경계를 봉인하며, 증거는 호출별 레코드에 남는다. 이를 프레임워크 어댑터(아래 매트릭스)로 캡처하거나 — 명시적으로 캡처할 수도 있으며, 이는 위임 링크가 어떻게 연결되는지도 보여준다:```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)

quickstart는 브라우저에서 자신의 에이전트 Runtime Report를 보고 있을 때 끝납니다. JSONL 파일만 받고 보고서를 받지 못했다면 뭔가 잘못된 것입니다: 이슈를 열어주세요.

### 검증 블록

가드레일이나 정책 계층이 해당 작업을 검사했다면, 그 판정이 레코드에 실릴 수 있습니다 — 게이트가 무엇을 결정했는지 기록하는 선택적 블록으로, 다른 모든 필드와 마찬가지로 해시 체인에 봉인됩니다:```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(...)`은 동일한 `verification=` 키워드를 받습니다. `status`는 블록 내에서 필수이며, `verifier`, `policy_ref`, `checked_at`은 선택 사항입니다. 각 상태의 의미는 다음과 같습니다:

| 상태 | 게이트가 보고하는 내용 | 작업이 실행되었는가? |
|---|---|---|
| `allowed` | 작업을 허용함 | 예 — 작업이 진행됨 |
| `blocked` | 작업을 거부함 | 이 필드가 아니라 통합에 의해 결정됨 — 레코드가 여전히 결과를 담고 있을 수 있으며, 차단만으로는 미실행을 입증하지 못함 |
| `modified` | 실행 전에 작업을 변경함 — `action.input`은 수정 후 **실행된 대로**의 작업을 설명함 | 예, 변경된 형태로 |
| `unverified` | 실행되었으나(또는 참조되었으나) 판단을 내리지 않음 — 검증 주장이 전혀 이루어지지 않았음을 의미하는 블록 부재와는 구별됨 | 예 — 판정 없이 작업이 진행됨 |

이 블록은 운영자의 통합 코드에 의해 제공되며, 게이트가 말했다고 보고하는 내용을 기록합니다 — `principal`과 동일한 신뢰 태세입니다([LIMITS](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#11-verification-status-is-the-gates-report-not-halos-finding) 참조). 봉인은 상태가 사후에 편집되지 않았음을 증명하지만, 검사가 발생했는지, 판정이 올바른지, 또는 차단된 작업이 실행되지 않았는지는 증명하지 않습니다. 이는 독립적인 검증이 아닙니다.

`policy_ref`를 증거로 사용할 수 있으려면 규칙 세트의 콘텐츠 해시를 사용하고 규칙 세트 아티팩트를 보관하십시오 — 해석할 수 없는 레이블은 해당 필드를 장식적으로 만듭니다.

## 이미 실행 중인 것에 연결하기

| 경계에서 캡처됨 | 기존 텔레메트리에서 수집됨 |
|---|---|
| 네이티브 레코더 (`from halo_record import trace`) | OpenTelemetry GenAI 스팬 |
| MCP 인터셉터 | LiteLLM 콜백 |
| LangChain / LangGraph 콜백 | Langfuse 내보내기 |
| OpenAI Agents SDK 훅 | 모든 게이트웨이 / 리버스 프록시 로그 |
| Claude Agent SDK 훅 | Claude Code 및 Codex CLI `PostToolUse` 훅 (도구 실행 후 발동) |

프레임워크 어댑터와 수집 경로는 각 레코드에 `source` 태그를 찍으므로, 보고서는 각 증거가 어떻게 수집되었는지 공개합니다. 캡처된 레코드와 수집된 레코드는 동일한 체인에 존재합니다.

LangChain / LangGraph의 경우, 이는 콜백 핸들러입니다:```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

게이트웨이 또는 프록시 로그(Cloudflare AI Gateway, Portkey, 모델 앞단의 nginx)의 경우, 로그 행을 체인에 매핑합니다 — 경계에서 캡처된 것이 아니라 수집된 것으로 명시적으로 태그됩니다:```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"})

`~/.claude/settings.json`에 추가하면 레코드가 `~/.halo/audit.jsonl`에 기록됩니다(`$HALO_LOG`로 재정의 가능). 데이터, 네트워크, 외부 상태에 접근하지 않는 순수 오케스트레이션 도구는 건너뜁니다 — 이 체인은 사고가 아니라 신뢰 경계를 넘는 행위를 기록합니다. `HALO_HASH_ONLY=1`을 설정하면 요약 없이 콘텐츠 해시만 기록합니다. `HALO_AGENT_VERSION`(그리고 선택적으로 `HALO_AGENT_MODEL`)을 설정하면 모든 레코드를 이를 생성한 에이전트 빌드에 바인딩합니다 — 감사자가 특정 기간에 실행 중이던 버전을 물을 때, 내보내기는 기억이 아니라 컬럼으로 답합니다.

Codex CLI는 동일한 이벤트 형태로 동일한 라이프사이클 훅을 제공합니다(훅은 기본적으로 활성화됨). 다음을 `~/.codex/hooks.json`에 추가하면 Codex의 셸 명령, `apply_patch` 편집, MCP 호출이 동일한 체인에 기록됩니다:```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

| `-s` | `--server` | `SERVER` | `http://localhost:8080` | 서버 URL |
| `-t` | `--token` | `TOKEN` | | 인증 토큰 |
| `-o` | `--output` | `OUTPUT` | | 출력 파일 |
| `-f` | `--format` | `FORMAT` | `json` | 출력 형식 |
| `-v` | `--verbose` | | | 상세 출력 |
| `-q` | `--quiet` | | | 조용한 모드 |
| `-h` | `--help` | | | 도움말 표시 |
| `-V` | `--version` | | | 버전 표시 |

### 예제

```bash
# 기본 사용법
tool --server http://localhost:8080

# 인증 포함
tool --server http://localhost:8080 --token abc123

# 출력 형식 지정
tool --output results.json --format json

# 상세 모드
tool --verbose --server http://localhost:8080

server: http://localhost:8080
token: your-token-here
format: json
verbose: false
timeout: 30

# 고급 설정
advanced:
  retry_count: 3
  retry_delay: 5
  max_connections: 10

# 서버가 실행 중인지 확인
curl http://localhost:8080/health

# 포트가 사용 중인지 확인
netstat -tulpn | grep 8080

# 토큰 확인
tool --server http://localhost:8080 --token $TOKEN --verbose

# 파일 권한 확인
ls -la /path/to/file

# 권한 수정
chmod 644 /path/to/file

# 환경 변수 사용
export TOOL_DEBUG=true
tool --server http://localhost:8080

# 또는 명령줄 플래그 사용
tool --debug --server http://localhost:8080

# 저장소 복제
git clone https://github.com/example/tool.git
cd tool

# 가상 환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt
pip install -r requirements-dev.txt

# 테스트 실행
pytest tests/

스냅샷은 액션 레코드와 동일한 해시 체인에 봉인됩니다. 좋은 기본값은 시작 시 세션 수준 스냅샷 하나를 만들고, 규칙, Skills, 훅, MCP 도구 레지스트리 또는 컴팩션 정책이 변경될 때 새 스냅샷을 만드는 것입니다. 긴 세션을 간결하게 유지하기 위해 동일한 `authority.snapshot_id`를 가진 연속 레코드는 첫 번째 전체 스냅샷 이후에 컴팩션됩니다. 이후 레코드는 `{"snapshot_id": "...", "same_as_previous": true}`만 유지합니다. 포인터는 해시 체인으로 유지되지만, 부피가 큰 refs/omissions/stale-if 블록은 모든 액션마다 반복되지 않습니다. (컴팩션은 레코더 프로세스별로 이루어집니다. 도구 호출마다 하나의 프로세스를 생성하는 훅 스타일 캡처는 이전 전체 스냅샷이 꼬리 레코드가 아닐 때마다 전체 본문을 다시 저장하므로, 단명 프로세스는 재사용 가드를 위해 체인 크기를 희생합니다.)

SDK 사용자는 동일한 블록을 직접 붙입니다 — `build(..., authority={...})` 또는 `record_call(..., authority={...})`; 해시 전용 캡처도 동일한 표면입니다(이들 중 어느 것이든 `summaries=False`):```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")

post-action 훅을 노출하는 모든 에이전트 런타임은 동일한 명령을 공급할 수 있습니다 — 훅은 stdin으로 JSON 형식의 이벤트 하나를 읽고 레코드 하나를 추가합니다.

하나의 체인, 한 번에 하나의 작성자. 체인은 연결 리스트입니다: 같은 head를 읽고 둘 다 추가하는 두 작성자는 체인을 분기시키며(같은 선행자를 주장하는 두 레코드), 검증은 영향을 받은 레코드의 이름을 밝힙니다. `Recorder`는 사이드카 잠금(여기서는 POSIX `flock`; TypeScript 패키지에서는 잠금 디렉터리)으로 자체 추가를 직렬화하며, `halo hook`은 `Recorder`를 통해 추가하므로 위의 훅 설정은 보호됩니다. 체인 파일에 직접 쓰는 모든 것 — 직접 만든 훅, 병렬 워커, 로그 전송기 — 은 head 읽기 후 추가 시퀀스 전반에 걸쳐 동등한 배타적 잠금을 보유하거나 프로세스별 체인에 기록해야 합니다. [LIMITS.md 섹션 9](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#9-single-writer-chains)는 언어 간 경계를 포함하여 이 내용을 전부 다룹니다.

## 기록이 실패할 때

두 통합 스타일은 의도적으로 반대 방향으로 실패합니다 — 감당할 수 있는 실패를 선택하세요:

- **프레임워크 어댑터(LangChain, 콜백 관리자를 통한 훅)는 열린 상태로 실패합니다.** 레코드를 쓸 수 없으면(디스크 가득 참, 권한), 에이전트의 작업은 정상적으로 완료되고 레코드는 손실됩니다. LangChain 핸들러는 stderr에 큰 경고를 출력하고 손실을 집계하지만(`handler.lost_records`), 체인 자체에서는 결코 기록되지 않은 레코드를 보여줄 수 없습니다 — 멈춘 체인도 여전히 검증됩니다. 주기적인 witness 체크포인트가 멈춘 체인을 가시화합니다: 도착하지 않는 예상 체크포인트가 경보입니다.
- **네이티브 `trace()` 래퍼는 닫힌 상태로 실패합니다.** 레코드를 쓸 수 없으면 예외가 에이전트의 작업으로 전파됩니다 — 증거 없으면 작업도 없습니다. 더 엄격하며, 에이전트를 중단시킬 수 있습니다.

어느 기본값도 모든 사람에게 맞지는 않습니다; 자신이 어느 것을 실행 중인지 알아두세요.

## 무결성 vs. 완전성 (이 부분을 읽으세요)

각 계층이 무엇을 증명하는지 정확히 파악하세요 — 서로 다른 주장이며, 그 차이가 핵심입니다:

자체 보유 체인은 **확립된 head에 대한 무결성**을 증명합니다: 누군가 이미 보유한 체인 head가 주어지면, 그 뒤의 레코드에 대한 모든 편집, 재정렬, 삭제가 탐지 가능해집니다. 그 자체로 — 운영자 외부의 누군가가 head를 보기 전에는 — 체인은 내부 일관성을 증명할 뿐, 이력을 증명하지 않습니다: 운영자는 레코드를 삭제하고 다시 봉인할 수 있으며, 새 파일은 검증을 통과합니다. 체인은 그 head가 운영자의 통제를 벗어나는 순간 **역사적으로 커밋**됩니다.

그것이 witness입니다: 체인의 주기적 체크포인트를 보유한 운영자 외부의 당사자 — subject id, 레코드 수, 두 개의 체인 지문(head와 체인 루트); 정확한 페이로드, 그 외에는 아무것도. 체크포인트는 커밋된 이력의 재작성을 탐지 가능하게 만들며, 놓친 체크포인트 자체가 가시적인 이벤트입니다:```
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`는 토큰이 이 체인 상태에 바인딩되어 있는지 확인하고 증명된 시간을 읽지만, TSA의 서명을 **검증하지는 않습니다** — 이는 의도적으로 표준 도구에 맡겨, 검토자가 우리 코드를 신뢰하지 않도록 한 것입니다. 시간을 독립적으로 검증하려면(보안 검토자에게 건네는 것이 바로 이것입니다):```
# 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"

이를 강제하는 설정은 없습니다 — 기록기를 어떻게 호출하는지에 관한 규율입니다.
이는 삭제를 다루기 쉽게 만들 뿐이며, 익명화가 아니고, 아직 내장된
보존 기간이나 정리 기능도 없습니다.
[LIMITS.md 섹션 13](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#13-personal-data-and-erasure)에 전체 필드
목록이 있고, 매핑이 사라진 뒤에도 저장된 입력 지문이 추측 가능한 값을 확인할 수 있는
이유를 설명하며, 검토자가 물어야 할 질문들로 끝맺습니다.

모델 호출을 기록하세요 (구매자의 첫 번째 질문: "어떤 모델이 내 데이터를 보았나?"):```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

이것은 감사 창(audit window)에 대해 두 개의 파일을 작성합니다: CSV(기록된 각 작업당 한 행으로, 왼쪽에서 오른쪽으로 *언제 → 무슨 일이 있었는지 → 누가 → 어떤 권한으로 → 무엇이 플래그되었는지 → 출처 → 검증 방법* 순으로 그룹화되며, 호출과 그 결과에 대한 수정된 평이한 언어 요약, 각각을 생성한 에이전트 빌드와 모델, 그것이 대신하여 실행된 신원, 그것을 유발한 레코드, 그 승인 결정과 범위, 그리고 모든 개인 데이터 범주 또는 수집된 위협 플래그를 포함합니다)와 CSV를 그 출처에 연결하는 매니페스트(`evidence.csv.manifest.json`)입니다 — 체인의 헤드 해시는 그것을 그것이 나온 검증 가능한 로그에 연결하고, `csv_sha256`은 내보낸 파일 자체의 해시이므로, 내보낸 후 편집된 CSV는 더 이상 매니페스트와 일치하지 않습니다. 통제가 특정 작업만을 포괄할 때는 `--tool`로 모집단을 좁히십시오; 매니페스트는 필터를 기록하므로, 범위가 지정된 내보내기는 전체 모집단으로 읽히는 대신 그것이 부분집합임을 공개합니다. 둘 다 로깅 또는 모니터링 통제에 대해 업로드하십시오; 검토자가 체인을 직접 검증하고자 할 때는 Runtime Report HTML을 첨부하십시오. 내보내기는 검증에 실패한 체인에서는 실행을 거부합니다.

네이티브 푸시 통합 — 증거가 귀하의 플랫폼에 자동으로 도착하는 것 — 은 로드맵에 있습니다. 위의 파일 경로는 업로드된 증거를 수용하는 모든 플랫폼에서 오늘날 작동합니다.

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