Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/users/features/hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
| `UserPromptSubmit` | After user submits prompt | None (always fires) |
| `SessionStart` | When session starts or resumes | Source (`startup`, `resume`, `clear`, `compact`) |
| `SessionEnd` | When session ends | Reason (`clear`, `logout`, `prompt_input_exit`, etc.) |
| `MessageDisplay` | Repeatedly, as the reply streams | None (always fires) |
| `Stop` | When Claude prepares to conclude response | None (always fires) |
| `SubagentStart` | When subagent starts | Agent type (`Bash`, `Explorer`, `Plan`, etc.) |
| `SubagentStop` | When subagent stops | Agent type |
Expand All @@ -267,6 +268,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
| Todo Events | `TodoCreated`, `TodoCompleted` | ❌ No | N/A |
| Prompt Events | `UserPromptSubmit` | ❌ No | N/A |
| Stop Events | `Stop` | ❌ No | N/A |
| Message Display | `MessageDisplay` | ❌ No | N/A |

**Matcher Syntax:**

Expand Down Expand Up @@ -563,6 +565,24 @@ The `permissionDecision` value controls whether the tool runs:

- Standard hook output fields (typically not used for blocking)

#### MessageDisplay

**Purpose**: Fires repeatedly as the assistant's reply streams — before `Stop`, which fires once at the end of the turn. Useful for live narration, incremental logging, or any consumer that wants to react to the reply as it's written rather than after the fact. This is a **fire-and-forget** event - hook output and exit codes are ignored.

**Event-specific fields**:

```json
{
"message_id": "stable id for the whole streamed message",
"displayed_text": "the CUMULATIVE text streamed so far for this message (not a delta)",
"is_final": "true on the last firing for this message, false otherwise"
}
```

`displayed_text` is cumulative rather than a delta so hook scripts never need to reassemble chunks themselves — each firing carries the full text so far. Firing is debounced (at most every ~200ms) except for the final firing (`is_final: true`), which always fires immediately once the message ends, so the reply's tail is never dropped waiting on the debounce window.

**Note**: Fires in both the terminal UI and ACP (IDE/editor) sessions — they share the same underlying streaming event loop.

#### Stop

**Purpose**: Executed before Qwen concludes its response to provide final feedback or summaries.
Expand Down
3 changes: 3 additions & 0 deletions packages/acp-bridge/src/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -936,6 +936,9 @@ export const IDLE_HOOK_EVENTS: Record<HookEventName, ServeHookEventMeta> = {
description: 'When a new session is started',
matcherKind: 'sessionTrigger',
},
MessageDisplay: {
description: 'Repeatedly, as the assistant reply streams',
},
Stop: { description: 'Right before Qwen Code concludes its response' },
SubagentStart: {
description: 'When a subagent is started',
Expand Down
12 changes: 12 additions & 0 deletions packages/cli/src/config/settingsSchema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2889,6 +2889,18 @@ const SETTINGS_SCHEMA = {
mergeStrategy: MergeStrategy.CONCAT,
items: HOOK_DEFINITION_ITEMS,
},
MessageDisplay: {
type: 'array',
label: 'Message Display Hooks',
category: 'Advanced',
requiresRestart: false,
default: [],
description:
'Hooks that execute repeatedly as the assistant reply streams, before the After Agent (Stop) hooks fire.',
showInDialog: false,
mergeStrategy: MergeStrategy.CONCAT,
items: HOOK_DEFINITION_ITEMS,
},
Notification: {
type: 'array',
label: 'Notification Hooks',
Expand Down
16 changes: 16 additions & 0 deletions packages/cli/src/ui/components/hooks/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,16 @@ export function getHookExitCodes(eventName: string): HookExitCode[] {
{ code: 2, description: t('show stderr to model immediately') },
{ code: 'Other', description: t('show stderr to user only') },
],
[HookEventName.MessageDisplay]: [
{
code: 0,
description: t('fire-and-forget; exit status is ignored'),
},
{
code: 'Other',
description: t('fire-and-forget; exit status is ignored'),
},
],
[HookEventName.Notification]: [
{ code: 0, description: t('stdout/stderr not shown') },
{ code: 'Other', description: t('show stderr to user only') },
Expand Down Expand Up @@ -171,6 +181,9 @@ export function getHookShortDescription(eventName: string): string {
'When a slash command expands into a prompt',
),
[HookEventName.SessionStart]: t('When a new session is started'),
[HookEventName.MessageDisplay]: t(
'Repeatedly, as the assistant reply streams',
),
[HookEventName.Stop]: t('Right before Qwen Code concludes its response'),
[HookEventName.SubagentStart]: t(
'When a subagent (Agent tool call) is started',
Expand Down Expand Up @@ -229,6 +242,9 @@ export function getHookDescription(eventName: string): string {
[HookEventName.SessionStart]: t(
'Input to command is JSON with session start source.',
),
[HookEventName.MessageDisplay]: t(
'Input to command is JSON with message_id, displayed_text (cumulative text streamed so far), and is_final. Fire-and-forget: output and exit status are ignored.',
),
[HookEventName.SessionEnd]: t(
'Input to command is JSON with session end reason.',
),
Expand Down
16 changes: 16 additions & 0 deletions packages/core/src/config/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2154,6 +2154,22 @@ export class Config {
stopHookCount = stopResult.allOutputs.length;
break;
}
case 'MessageDisplay': {
const messageDisplayResult =
await hookSystem.fireMessageDisplayEvent(
(input['message_id'] as string) || '',
(input['displayed_text'] as string) || '',
(input['is_final'] as boolean) || false,
signal,
);
result = messageDisplayResult.finalOutput
? createHookOutput(
'MessageDisplay',
messageDisplayResult.finalOutput,
)
: undefined;
break;
}
case 'PreToolUse': {
result = await hookSystem.firePreToolUseEvent(
(input['tool_name'] as string) || '',
Expand Down
Loading
Loading