audit

audit

session_id_for

session_id_for(evt: BaseHookEvent) -> str | None

Return a 12-char sha256 prefix of the transcript path, or None if unavailable.

audit

audit(
    events: Event = Event.PreToolUse
    | Event.PostToolUse
    | Event.Stop,
    *,
    log_dir: Path | str | None = None,
    filename: Callable[[datetime], str] = lambda d: (
        f"{d}.jsonl"
    ),
    fields: Callable[
        [BaseHookEvent], dict[str, Any]
    ] = default_fields,
    only_if: Sequence[TCondition] = (),
    skip_if: Sequence[TCondition] = (),
) -> None

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

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:

Name	Type	Description	Default
events	Event	Event mask to audit. Defaults to PreToolUse | PostToolUse | Stop.	PreToolUse | PostToolUse | Stop
log_dir	Path | str | None	Output directory. Defaults to $CLAUDE_PROJECT_DIR/.context/hook-logs.	None
filename	Callable[[datetime], str]	(datetime) -> str mapping a timestamp to a filename.	lambda d: f'{d}.jsonl'
fields	Callable[[BaseHookEvent], dict[str, Any]]	(evt) -> dict for the per-record payload.	default_fields
only_if	Sequence[TCondition]	Conditions that must match for the event to be recorded.	()
skip_if	Sequence[TCondition]	Conditions that, if matched, suppress recording.	()