Manu's Vault

Hooks-Agent-Lifecycle

3 min readStatus:Seedling

Hooks are user-defined scripts or commands that execute automatically at defined points in an agent’s lifecycle. Within a coding agent harness, hooks provide the imperative control layer: while AGENTS.md files and skills offer declarative configuration, hooks enforce deterministic behaviour regardless of what the model would otherwise choose to do.

The conceptual predecessor is Aspect-Oriented Programming (AOP) — separating cross-cutting concerns (logging, validation, notifications) from core task logic. Hooks apply the same principle to agent sessions: insert verification, enforcement, or integration logic at the seam between the agent and the environment, without modifying agent instructions.

Lifecycle Events

Modern coding agents expose a rich set of lifecycle events for hook attachment. Claude Code (as of 2026) defines 24+ events:

  • Pre-execution: PreToolUse (fires before a tool runs; can block it), PermissionRequest (fires before a permission dialog)
  • Post-execution: PostToolUse (fires after a tool succeeds), PostToolUseFailure (fires after a tool fails)
  • Session boundaries: SessionStart (including on resume or post-compaction), SessionEnd
  • Context management: PreCompact, PostCompact, InstructionsLoaded
  • Agent coordination: SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle
  • Attention and control: Notification (Claude needs input), Stop (Claude finished responding), UserPromptSubmit
  • Environment reactivity: CwdChanged, FileChanged, ConfigChange, WorktreeCreate, WorktreeRemove

Cursor v1.7 introduced an equivalent system (beforeShellExecution, afterFileEdit, stop) confirming hooks as a convergent pattern across coding agent platforms.

Control Flow Modes

Hooks communicate intent via exit codes and structured output:

  • Exit 0: allow — action proceeds. Stdout injected into Claude’s context for SessionStart and UserPromptSubmit events
  • Exit 2: block — action cancelled. Stderr message fed back to the agent as feedback, enabling self-correction
  • JSON output (structured): PreToolUse supports allow / deny / ask; Stop and PostToolUse support decision: "block" — enabling finer-grained semantics than exit codes alone
  • Hook types: command (shell), http (POST to endpoint), prompt (LLM single-turn evaluation), agent (subagent with tool access for complex verification)

Practical Patterns

  • Silent-success / verbose-failure: a type-check hook that succeeds silently and surfaces only errors forces the agent to resolve issues before stopping — the core CI-gate pattern
  • Auto-format: PostToolUse on Edit|Write events runs Prettier or Black without agent involvement
  • Notification on idle: Notification hook sends a desktop alert when Claude needs input, freeing the developer to context-switch
  • Context re-injection after compaction: SessionStart with compact matcher injects reminders (sprint goal, toolchain conventions) that would otherwise be lost
  • Blocking dangerous commands: PreToolUse on Bash can block DROP TABLE, rm -rf, or migration commands that exceed the agent’s authorised scope

Security Surface

Hooks run with the same OS permissions as the user. This is necessary for their power but creates risk: hooks can exfiltrate data, modify the environment, or escalate privilege. Enterprise deployments scope hooks via managed policy settings; team-shared hooks should be treated as code review artefacts.

Sources

Note

This note was researched and drafted with AI. How these notes are written →

Graph View

Backlinks