Audit Logging

You want a per-day record of every tool the agent invoked, what file it touched, and which session it came from, so you can investigate incidents after the fact, build a usage dashboard, or just spot-check what the agent has been doing.

from __future__ import annotations

from captain_hook import Event, FilePath, audit

audit(Event.PreToolUse | Event.PostToolUse | Event.Stop)

audit(
    Event.PostToolUse,
    log_dir="logs/hooks",
    filename=lambda d: f"{d:%Y-%m-%dT%H}.jsonl",
    fields=lambda evt: {
        "event": evt.event_name.name,
        "tool": evt.tool_name,
        "agent": evt.agent_type,
        "file": str(evt.file.path) if evt.file else None,
    },
    only_if=[FilePath("**/*.py")],
)

What to learn: audit() is the no-result primitive that drops one JSONL line per matching event under $CLAUDE_PROJECT_DIR/.context/hook-logs/. Customize the destination with log_dir / filename, and the record shape with fields. Combine only_if=[FilePath(...)] to scope the audit to one slice of activity.