# Hook event reference

Supported hosted lifecycle events, projected inputs, and return behavior.

Every handler receives `(event, ctx)`. The table shows the event-specific fields beyond `event.type`.

| Event                     | Event fields                                                       | Supported return                                              |
| ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| `before_agent_start`      | `prompt`, `images`, `systemPrompt`, `resources`                    | `{ messages?, systemPrompt? }`; may call model/tool selectors |
| `tool_call`               | `toolCallId`, `toolName`, `input`                                  | `{ block: true, reason? }`; input may be mutated in place     |
| `tool_result`             | `toolCallId`, `toolName`, `input`, `content`, `details`, `isError` | `{ content?, details?, isError?, terminate? }`                |
| `context`                 | `messages`                                                         | `{ messages }`                                                |
| `before_provider_request` | `model`, `sessionId`, `streamOptions`                              | `{ streamOptions }` patch                                     |
| `before_provider_payload` | `model`, `payload`                                                 | `{ payload }`                                                 |
| `after_provider_response` | `status`, `headers`                                                | Observation only                                              |
| `session_before_compact`  | `preparation`, `branchEntries`, `customInstructions`, `signal`     | `{ cancel?, compaction? }`                                    |
| `session_compact`         | `compactionEntry`, `fromHook`                                      | Observation only                                              |
| `model_update`            | `model`, `previousModel`, `source`                                 | Observation only                                              |
| `thinking_level_update`   | `level`, `previousLevel`                                           | Observation only                                              |

## Messages before the agent starts

`before_agent_start` may return `messages` to add structured Pi messages before the turn runs:

```js
return {
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Treat this turn as a support escalation." },
      ],
    },
  ],
};
```

Each item must be a valid Pi message object. When multiple handlers return messages, the extension host appends their arrays in handler registration order. These are additional pre-turn messages; they do not replace the current prompt. Use the `context` hook when you need to transform the complete model-context message array instead.

## Provider request patch

`before_provider_request` may patch `transport`, `timeoutMs`, `maxRetries`, `maxRetryDelayMs`, `headers`, `metadata`, and `cacheRetention`. Returning `undefined` leaves the request unchanged.

## Compaction override

```js
return {
  compaction: {
    summary: "Bounded session summary",
    firstKeptEntryId: "entry-id",
    tokensBefore: 12000,
    details: { strategy: "customer-extension" },
  },
};
```

Use compaction overrides only when the application owns a tested summarization strategy. The normal hosted runtime already performs native Pi compaction when required.