Inbound interception, reply takeover, and outbound delivery policy. Part of the Plugin hooks guide.

Message hooks

For inbound interception, before_dispatch receives the incoming message before ordinary model dispatch. Return { handled: true, text: "..." } to send a final reply, or { handled: true } to handle it without text. This is a claim, not an API for rewriting outbound or inbound content.

reply_dispatch is the advanced takeover seam: it receives the finalized message context and a host dispatcher, and a handled result reports queuedFinal and delivery counts. Use before_agent_reply for a simple synthetic reply, and the sending hooks below to transform outgoing payloads.

Runtime takeovers should forward ctx.onAgentRunStart, ctx.userTurnTranscriptRecorder, and optional ctx.prepareAssistantTranscriptMessage to their runtime helper. The ACP dispatch helper forwards all three automatically. Share the recorder so the runtime and Gateway do not append the same user turn independently; mark runtime persistence only after a successful transcript write.

The host-provided preparer records display ownership before the canonical assistant append, using original runtime text captured before transcript-only hooks. It preserves raw content and IDs and grants no file access or write authority. Keep it in process and bound to its owning turn; after that turn aborts, is replaced, or completes, it returns the message unchanged.

The optional third onAgentRunStart argument can offer completionSource: "reply-dispatch" with a getResult() callback. The host must return "reply-dispatch" synchronously to accept completion ownership; observers and other callback results leave lifecycle completion unchanged. Wrappers must forward every callback argument and its return value. After dispatch settles, getResult() supplies the canonical terminalOutcome and, when an assistant write succeeded, its assistantTranscript receipt (target, message ID, idempotency key, and optional projection anchor). The host then emits one chat completion from the delivered, post-hook payloads while retaining runtime lifecycle events. A receipt prevents a duplicate append; it does not authorize writes to a replaced session. Omit this declaration for runtimes whose event stream already owns chat completion.

Use eligibleDispatchKinds: ["acp"] for an ACP-only dispatcher. The host classifies the resolved target, including conversation bindings, and passes ctx.dispatchKind as acp or agent. Stored ACP metadata and ACP session keys both select acp; a missing ACP binding does not fall back to agent dispatch. The host applies the same eligibility check before invocation and when deciding whether a hook prevents durable chat admission. An ACP-only hook therefore does not block ordinary agent sessions. Omitted, empty, malformed, or partly unknown eligibility lists remain unrestricted. Missing or unknown dispatch context also keeps the hook eligible.

Use message hooks for channel-level routing and delivery policy:

For audio-only TTS replies, content may contain the hidden spoken transcript even when the channel payload has no visible text/caption. Rewriting that content updates the hook-visible transcript only; it is not rendered as a media caption.

reply_payload_sending events may include usageState, a best-effort live per-turn model/usage/context snapshot. Durable delivery, recovered replay, and replies without exact run correlation omit it.

Message hook contexts expose stable correlation fields when available: ctx.sessionKey, ctx.runId, ctx.messageId, ctx.senderId, ctx.trace, ctx.traceId, ctx.spanId, ctx.parentSpanId, and ctx.callDepth. Inbound and before_dispatch contexts also expose reply metadata when the channel has visibility-filtered quoted message data: replyToId, replyToIdFull, replyToBody, replyToSender, and replyToIsQuote. Prefer these first-class fields before reading legacy metadata.

before_dispatch receives the canonical inbound messageId in both its event and context.

Prefer typed threadId and replyToId fields before using channel-specific metadata.

Inbound claim and message-received events expose media?: PluginHookMediaFact[] as the canonical attachment API. Each fact can carry path, url, contentType, kind, transcribed, messageId, and workspaceDir; array position is attachment identity. When a remote attachment has not been staged locally yet, media is omitted, mediaStagingPending: true, and originalMedia contains the provider-side facts. Do not treat originalMedia.path as locally readable until a later staged event supplies media.

The singular/plural mediaPath, mediaUrl, mediaType, mediaPaths, mediaUrls, mediaTypes, and matching originalMedia* metadata properties are deprecated compatibility aliases. New hooks should use the typed top-level arrays.

Decision rules: