Hooks
hooks — declarative lifecycle hooks a package attaches to tool calls, sessions and the prompt, validated at load.
A hook runs package code at a fixed point in an agent's life: before or after
a tool call, when a session starts or ends, when a run stops, or before the
prompt is sent. Hooks live in hooks.json at the package root, as
{ "hooks": [ … ] }, and inline hooks[] entries in the manifest merge with
the file (the file wins on the same id).
{
"hooks": [
{
"id": "audit-shell",
"event": "PostToolUse",
"handler": { "kind": "callback", "module": "@acme/ops/dist/hooks/audit.js", "export": "onToolUse" },
"conditions": { "toolNames": ["execute"] },
"config": { "action": "observe" },
"priority": 10
}
]
}Events and actions
Seven events are recognised: PreToolUse, PostToolUse, PostToolUseFailure,
SessionStart, SessionEnd, Stop and PrePrompt. An entry without an id,
or naming any other event, is skipped with a warning. Three events also limit
what the hook may declare as its config.action, checked at load:
| Event | Allowed action |
|---|---|
PostToolUse | observe only — it cannot change a result that already happened |
Stop | forceContinue only |
PrePrompt | inject only |
conditions.toolNames and conditions.toolFamilies narrow a tool hook to the
calls it cares about, and priority orders hooks on the same event. An invalid
entry is skipped; it never stops the package or the platform from starting.
Handlers
handler.kind | Runs today |
|---|---|
callback | Yes, for native packages: module is a path inside the package (<package id>/…) and export names the function. A module outside the package root, a missing export, or a package of any other trust resolves to no handler. |
script | No — it validates, then fails at dispatch with a "no script executor" error. |
http | No — it validates, then fails at dispatch with a "no HTTP executor" error. |
Hooks found in other ecosystems' layouts (Claude Code, Gemini and similar) are not imported; see the package system.