{a}OS Concept — Lifecycle Hooks

Explainer

Hooks are deterministic extension points in an agent runtime. Code runs before or after a lifecycle event — a turn, tool call, file edit, session stop, or context compaction boundary — without any model decision required. That makes them different from MCP tools (which the model chooses to call) and from skills or workflows (which a human or agent invokes on demand).

Think of hooks like React lifecycle methods or Express middleware: they fire because of where you are in the lifecycle, not because anyone asked for them. That guarantee is exactly what makes them useful for ambient behavior — memory capture, auditing, heartbeat checks — that must happen reliably, not best-effort.

Mechanism vs Pattern — the key distinction

Hook, cron, and VS Code task are mechanisms (how something fires). Heartbeat is a pattern (what something does — quiet recurring check, clips findings). A heartbeat can be implemented via any of the three mechanisms.

Concept	Type	Trigger	Who runs it	Typical use
Hook	Mechanism	Lifecycle event (Stop, PostToolUse, SessionStart…)	Agent runtime (Claude Code harness)	Memory capture, audit, sentinel check on session end
Cron job	Mechanism	Fixed time interval (independent of sessions)	OS scheduler / task runner	Daily brief at 07:00, weekly repo health scan
VS Code Task	Mechanism	IDE events (folder open, build trigger, Ctrl+Shift+B)	VS Code task runner	Pre-build linting, launch scripts, rename queues
Skill	Capability unit	Manual (`/sentinel`) or agentic (model decides)	Human or model	On-demand audit, pipeline step, named tool
Workflow	Orchestration	Manual or agentic, multi-step sequence	Human or model	LinkedIn crucible, acquire-skill, post-ship checklist
Heartbeat	Pattern	Any recurring mechanism above	Whichever mechanism implements it	Sentinel clips violations every session end; brief every morning

Rule of thumb: If you need it to happen without anyone asking, use a hook (session-scoped) or cron (time-scoped). If you need it on demand, build a skill. If you need it to chain multiple skills, build a workflow.

Hook events (Claude Code)

Stop — fires when the session ends (close, /exit, compact). Use for ambient audits.
SessionStart — fires when a session opens. Use for context pre-fetch.
PostToolUse — fires after any tool call. Use for post-edit formatters, loggers.
PreToolUse — fires before any tool call. Use for guard checks, input validation.
PreCompact — fires before context compaction. Use for state capture.
UserPromptSubmit — fires when user submits. Use for routing or pre-processing.

Anti-Patterns

Relying on the model to remember to call a memory tool every turn — this degrades to best-effort instead of guaranteed behavior.
Using a hook for something that needs context from the model's reasoning — hooks run blind, outside the model's turn.
Putting blocking logic in a Stop hook — it delays session close for the user.

Mitigations

Attach memory operations to deterministic lifecycle hooks: pre-fetch before reasoning, capture outcomes after the turn, compress state before context loss.
Use async: true in the hook config for long-running operations that shouldn't block the lifecycle event.
Always add || true to hook commands so a failure doesn't surface as a harness error.

Lifecycle Hooks

Explainer

Mechanism vs Pattern — the key distinction

Hook events (Claude Code)

Anti-Patterns

Mitigations

Top Products

Related Concepts