Plugins & Hooks

New in 0.10.0

The plugin/hook layer is a lower-level extension mechanism than Conversation guardrails — the built-in Cognipeer Console and Portkey guardrail integrations are themselves implemented as plugins on top of it. This page covers what's confirmed as of 0.10.2; see the release notes for the exact fix history.

A plugin extends the agent runtime through three kinds of extension point:

Kind	Behavior
Hooks	Intercept a lifecycle point; multiple plugins chain in registration order.
Contributions	Add to something (e.g. tool definitions); multiple plugins accumulate.
Strategy slots	Replace a default implementation; exactly one plugin may own a given slot.

There are 13 hooks across the runtime lifecycle. Three are named directly in the 0.10.x fix history:

• userPromptSubmit — fires when a user turn is submitted, before the model sees it. This is the hook a prompt-level guardrail denies on; a deny sets ctx.__guardrailBlocked so a caller can tell a blocked turn from a normal completed one.
• preToolUse — fires before a tool call executes. Can allow, deny, or ask (route to approval); a deny under a tool-based structured-output strategy stops the loop from making a further call.
• postToolUse — fires after a tool call executes, including on a preToolUse short-circuit or a cache hit — this is the hook a redaction/audit plugin uses to see (and mask) tool output before it lands in the transcript.

Multimodal input is carried through every hook: a plugin that rewrites text touches only the text parts of a message, so attachments (images, files, audio) survive untouched.

pluginCapabilities() reports which hooks, contributions, and strategy slots are actually wired up for the current agent, so an unimplemented extension point is explicit rather than silently a no-op.

Built-in plugins

25 built-in plugins ship with the SDK, including guardrail bridges for the Cognipeer Console (the same guardrail hook plane the Console dashboard configures) and Portkey.

Snapshots and handoffs

Plugin state participates in snapshot() / resume the same way agent state does — a checkpointing plugin runs at the same lifecycle points as everything else, so a failureMode: "open" plugin that swallows an error will silently skip a checkpoint rather than fail the run. On a handoff, the target agent's persona is rebuilt on the wire per model call rather than written into the transcript, so plugin-visible state doesn't leak the wrong persona into a later turn.