@package-system

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:

EventAllowed action
PostToolUseobserve only — it cannot change a result that already happened
StopforceContinue only
PrePromptinject 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.kindRuns today
callbackYes, 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.
scriptNo — it validates, then fails at dispatch with a "no script executor" error.
httpNo — 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.

On this page