# Hooks (https://docs.neuralisapp.com/package-system/hooks)

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`).

```json
{
  "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 [#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 [#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](https://docs.neuralisapp.com/package-system.md#other-ecosystems).
