Hook Audit Trails For Claude Code

Why Hooks Are Good Audit Boundaries

A transcript tells you what happened after the fact. A hook lets you capture, validate, enrich, or block activity while the session is running. Anthropic documents hook events that run once per session, once per turn, and on tool calls inside the agentic loop. That cadence maps cleanly to audit needs.

Use hooks when you need deterministic behavior around the model: write an event to a local audit file, require a ticket ID before destructive commands, notify a reviewer when a session stops, or capture a working-tree snapshot after a turn.

What To Record

A hook audit record should be smaller than the transcript and more structured than a free-text note. Record the session ID, event name, working directory, hook matcher, tool name, decision, timestamp, policy version, and a pointer to the transcript path. For tool inputs, record either a redacted summary or a hash unless your governance explicitly allows full content.

OWASP logging guidance favors deliberate event design over noisy catch-all logging. That principle matters with agent runs because prompts and tool inputs can contain secrets, customer data, or unreleased code.

• Always record policy decisions and denials.
• Record enough identifiers to correlate back to the transcript and OpenTelemetry event.
• Prefer redacted summaries over full prompts when audit goals do not require raw content.

Coverage Gaps To Design Around

A per-tool hook can miss state changes caused by shell commands unless it also observes Bash activity or scans the working tree at stop time. Anthropic hook guidance notes this tradeoff in examples for file-change coverage. The practical answer is layered capture: tool events for intent, git status for filesystem reality, and transcript links for context.

Subagents add another wrinkle. Record both the parent session and subagent identifiers. If you only store the parent transcript path, parallel work can collapse into an ambiguous blob during later review.

Keep Policy Scope Explicit

Claude Code settings have managed, user, project, and local scopes. That means two developers can run the same repository with different local behavior unless the team pins policy in the right place. Audit rows should include the policy source and version when possible.

For general settings and permission hardening, link to Claude Ships Code. On this site, the focus is the evidence produced by the hook layer.