feat: 新增 AssistantRender hook 事件，支持 LLM 输出显示层重渲染

src/commands/clear/caches.ts

@@ -29,6 +29,7 @@ import { clearCommandPrefixCaches } from '../../utils/bash/commands.js'
 import { resetGetMemoryFilesCache } from '../../utils/claudemd.js'
 import { clearRepositoryCaches } from '../../utils/detectRepository.js'
 import { clearResolveGitDirCache } from '../../utils/git/gitFilesystem.js'
+import { clearRenderCache } from '../../utils/hooks/renderCache.js'
 import { clearStoredImagePaths } from '../../utils/imageStore.js'
 import { clearSessionEnvVars } from '../../utils/sessionEnvVars.js'
 
@@ -86,6 +87,9 @@ export function clearSessionCaches(
   // Clear stored image paths cache
   clearStoredImagePaths()
 
+  // 清空 AssistantRender 显示层渲染缓存与重绘纪元（/clear、resume 时全部失效）
+  clearRenderCache()
+
   // Clear all session ingress caches (lastUuidMap, sequentialAppendBySession)
   clearAllSessions()
   // Clear swarm permission pending callbacks

src/components/MessageRow.tsx

@@ -59,6 +59,8 @@ export type Props = {
   onOpenRateLimitOptions?: () => void;
   lastThinkingBlockId: string | null;
   latestBashOutputUUID: string | null;
+  /** AssistantRender 渲染缓存版本号（由 Messages.tsx 下发，变化时强制重绘） */
+  renderCacheVersion: number;
   columns: number;
   isLoading: boolean;
   lookups: ReturnType<typeof buildMessageLookups>;
@@ -310,6 +312,11 @@ export function areMessageRowPropsEqual(prev: Props, next: Props): boolean {
   const nextIsLatestBash = next.latestBashOutputUUID === next.message.uuid;
   if (prevIsLatestBash !== nextIsLatestBash) return false;
 
+  // AssistantRender 渲染缓存版本变化（hook 命中或清除）时强制重绘。
+  // 注意不能用 getMessageRenderCacheState(prev/next.message) 对比：
+  // prev/next 持同一 message 引用，两次查询拿到的是同一份实时缓存态，恒等。
+  if (prev.renderCacheVersion !== next.renderCacheVersion) return false;
+
   // lastThinkingBlockId affects thinking block visibility — but only for
   // messages that HAVE thinking content. Checking unconditionally busts the
   // memo for every scrollback message whenever thinking starts/stops (CC-941).

src/components/Messages.tsx

@@ -56,6 +56,7 @@ import { Divider } from '@anthropic/ink';
 import type { UnseenDivider } from './FullscreenLayout.js';
 import { LogoV2 } from './LogoV2/LogoV2.js';
 import { StreamingMarkdown } from './Markdown.js';
+import { getRenderCacheVersion, getRepaintEpoch } from '../utils/hooks/renderCache.js';
 import { hasContentAfterIndex, MessageRow } from './MessageRow.js';
 import {
   InVirtualListContext,
@@ -781,7 +782,15 @@ const MessagesImpl = ({
     return () => progress(null);
   }, [progress]);
 
-  const messageKey = useCallback((msg: RenderableMessage) => `${msg.uuid}-${conversationId}`, [conversationId]);
+  // AssistantRender 重绘纪元并入行 key：命中的行 key 变化 → 重挂载，
+  // 绕过 React.memo 与 OffscreenFreeze（静态定格行对 prop 变化免疫）
+  const messageKey = useCallback(
+    (msg: RenderableMessage) => {
+      const epoch = getRepaintEpoch(msg.uuid);
+      return epoch > 0 ? `${msg.uuid}-${conversationId}-r${epoch}` : `${msg.uuid}-${conversationId}`;
+    },
+    [conversationId],
+  );
 
   const renderMessageRow = (msg: RenderableMessage, index: number) => {
     const prevType = index > 0 ? renderableMessages[index - 1]?.type : undefined;
@@ -817,6 +826,7 @@ const MessagesImpl = ({
         onOpenRateLimitOptions={onOpenRateLimitOptions}
         lastThinkingBlockId={lastThinkingBlockId}
         latestBashOutputUUID={latestBashOutputUUID}
+        renderCacheVersion={getRenderCacheVersion()}
         columns={columns}
         isLoading={isLoading}
         lookups={lookups}

src/components/__tests__/MessageRowRenderCache.test.tsx

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+import { randomUUID } from 'crypto';
+import type { RenderableMessage } from 'src/types/message.js';
+import { areMessageRowPropsEqual } from 'src/components/MessageRow.js';
+import { clearRenderCache, getRenderCacheVersion, setMessageRenderCache } from 'src/utils/hooks/renderCache.js';
+
+function assistantMessage(text: string): RenderableMessage {
+  return {
+    type: 'assistant',
+    uuid: randomUUID(),
+    message: {
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+    },
+  } as unknown as RenderableMessage;
+}
+
+// 最小 Props：比较器只消费其中少数字段，其余以空值填充
+function makeProps(message: RenderableMessage, renderCacheVersion = 0) {
+  return {
+    message,
+    isUserContinuation: false,
+    hasContentAfter: false,
+    tools: [],
+    commands: [],
+    verbose: false,
+    inProgressToolUseIDs: new Set<string>(),
+    streamingToolUseIDs: new Set<string>(),
+    screen: 'main',
+    canAnimate: false,
+    lastThinkingBlockId: null,
+    latestBashOutputUUID: null,
+    renderCacheVersion,
+    columns: 80,
+    isLoading: false,
+    lookups: { resolvedToolUseIDs: new Set<string>() },
+  } as unknown as Parameters<typeof areMessageRowPropsEqual>[0];
+}
+
+describe('areMessageRowPropsEqual (AssistantRender cache version)', () => {
+  test('renderCacheVersion bump forces re-render', () => {
+    clearRenderCache();
+    const message = assistantMessage('render-target');
+    const prev = makeProps(message, getRenderCacheVersion());
+    expect(areMessageRowPropsEqual(prev, prev)).toBe(true);
+    setMessageRenderCache('render-target', 'ASCII');
+    const next = makeProps(message, getRenderCacheVersion());
+    expect(areMessageRowPropsEqual(prev, next)).toBe(false);
+  });
+
+  test('same renderCacheVersion with static message bails out', () => {
+    clearRenderCache();
+    setMessageRenderCache('stable', 'ASCII');
+    const version = getRenderCacheVersion();
+    const message = assistantMessage('stable');
+    const prev = makeProps(message, version);
+    const next = makeProps(message, version);
+    expect(areMessageRowPropsEqual(prev, next)).toBe(true);
+  });
+});

src/components/messages/AssistantTextMessage.tsx

@@ -18,6 +18,7 @@ import {
   TOKEN_REVOKED_ERROR_MESSAGE,
 } from '../../services/api/errors.js';
 import { isEmptyMessageText, NO_RESPONSE_REQUESTED } from '../../utils/messages.js';
+import { getCachedRenderedText } from '../../utils/hooks/renderCache.js';
 import { getUpgradeMessage } from '../../utils/model/contextWindowUpgradeCheck.js';
 import { getDefaultSonnetModel, renderModelName } from '../../utils/model/model.js';
 import { isMacOsKeychainLocked } from '../../utils/secureStorage/macOsKeychainStorage.js';
@@ -30,6 +31,15 @@ import { RateLimitMessage } from './RateLimitMessage.js';
 
 const MAX_API_ERROR_CHARS = 1000;
 
+// 显示层降级：渲染缓存查取异常时回退原文
+function getRenderedText(text: string): string | undefined {
+  try {
+    return getCachedRenderedText(text);
+  } catch {
+    return undefined;
+  }
+}
+
 type Props = {
   param: TextBlockParam;
   addMargin: boolean;
@@ -60,6 +70,8 @@ export function AssistantTextMessage({
   onOpenRateLimitOptions,
 }: Props): React.ReactNode {
   const isSelected = useContext(MessageActionsSelectedContext);
+  // AssistantRender 缓存命中时用 hook 重渲染文本替换原文显示
+  const renderedText = getRenderedText(text);
   if (isEmptyMessageText(text)) {
     return null;
   }
@@ -187,7 +199,7 @@ export function AssistantTextMessage({
               </NoSelect>
             )}
             <Box flexDirection="column">
-              <Markdown>{text}</Markdown>
+              <Markdown>{renderedText ?? text}</Markdown>
             </Box>
           </Box>
         </Box>

src/components/messages/nullRenderingAttachments.ts

@@ -14,6 +14,7 @@ import type { Message, NormalizedMessage } from '../../types/message.js'
 const NULL_RENDERING_TYPES = [
   'hook_success',
   'hook_additional_context',
+  'hook_output_rendered',
   'hook_cancelled',
   'command_permissions',
   'agent_mention',

src/entrypoints/agentSdkTypes.js

@@ -29,6 +29,7 @@ export const HOOK_EVENTS = [
   'InstructionsLoaded',
   'CwdChanged',
   'FileChanged',
+  'AssistantRender',
 ]
 
 export const EXIT_REASONS = [

src/entrypoints/sdk/coreSchemas.ts

@@ -387,6 +387,7 @@ export const HOOK_EVENTS = [
   'InstructionsLoaded',
   'CwdChanged',
   'FileChanged',
+  'AssistantRender',
 ] as const
 
 export const HookEventSchema = lazySchema(() => z.enum(HOOK_EVENTS))
@@ -771,6 +772,31 @@ export const SessionEndHookInputSchema = lazySchema(() =>
   ),
 )
 
+// AssistantRender 事件输入：回合末 assistant 消息的非空 text 块原文
+export const AssistantRenderHookInputSchema = lazySchema(() =>
+  BaseHookInputSchema().and(
+    z.object({
+      hook_event_name: z.literal('AssistantRender'),
+      message_id: z
+        .string()
+        .optional()
+        .describe(
+          'API message id (msg_...) of the assistant message being rendered',
+        ),
+      text_blocks: z
+        .array(
+          z.object({
+            block_index: z.number().int(),
+            text: z.string(),
+          }),
+        )
+        .describe(
+          'Non-empty text content blocks of the assistant message, in order',
+        ),
+    }),
+  ),
+)
+
 export const HookInputSchema = lazySchema(() =>
   z.union([
     PreToolUseHookInputSchema(),
@@ -800,6 +826,7 @@ export const HookInputSchema = lazySchema(() =>
     WorktreeRemoveHookInputSchema(),
     CwdChangedHookInputSchema(),
     FileChangedHookInputSchema(),
+    AssistantRenderHookInputSchema(),
   ]),
 )
 
@@ -911,6 +938,28 @@ export const FileChangedHookSpecificOutputSchema = lazySchema(() =>
   }),
 )
 
+// AssistantRender 事件输出：updatedBlocks 提供对应 text 块的显示层替换文本
+export const AssistantRenderHookSpecificOutputSchema = lazySchema(() =>
+  z
+    .object({
+      hookEventName: z.literal('AssistantRender'),
+      updatedBlocks: z
+        .array(
+          z.object({
+            blockIndex: z.number().int(),
+            text: z.string(),
+          }),
+        )
+        .optional()
+        .describe(
+          'Re-rendered replacement text for the requested text blocks. Blocks not listed are displayed unchanged.',
+        ),
+    })
+    .describe(
+      'Hook-specific output for the AssistantRender event. Return this to replace the display-layer text of assistant message blocks; transcript and model context keep the original text.',
+    ),
+)
+
 export const SyncHookJSONOutputSchema = lazySchema(() =>
   z.object({
     continue: z.boolean().optional(),
@@ -936,6 +985,7 @@ export const SyncHookJSONOutputSchema = lazySchema(() =>
         CwdChangedHookSpecificOutputSchema(),
         FileChangedHookSpecificOutputSchema(),
         WorktreeCreateHookSpecificOutputSchema(),
+        AssistantRenderHookSpecificOutputSchema(),
       ])
       .optional(),
   }),

src/entrypoints/sdk/coreTypes.generated.ts

@@ -250,6 +250,11 @@ export type HookInput =
       file_path: string
       event: 'change' | 'add' | 'unlink'
     })
+  | (HookInputBase & {
+      hook_event_name: 'AssistantRender'
+      message_id?: string
+      text_blocks: { block_index: number; text: string }[]
+    })
 
 export type AsyncHookJSONOutput = {
   async: true
@@ -315,6 +320,10 @@ export type SyncHookJSONOutput = {
     | { hookEventName: 'CwdChanged'; watchPaths?: string[] }
     | { hookEventName: 'FileChanged'; watchPaths?: string[] }
     | { hookEventName: 'WorktreeCreate'; worktreePath: string }
+    | {
+        hookEventName: 'AssistantRender'
+        updatedBlocks?: { blockIndex: number; text: string }[]
+      }
 }
 
 export type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
@@ -330,6 +339,11 @@ export type SessionStartHookInput = HookInput
 export type SessionEndHookInput = HookInput & { exit_reason: string }
 export type SetupHookInput = HookInput
 export type StopHookInput = HookInput
+export type AssistantRenderHookInput = HookInput & {
+  hook_event_name: 'AssistantRender'
+  message_id?: string
+  text_blocks: { block_index: number; text: string }[]
+}
 export type StopFailureHookInput = HookInput
 export type SubagentStartHookInput = HookInput
 export type SubagentStopHookInput = HookInput

src/entrypoints/sdk/coreTypes.ts

@@ -50,6 +50,7 @@ export const HOOK_EVENTS = [
   'InstructionsLoaded',
   'CwdChanged',
   'FileChanged',
+  'AssistantRender',
 ] as const
 
 export const EXIT_REASONS = [

src/query.ts

@@ -4,6 +4,7 @@ import type {
   ToolUseBlock,
 } from '@anthropic-ai/sdk/resources/index.mjs'
 import type { CanUseToolFn } from './hooks/useCanUseTool.js'
+import { randomUUID } from 'crypto'
 import { FallbackTriggeredError } from './services/api/withRetry.js'
 import {
   calculateTokenWarningState,
@@ -101,7 +102,10 @@ import { ESCALATED_MAX_TOKENS } from './utils/context.js'
 import { getFeatureValue_CACHED_MAY_BE_STALE } from './services/analytics/growthbook.js'
 import { SLEEP_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/SleepTool/prompt.js'
 import { executePostSamplingHooks } from './utils/hooks/postSamplingHooks.js'
-import { executeStopFailureHooks } from './utils/hooks.js'
+import {
+  executeAssistantRenderHooks,
+  executeStopFailureHooks,
+} from './utils/hooks.js'
 import type { QuerySource } from './constants/querySource.js'
 import type { QueuedCommand } from './types/textInputTypes.js'
 import { createDumpPromptsFetch } from './services/api/dumpPrompts.js'
@@ -1565,6 +1569,27 @@ async function* queryLoop(
         stopHookActive,
       )
 
+      // AssistantRender：回合末对 assistant 输出做显示层重渲染（第 28 个 hook 事件）。
+      // 必须排在 Stop hooks 之后：mermaid 类插件的 Stop 钩子负责把渲染产物落盘，
+      // 本事件随后读取产物回填显示缓存——放之前会同回合读不到产物，永远滞后一回合。
+      // 命中时 yield 零渲染附件触发状态更新 → Ink 重绘 → 组件读渲染缓存就地替换。
+      if (!toolUseContext.abortController.signal.aborted) {
+        const renderedBlocks = await executeAssistantRenderHooks(
+          assistantMessages,
+          toolUseContext,
+        )
+        if (renderedBlocks > 0) {
+          yield createAttachmentMessage({
+            type: 'hook_output_rendered',
+            message: `${renderedBlocks} text block(s) re-rendered`,
+            count: renderedBlocks,
+            hookName: 'AssistantRender',
+            toolUseID: randomUUID(),
+            hookEvent: 'AssistantRender',
+          })
+        }
+      }
+
       if (stopHookResult.preventContinuation) {
         return { reason: 'stop_hook_prevented' }
       }

src/types/hooks.ts

@@ -160,6 +160,18 @@ export const syncHookResponseSchema = lazySchema(() =>
           hookEventName: z.literal('WorktreeCreate'),
           worktreePath: z.string(),
         }),
+        // AssistantRender：显示层重渲染 assistant text 块（transcript/模型上下文保留原文）
+        z.object({
+          hookEventName: z.literal('AssistantRender'),
+          updatedBlocks: z
+            .array(
+              z.object({
+                blockIndex: z.number().int(),
+                text: z.string(),
+              }),
+            )
+            .optional(),
+        }),
       ])
       .optional(),
   }),