feat: add PostTurn hook event for turn-level post-processing

[zhangxy-zju]

Summary

Add a new PostTurn hook event that fires at every model turn boundary (tool_call or end of response). Hook scripts receive the turn's accumulated thoughts, messages, and tool calls, and can optionally inject a message into the ACP stream with custom metadata.

Closes #3265

Changes (10 files, +319 lines)

Core hook framework (packages/core):

• types.ts: New PostTurn enum, PostTurnInput, PostTurnOutput, PostTurnHookOutput class with getAcpMessage() / getAcpMeta()
• hookEventHandler.ts: firePostTurnEvent()
• hookSystem.ts: Public firePostTurnEvent()
• hookAggregator.ts: PostTurn fire-and-forget handling (preserve outputs, ignore errors, first non-empty acpMessage wins)
• toolHookTriggers.ts: firePostTurnHook() via MessageBus
• config.ts: PostTurn case in MessageBus hook dispatcher

ACP integration (packages/cli):

• Session.ts: Accumulate turn content during streaming, fire-and-forget PostTurn hook at every turn boundary, pass through acpMessage + acpMeta to ACP stream
• settingsSchema.ts: PostTurn in hooks schema
• hooks/constants.ts: PostTurn descriptions and exit codes

Hook Protocol

Input (stdin JSON):

{
  "turn_index": 3,
  "thoughts": ["..."],
  "messages": ["..."],
  "tool_calls": [{ "name": "read_file", "args": { "file_path": "..." } }]
}

Output (stdout JSON):

{
  "decision": "allow",
  "hookSpecificOutput": {
    "hookEventName": "PostTurn",
    "acpMessage": "Message to inject into ACP stream",
    "acpMeta": { "custom": "metadata passed through as _meta" }
  }
}

Configuration

{
  "hooks": {
    "PostTurn": [{
      "hooks": [{
        "type": "command",
        "command": "python3 .qwen/hooks/my_script.py",
        "timeout": 30000
      }]
    }]
  }
}

Design Decisions

• Async fire-and-forget: Does not block agent execution
• ACP-only: Fires in Session path, not in non-interactive CLI mode
• Framework-agnostic metadata: acpMeta defined by hook scripts, framework passes through as-is
• Single hook limit: Multiple PostTurn hooks → first non-empty acpMessage wins
• Safe degradation: Hook failures silently ignored, original messages unaffected
• Backward compatible: Old qwen-code versions ignore unknown PostTurn hook config with zero side effects

Test plan

• TypeScript compilation passes
• ESLint passes
• Hook script unit test (stdin/stdout JSON protocol)
• End-to-end ACP eval with PostTurn hook (in progress)

[github-actions]

📋 Review Summary

This PR introduces a new PostTurn hook event that fires at every model turn boundary (after tool calls or end of response), allowing hook scripts to inject messages into the ACP stream with custom metadata. The implementation is well-architected with proper fire-and-forget semantics, backward compatibility, and consistent integration with the existing hook framework. Overall, this is a solid addition that extends the hook system's capabilities without disrupting existing functionality.

🔍 General Feedback

• Strong architectural consistency: The PostTurn hook follows the same patterns as existing hooks (PreToolUse, PostToolUse, etc.), making it easy to understand and maintain.
• Fire-and-forget design: The async, non-blocking approach with Promise.allSettled is appropriate for this use case and prevents hook failures from affecting agent execution.
• ACP-focused integration: The hook only fires in the Session path (not non-interactive CLI mode), which aligns with its purpose of injecting messages into the ACP stream.
• Clean separation of concerns: Core hook logic is in packages/core, while ACP-specific integration is in packages/cli.
• Comprehensive type safety: New types (PostTurnInput, PostTurnOutput, PostTurnHookOutput) are well-defined with proper validation.

🎯 Specific Feedback

🟡 High

1. File: packages/cli/src/acp-integration/session/Session.ts:343-347 - The accumulation logic for turnThoughts and turnMessages may have a bug. The condition if (part.thought) checks if the boolean flag is set, but then pushes part.text to turnThoughts. However, the else branch pushes to turnMessages for all non-thought parts, which could include non-text content. Consider adding explicit type checking:

   if (part.thought && part.text) {
     turnThoughts.push(part.text);
   } else if (part.text) {
     turnMessages.push(part.text);
   }

2. File: packages/core/src/hooks/hookAggregator.ts:58-83 - The PostTurn handling uses firstAcpOutput logic where "first non-empty acpMessage wins". However, the iteration order of results is not guaranteed to be deterministic if hooks run in parallel. If hook execution order matters, this should be documented or the implementation should preserve sequential execution order when the sequential flag is set.

🟢 Medium

3. File: packages/core/src/hooks/types.ts:385 - The getAcpMessage() method has a validation check msg.trim().length < 5 which silently returns undefined for messages shorter than 5 characters. This magic number should be either:

   • Documented with a comment explaining why 5 characters is the threshold
   • Made configurable
   • Changed to a more sensible minimum (e.g., 1 character)

   if (!msg || typeof msg !== 'string' || msg.trim().length < 5) {
     return undefined; // Why 5 characters?
   }

4. File: packages/cli/src/acp-integration/session/Session.ts:416-447 - The PostTurn hook firing creates a new async function that captures several variables. While this works, the pattern of pushing promises to pendingPostTurnHooks and awaiting them all at the end could be extracted into a helper method for better testability and readability.

5. File: packages/core/src/config/config.ts:959-972 - The PostTurn case in the MessageBus hook dispatcher uses inline type assertions for the input. Consider creating a type guard or validation function to ensure the input shape matches PostTurnInput before passing to firePostTurnEvent.

🔵 Low

6. File: packages/core/src/hooks/types.ts:49 - The HookEventName.PostTurn enum value should have a JSDoc comment consistent with other enum values (e.g., StopFailure, PreCompact).

7. File: packages/cli/src/ui/components/hooks/constants.ts:97-105 - The exit code descriptions for PostTurn could be more specific about what "Other" means in practice. Consider: { code: 'Other', description: t('hook failed or returned no acpMessage, stderr shown to user') }

8. File: packages/core/src/core/toolHookTriggers.ts:507 - The firePostTurnHook function has a catch block that returns {} on error. While this is the intended fire-and-forget behavior, adding a debug log call (like other hook triggers have) would help with troubleshooting:

   debugLogger.warn(
     `PostTurn hook error: ${error instanceof Error ? error.message : String(error)}`,
   );

   (Note: I see this is actually present at line 553-556 in the diff - this is already implemented correctly)

9. File: packages/core/src/index.ts:276-281 - The export comment says "Export hook triggers for notification and PostTurn hooks" but only exports fireNotificationHook, firePermissionRequestHook, and firePostTurnHook. Consider updating the comment to be more accurate or adding any missing exports.

✅ Highlights

• Excellent backward compatibility design: Old qwen-code versions will ignore unknown PostTurn hook config with zero side effects, as noted in the PR description.
• Robust error handling: Hook failures are silently ignored, ensuring the original agent flow is never disrupted.
• Well-documented hook protocol: The stdin/stdout JSON protocol is clearly defined in the PR body with examples.
• Comprehensive test coverage: The PR includes unit tests for the hook script JSON protocol.
• Smart ACP message injection: The acpMeta field allows hook scripts to attach arbitrary metadata that's passed through as _meta in the ACP stream, enabling rich extensibility.

[tanzhenxin]

Hey @zhangxy-zju Thanks for the PR!

Quick note — the existing hook framework already has PostToolUse (fires after each tool call) and Stop (fires at end of response), which together cover the same trigger points as PostTurn. The new parts here are the turn-level content aggregation and ACP message injection, but it's worth discussing whether those should be a new event or extensions to the existing ones.

Assigning @DennisYu07 to review since he's been leading the hook system work (#2827, #3248) and can best assess how this fits the architecture.

[DennisYu07]

Hey @zhangxy-zju Thanks for the PR!

Quick note — the existing hook framework already has PostToolUse (fires after each tool call) and Stop (fires at end of response), which together cover the same trigger points as PostTurn. The new parts here are the turn-level content aggregation and ACP message injection, but it's worth discussing whether those should be a new event or extensions to the existing ones.

Assigning @DennisYu07 to review since he's been leading the hook system work (#2827, #3248) and can best assess how this fits the architecture.

Agree with this, personally I think it is a little redundant.

[zhangxy-zju]

Closing for now — turn-level post-processing is currently supported via the ACP message rewrite middleware (#3191) as a temporary solution. We can revisit the hook-based approach when the middleware no longer meets our needs.