ai-hats-observe

A standalone session-logging engine: open a session on a bare directory, append trace entries, write an incremental audit, and finalize a versioned metrics.json — with no configuration, no worktree engine, and no ai-hats.yaml.

ai-hats-observe is the observability core extracted from the ai-hats framework (ADR-0014 Phase 1, T15). It has no dependency on the ai-hats integrator: everything below runs against a plain directory. Its only runtime dependency is ai-hats-core (dependency-free filesystem primitives + the migration seam).

What it owns

• Session lifecycle — SessionManager / Session: allocate a session directory, resolve its artifact paths, list/filter past sessions.
• Trace + audit writer — log_trace, init_audit, append_audit, finalize_audit; the enriched AuditWriter that turns a transcript into audit.md + a versioned metrics.json.
• Versioned trace/audit schema — a schema_version on the metrics surface, with a wired (initially empty) migration seam.
• Surface-agnostic parsing — a TranscriptParser adapter: the AuditWriter holds no provider-specific parsing; the concrete ClaudeParser (structured JSONL + trace-chrome fallback) is one implementation. A new surface (Gemini, or a future CLI) plugs in its own parser — the writer never changes.

Session privacy

New session directories are created with mode 0700. Sensitive artifacts are created and rewritten with mode 0600, including prompts, role materialization, traces, audits, metrics, transcripts, reasoning, usage, and raw PTY captures. These permissions are enforced independently of the caller's umask and apply to every provider that uses the observe session API. Existing session trees are not migrated or rewritten.

Extending to a new surface

The parser is carried by the session's provider, not a central registry: a Provider yields its TranscriptParser, and the integrator injects it into the AuditWriter. Adding a surface means shipping a parser that satisfies the TranscriptParser protocol and a provider that names it — no edit to ai-hats-observe internals.

Dependency direction

ai-hats-observe imports only ai-hats-core and the standard library. It never imports the ai-hats integrator; ai-hats imports from here. The boundary is enforced by an AST import-lint (test_observe_boundary.py).