Hook component: lifecycle event handlers

A Hook component packages logic that fires automatically when the agent runtime reaches a specific lifecycle event. Unlike Commands (user-triggered) or Tools (agent-triggered), hooks are reactive — the runtime invokes them in response to events like session start, tool use, or file changes. You don’t call a hook directly; you configure it for an event and the runtime fires it when that event occurs.

Entrypoint format

Hook entrypoints can be:

Markdown (.md) — with YAML frontmatter describing the event and hook type
YAML (.yaml) — a descriptor with event and type fields
Executable script — any regular executable file

The portable validation minimum requires:

The entrypoint file exists and is a regular file.
The descriptor declares or implies a canonical lifecycle event from the vocabulary below.
The descriptor declares one of the three valid hook types: command, script, or module.

Lifecycle events

Hooks can fire on any of the following canonical lifecycle events:

Session events

SessionStart, SessionEnd, Setup

User interaction events

UserPromptSubmit, Stop, StopFailure

Tool events

PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch

Agent events

SubagentStart, SubagentStop, TaskCreated, TaskCompleted

Context events

InstructionsLoaded, PreCompact, PostCompact

Environment events

ConfigChange, CwdChanged, FileChanged

A hook that declares an event outside this canonical vocabulary is a validation failure.

Hook types

Three hook types define how the hook executes:

Type	Description
`command`	A shell command string executed by the runtime.
`script`	An executable file run as a subprocess.
`module`	A Node.js or Python module loaded and called.

Required descriptor fields

For Markdown and YAML hook entrypoints, the descriptor must include:

Field	Required	Description
`event`	Yes	One canonical lifecycle event from the vocabulary above.
`type`	Yes	One of: `command`, `script`, `module`.

Markdown hook with frontmatter

---
event: PostToolUse
type: script
---

Log every tool call result for audit purposes.

YAML hook descriptor

event: SessionStart
type: command
command: echo "Session started at $(date)" >> ~/.agent-sessions.log

Declaring a hook in `volume.toml`

Add a [[components]] entry with type = "hook" and point entrypoint to your hook file.

[[components]]
type = "hook"
name = "session-logger"
entrypoint = "./hooks/session-logger.md"
description = "Log session start and end events for audit purposes"

A volume that exports several hooks for different lifecycle stages:

[volume]
schema = 1
name = "audit-hooks-pack"
version = "1.0.0"
description = "Lifecycle hooks for session auditing and file change tracking"
license = "Apache-2.0"
role = "plugin"

[publisher]
id = "example"

[[components]]
type = "hook"
name = "session-logger"
entrypoint = "./hooks/session-logger.yaml"
description = "Log session start and end timestamps"

[[components]]
type = "hook"
name = "tool-auditor"
entrypoint = "./hooks/tool-auditor.md"
description = "Record every tool invocation and its result"

[[components]]
type = "hook"
name = "file-watcher"
entrypoint = "./hooks/file-watcher.md"
description = "React to file changes in the working directory"

[permissions]
filesystem = "write"
shell = "allow"

Common hook patterns

SessionStart
PreToolUse
PostToolUse
FileChanged

Run setup logic when a new session begins — initialize state, load configuration, or log the session.

event: SessionStart
type: command
command: mkdir -p ~/.agent-logs && echo "$(date): session started" >> ~/.agent-logs/sessions.log

Inspect or gate a tool call before it executes — useful for logging, approval workflows, or enforcing policies.

---
event: PreToolUse
type: script
---

Before executing any tool, validate that the requested operation is permitted
under the current session's policy configuration.

Process the result of a tool call — write audit records, trigger follow-up actions, or update state.

---
event: PostToolUse
type: module
---

After each tool call, append the tool name, inputs, and result summary to the
session audit log.

React when files in the working directory change — trigger reloads, run checks, or notify other systems.

event: FileChanged
type: script

Validation requirements

A hook entrypoint fails portable validation if any of these conditions are true:

The file does not exist or is not a regular file.
The descriptor cannot be parsed.
The event field declares a lifecycle event outside the canonical vocabulary.
The type field declares a hook type other than command, script, or module.

Use PreToolUse and PostToolUse hooks for cross-cutting concerns like logging and auditing. These fire for every tool call, giving you a consistent observation point without modifying individual tool definitions.

Component identifier

Once published, reference the hook using a purl identifier:

pkg:volume/audit-hooks-pack@1.0.0#hook/session-logger

Documentation Index

​Entrypoint format

​Lifecycle events

Session events

User interaction events

Tool events

Agent events

Context events

Environment events

​Hook types

​Required descriptor fields

​Markdown hook with frontmatter

​YAML hook descriptor

​Declaring a hook in volume.toml

​Common hook patterns

​Validation requirements

​Component identifier

Entrypoint format

Lifecycle events

Hook types

Required descriptor fields

Markdown hook with frontmatter

YAML hook descriptor

Declaring a hook in `volume.toml`

Common hook patterns

Validation requirements

Component identifier