Every handler receives (event, ctx). The table shows the event-specific fields beyond event.type.
EventEvent fieldsSupported return
before_agent_startprompt, images, systemPrompt, resources{ messages?, systemPrompt? }; may call model/tool selectors
tool_calltoolCallId, toolName, input{ block: true, reason? }; input may be mutated in place
tool_resulttoolCallId, toolName, input, content, details, isError{ content?, details?, isError?, terminate? }
contextmessages{ messages }
before_provider_requestmodel, sessionId, streamOptions{ streamOptions } patch
before_provider_payloadmodel, payload{ payload }
after_provider_responsestatus, headersObservation only
session_before_compactpreparation, branchEntries, customInstructions, signal{ cancel?, compaction? }
session_compactcompactionEntry, fromHookObservation only
model_updatemodel, previousModel, sourceObservation only
thinking_level_updatelevel, previousLevelObservation 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.