What are agent hooks?

A hook is a lifecycle seam

An agent harness already has named transitions: a session starts, a user submits a goal, the model proposes a tool call, policy asks for permission, a tool returns, context is compacted, and the run attempts to stop. Hooks expose selected transitions to user or project code.

flowchart LR
  S[Session start] --> U[User input]
  U --> B[Before tool]
  B --> X[Tool execution]
  X --> A[After tool]
  A --> C[Compaction]
  C --> T[Stop attempt]
  H[Matching hook handlers] -. observe, add context, allow, or block .-> B
  H -. validate or record .-> A
  H -. verify completion .-> T

The harness owns the event contract: when it fires, which fields it supplies, which handler types are allowed, whether handlers run concurrently, how long they may run, and whether their output can block or modify the transition.

Event position determines capability

A session-start hook can load a small piece of local context, initialize instrumentation, or check environment state. It runs before ordinary work and should be fast and repeatable.

A pre-tool hook sees a proposed operation before execution. Depending on the product contract, it may allow, deny, rewrite, request approval, or attach context. This is the useful seam for deterministic command policy—but only if the hook's decision is authoritative for that exact execution path.

A post-tool hook observes a result after the effect boundary. It can format files, scan output, record telemetry, or add feedback for the next model call. Blocking after execution cannot undo an effect that already happened.

A stop hook runs when the agent is about to finish. It can check required artifacts or tests and return a reason to continue. It should have a termination rule; a hook that always rejects stop creates an infinite loop rather than persistence.

Compaction and subagent events expose other boundaries. Their exact names and powers differ across harnesses, so configuration is not portable merely because two products use the word “hook.”

Hooks are not prompts, tools, or skills

A prompt tells the model how to behave, and the model may interpret it differently across runs. A deterministic command hook runs because the lifecycle event occurred, whether or not the model remembered to ask for it.

A tool is normally selected or proposed by the model as part of the task. A hook is selected by runtime configuration because an event matched. A skill packages reusable instructions and resources; a hook reacts to runtime transitions. An agent-based hook may itself call a model, but then its judgement is probabilistic and should be described and evaluated as such.

Hooks can create memory by summarising or persisting events, but the hook is the trigger and handler. The resulting store, write policy, retention, and later retrieval are the memory system.

Executable configuration is a trust boundary

Hooks may run shell commands, local programs, HTTP calls, or MCP tools with the environment and credentials of the host. Treat installing or changing one like changing application code:

• review the exact source and resolved command;
• bind project hooks to a trusted repository or policy layer;
• use absolute or project-root-resolved paths;
• pass structured arguments without unsafe shell interpolation;
• minimize inherited secrets and filesystem or network access;
• constrain output size, duration, and destinations;
• record the handler version and event identity.

A malicious repository hook can exfiltrate data before the model performs any tool call. A well-intentioned formatter can overwrite user changes. Trust prompts and warning banners are helpful controls, not substitutes for operating-system permissions and least privilege.

Design for repetition, concurrency, and failure

Events may repeat after retries, resumes, compaction, parallel tool calls, or subagent work. Give side-effecting handlers stable event IDs or idempotency keys. A notification can tolerate duplication; a deployment or database mutation may not.

If matching handlers run concurrently, do not assume one validator finishes before another handler starts. Put critical authorization in the single execution gate or define explicit ordering in a workflow engine.

Choose a failure policy per event. A telemetry hook may fail open so work continues. A secret-scanning or authorization hook may need to fail closed. A post-tool formatter failure should report that formatting is incomplete, not pretend that the underlying tool did not run. Timeouts, malformed output, crashes, and unavailable MCP servers need observable states.

Verify the event contract

Test hook code as ordinary software and test the harness integration with fixed event fixtures. Cover matcher boundaries, structured input parsing, path resolution, hostile strings, concurrent events, duplicate delivery, timeout, non-zero exit, invalid output, and disabled or untrusted configuration.

Then run one small end-to-end trace for each consequential hook: prove a forbidden call produces no effect, a post-tool failure does not erase the known tool outcome, and a stop check allows completion once its evidence becomes true. The valuable property is not “the hook ran”; it is that the lifecycle transition followed the declared contract.