[FEATURE] pre_chat.messages.transform hook for image-to-text stripping

[n1flh31mur]

Verification

• I have verified this feature request has not been suggested before (see Proposal: message.parts.before plugin hook for multimodal preflight #24125, system.transform fires after messages.transform — plugins can't coordinate system+message mutations #19960 — this issue proposes a unified approach combining their ideas)

Problem

Plugins cannot strip or transform messages before they reach the LLM. When a user attaches an image, the LLM errors out with "this model does not support image input".

The existing hooks have limitations:

• experimental.chat.messages.transform has input: {} — it never receives messages (system.transform fires after messages.transform — plugins can't coordinate system+message mutations #19960)
• Proposal: message.parts.before plugin hook for multimodal preflight #24125 proposes message.parts.before for image handling but it is not implemented
• No hook fires BEFORE the LLM is called

Proposed Solution

Add pre_chat.messages.transform — a hook that fires before the LLM, receiving the full messages array and allowing plugins to transform them:

"pre_chat.messages.transform"?: (
  input: {
    sessionID: string
    agent: string
    model: Model
    messages: { info: Message; parts: Part[] }[]
  },
  output: { messages: { info: Message; parts: Part[] }[] },
) => Promise<void>

Use Cases

1. Image-to-text stripping: Scan for FilePart with image: true, call a Vision server (Qwen2.5-VL-3B), replace with TextPart containing the description
2. Vision plugin integration: Transform messages on-the-fly so the LLM always receives text-only input
3. Pre-inference modification: Any plugin that needs to modify messages before the LLM

Backward Compatibility

• experimental.chat.messages.transform is non-functional (empty input). Marked @deprecated and replaced by this new hook
• No breaking changes to existing hooks

Required Go Binary Change (separate PR)

The Go binary needs to:

1. Register pre_chat.messages.transform hooks from the plugin registry
2. Call them with the messages array before invoking the LLM
3. Collect output.messages and pass the transformed array to the model

PR

SDK type changes: #25493

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• Feature requests must have a title starting with [FEATURE]: (current title: "feat(plugin): add pre_chat.messages.transform hook for image stripping")
• Feature requests must include the verification checkbox confirming the feature hasn't been suggested before

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• Proposal: message.parts.before plugin hook for multimodal preflight #24125: Very similar proposal — a plugin hook ("message.parts.before") to intercept and transform message parts (including images) before they reach the LLM
• system.transform fires after messages.transform — plugins can't coordinate system+message mutations #19960: Related issue about experimental.chat.messages.transform not receiving messages/context, which is the same root problem described here

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thanks for updating the issue! Everything looks good now — the title, verification checkbox, and description all meet our contributing guidelines.