Browse documentation
Hook event reference
Supported hosted lifecycle events, projected inputs, and return behavior.
View MarkdownEvery 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:
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
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.