claude-code - 💡(How to fix) Fix Feature: UserPromptSubmit hook should support prompt replacement via `replaceUserMessage` field [2 comments, 2 participants]

Problem

UserPromptSubmit hooks can only append context (additionalContext) or block the prompt entirely. There is no way to replace the prompt text before it reaches Claude.

This makes it impossible to build token-efficient prompt transformation plugins — for example, a translation plugin that receives verbose English input and sends a compact Chinese equivalent to the model.

Current workaround: inject the translated text as additionalContext + instruct Claude to treat it as authoritative. But the original English still consumes tokens in the user turn. The overhead negates the savings for short prompts.

Proposed solution

Add an optional replaceUserMessage field to the UserPromptSubmit hook output:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "replaceUserMessage": "替换后的提示文本"
  }
}

Behavior:

• The original user message is replaced by replaceUserMessage before being sent to Claude
• The replacement is shown in the transcript (or marked as [transformed]) for auditability
• If replaceUserMessage is empty or omitted, behavior is unchanged (passthrough)
• Compatible with additionalContext (both can be returned together)

Use case

A translation plugin (TRmnl) intercepts English prompts, translates to Chinese via DeepL, and sends only the Chinese to Claude. Chinese expresses the same semantic content in ~40–60% fewer tokens for long prompts. The plugin works end-to-end today except the English leaks through because replacement isn't possible.

Same pattern applies to: prompt compression, PII redaction, template expansion, and any preprocessing pipeline that needs to transform input before model inference.

Current workaround limitation

// Can only do this — English still sent:
{ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: "Chinese: ..." } }

// Want to do this — English replaced entirely:
{ hookSpecificOutput: { hookEventName: "UserPromptSubmit", replaceUserMessage: "Chinese text only" } }

Impact

Unlocks a whole class of input-transformation plugins that are currently impossible to build correctly on the Claude Code plugin platform.