Manu's Vault

Hooks-Agent-Lifecycle

4 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 content was drafted with assistance from AI tools for research, organisation, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.

Graph View

Backlinks