# Hooks

> Make a command or a function of yours run at each moment of the agent's work: before a tool, when you send a message, when it finishes.

Building software · Updated: 2026-11-02 · version 2.0.145 · https://nobreiniers.com/en/help/hooks/

A hook is something of yours that runs by itself at a moment of the agent's work: before it uses a tool, when you send a message, when a turn ends. It can let the step through, block it, ask you for permission or add context.

## Where hooks come from

- **From a project:** the file `.osiris/hooks.json` in the project's folder.
- **From a plugin** you have turned on.
- **From another agent:** you bring them in from «Settings» › «Import», and they arrive turned off. See [Import from other agents](https://nobreiniers.com/en/help/import-from-other-agents/).

The first time a project brings hooks, the app asks you before it runs anything: the card says that the project, by its name, wants to run its own automatic steps on your Mac while you work in it, and lists those commands. If they change later, it asks again and they do not run until you approve the change. The same card lists what the project's settings files (`.claude/settings.json` and `.claude/settings.local.json`, in the folder and the folders above it up to the repository) let run or open without asking: those rules apply only after your yes for that folder, and a rule added later waits for your approval. What those files refuse or ask about always holds.

## A command hook

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [{ "type": "command", "command": "python3 hooks/guard.py" }]
      }
    ]
  }
}
```

The command gets the event as JSON on standard input. If it exits with code 2, it blocks the action and its message reaches the agent.

The moments used most:

| Event | When it runs |
|---|---|
| `SessionStart` | When a chat starts. |
| `Setup` | Right after the app makes a new working copy (a git worktree) for a chat or a helper: use it to install what the copy needs. It gets the folder of the copy and the folder it was made from. If it fails, the copy is still made and you are told. |
| `UserPromptSubmit` | When you send a message. |
| `PreToolUse` | Before the agent uses a tool. It can block it. |
| `PostToolUse` | After it uses it. |
| `Stop` | When the agent ends its turn. |
| `PreCompact` | Before the conversation is compacted. |

## A function hook

A function hook is JavaScript that runs inside the app, with no process to start. It takes the same decision as a command hook in a fraction of the time.

1. In your hooks file, use the type `function` and name the file:

```json
{ "type": "function", "file": "hooks/guard.js" }
```

2. Write the function. It gets the event and returns its decision:

```js
export default function (input) {
  const command = (input.tool_input || {}).command || "";
  if (command.startsWith("rm ")) {
    return { decision: "deny", reason: "This project deletes nothing from a command." };
  }
}
```

What it may return:

| Field | What it is for |
|---|---|
| `decision` | `allow`, `deny` or `block`. |
| `reason` | The why, which the agent reads. |
| `updatedInput` | The tool's input, corrected. |
| `additionalContext` | Text added to what the agent knows. |

If it returns nothing, the work goes on.

> **Note:** In our tests, the same decision before a tool took 0.24 ms as a function hook and 29 ms as a Python command hook (the median of each).

## What a function hook cannot do

- It sees none of your files, the network or other programs: it runs isolated, with the language alone.
- It can read text inside the project with `ctx.readFile`. It reaches the network only if the hooks file says `"network": true`.
- It has 50 ms of processor time per call (set it with `timeout`, from 5 ms to 5 s). If it runs over, it is stopped and decides nothing.
- An error of its own never breaks the turn: you see one line with the error and the work goes on.

## When a hook stops something

| Message | What happened |
|---|---|
| «One of your hooks did not let this message through: …» | A `UserPromptSubmit` hook blocked it. |
| «One of your hooks stopped this turn: …» | A hook asked to stop. |
| «One of your hooks did not let the context be compacted: …» | A `PreCompact` hook blocked it. |
