audit()

Register a hook that appends one JSONL record per matching event.

Usage

Source

audit(
    events=Event.PreToolUse | Event.PostToolUse | Event.Stop,
    *,
    log_dir=None,
    filename=lambda d: f"{d}.jsonl",
    fields=default_fields,
    only_if=(),
    skip_if=()
)

Each matching event writes a single line to <log_dir>/<filename(now)>. Default fields are ts, event, tool, file, and session_id (a 12-char sha256 prefix of the transcript path).

Example

from captain_hook import audit, Event audit(Event.PreToolUse | Event.PostToolUse | Event.Stop)

Parameters

events: Event = Event.PreToolUse | Event.PostToolUse | Event.Stop


Event mask to audit. Defaults to PreToolUse | PostToolUse | Stop.

log_dir: Path | str | None = None

Output directory. Defaults to $CLAUDE_PROJECT_DIR/.context/hook-logs.

filename: Callable[[datetime], str] = lambda d: f"{d}.jsonl"


(datetime) -> str mapping a timestamp to a filename.

fields: Callable[[BaseHookEvent], dict[str, Any]] = default_fields


(evt) -> dict for the per-record payload.

only_if: Sequence[TCondition] = ()


Conditions that must match for the event to be recorded.

skip_if: Sequence[TCondition] = ()


Conditions that, if matched, suppress recording.