Hooks & Permissions

Hooks are how Athena observes and controls agent runtimes. Each harness fires events at lifecycle points; Athena receives and processes them. The examples below use Claude Code's hook system, but the same event types are available on Codex via its event translation layer.

Hook Protocol

Claude Code → stdin JSON → athena-hook-forwarder → UDS NDJSON → Athena runtime

For events that expect a decision (interaction.expectsDecision: true), Athena writes a response back through the socket before the forwarder exits. Exit code 0 = passthrough, exit code 2 = block.

Auto-passthrough timeout: 5 seconds (5 minutes for permission/question events).

Hook Event Types

Tool Events (require `"*"` matcher)

Hook Name	RuntimeEventKind	Can Block
`PreToolUse`	`tool.pre`	Yes
`PostToolUse`	`tool.post`	No
`PostToolUseFailure`	`tool.failure`	No
`PermissionRequest`	`permission.request`	Yes

Non-Tool Events

Hook Name	RuntimeEventKind
`SessionStart`	`session.start`
`SessionEnd`	`session.end`
`UserPromptSubmit`	`user.prompt`
`Stop`	`stop.request`
`SubagentStart`	`subagent.start`
`SubagentStop`	`subagent.stop`
`Notification`	`notification`
`PreCompact`	`compact.pre`
`Setup`	`setup`

Blocking Decisions

Events marked "Can Block" allow Athena to respond before the agent proceeds:

passthrough — allow the action
block — deny with a reason string
json — structured response with intent

Athena's isolation policy evaluates tool.pre and permission.request events automatically. Decisions with source: 'rule' are auto-applied; decisions requiring user input pause the feed.

Isolation Presets

Control what the agent is allowed to do per-session:

Preset	MCP Servers	Allowed Tools
`strict`	Blocked	`Read`, `Edit`, `Glob`, `Grep`, `Bash`, `Write`
`minimal`	Project servers	Above + `WebSearch`, `WebFetch`, `Task`, `Skill`, `mcp__*`
`permissive`	Project servers	Above + `NotebookEdit`

All presets use --setting-sources "" to fully isolate from Claude Code's own settings file. Tool enforcement is done via PreToolUse hooks, so Athena retains visibility over every tool call.

athena-flow --isolation=minimal

Workflows can declare an isolation preset. If the workflow requires a more permissive level than the user's setting, Athena upgrades it with a warning.