Hook Events Reference

Hooks are the internal transport layer between Claude Code and the Athena runtime. Claude Code fires hooks at lifecycle points; Athena's hook-forwarder binary receives them and streams them over a Unix Domain Socket as NDJSON.

Understanding hook events is useful for contributors and for understanding what data flows through the system.

How Hook Registration Works

At startup, Athena generates a temporary settings file that registers athena-hook-forwarder as the handler for all Claude Code hook events. This file is written to the OS temp directory and passed to Claude Code via --setting-sources. On exit, the temp file is cleaned up.

Hook Event Types

Claude Code exposes hook events in two categories based on whether they require a tool matcher.

Tool Events (require a `"*"` matcher)

These fire around tool invocations. Athena registers a wildcard matcher ("*") to receive all tool calls.

Hook Name	When it fires	Can block?
`PreToolUse`	Before Claude invokes a tool	Yes
`PostToolUse`	After a tool completes and returns its result	No
`PostToolUseFailure`	After a tool invocation results in an error	No
`PermissionRequest`	When Claude Code requests explicit permission	Yes

Non-Tool Events (no matcher required)

Hook Name	When it fires
`SessionStart`	When a new Claude Code session begins
`SessionEnd`	When a Claude Code session ends
`UserPromptSubmit`	When the user submits a prompt
`Stop`	When Claude Code's stop hook fires
`SubagentStart`	When a subagent session starts
`SubagentStop`	When a subagent session ends
`Notification`	Informational notifications from Claude Code
`PreCompact`	Before context compaction occurs
`Setup`	On session init or maintenance

Internal Event Kinds

Hook events are translated to Athena's internal RuntimeEventKind type before being processed:

Hook Name	RuntimeEventKind
`SessionStart`	`session.start`
`SessionEnd`	`session.end`
`UserPromptSubmit`	`user.prompt`
`PreToolUse`	`tool.pre`
`PostToolUse`	`tool.post`
`PostToolUseFailure`	`tool.failure`
`PermissionRequest`	`permission.request`
`Stop`	`stop.request`
`SubagentStart`	`subagent.start`
`SubagentStop`	`subagent.stop`
`Notification`	`notification`
`PreCompact`	`compact.pre`
`Setup`	`setup`

Events not in this table map to unknown.

Feed Event Kinds

The feed layer further expands runtime events into display events. The full set of FeedEventKind values includes: session.start, session.end, run.start, run.end, user.prompt, tool.pre, tool.post, tool.failure, permission.request, permission.decision, stop.request, stop.decision, subagent.start, subagent.stop, notification, compact.pre, setup, unknown.hook, todo.add, todo.update, todo.done, agent.message, teammate.idle, task.completed, config.change.

Blocking Events

Events that canBlock allow Athena to send a denial or modification decision back to Claude Code through the hook response. The key ones are PreToolUse and PermissionRequest. Athena's isolation policy evaluation runs on these events before responding.

Blocking decisions include: passthrough (allow), block (deny with reason), or json (structured response with intent).