Feat/hooks

[vladislavdonchev]

Hook System Implementation - PR

Hey! This is a DRAFT, just floating the idea around (while testing it).
Interested to see what you guys think!

Summary

This pull request introduces a comprehensive hook system to Qwen Code, enabling users to execute custom scripts at key points in the application lifecycle. The implementation includes:

• Complete hook system with HookManager, HookService, and configuration
• 17 different hook types covering app lifecycle, tool execution, model interaction, file operations, and error handling
• Support for hooks to execute any application via shell command execution
• Claude Code hook format compatibility with event mapping
• Claude-compatible hook execution with stdin/stdout communication
• Support for both script file and inline hook definitions
• Security measures for external script execution
• New integration test suite for Claude-compatible hooks
• Configuration files for event, tool name, and tool input format mappings

TLDR

This PR adds a powerful hook system that allows executing custom scripts at 17 different lifecycle events in Qwen Code. The system maintains full compatibility with Claude Code hooks while adding enhanced functionality for Qwen-specific workflows.

Dive Deeper

The implementation adds several new components to support the hook system:

1. HookManager - Central registry that manages different hook types and executes them in priority order
2. HookService - Service layer that integrates hooks with the configuration system
3. HookSettings - Type definitions for hook configuration supporting both Qwen native and Claude-compatible hooks
4. ToolNameMapper - Handles mapping between Claude Code and Qwen Code tool names
5. ToolInputFormatMapper - Maps Qwen tool input formats to Claude-compatible formats
6. PayloadConverter - Converts between Qwen and Claude payload formats for compatibility
7. HookExecutor - Executes both external scripts and inline hook functions
8. HookConfigLoader - Loads configuration mappings for events, tool names, and input formats

The system supports two types of hooks:

• Qwen native hooks (scriptPath, inlineScript)
• Claude-compatible hooks (with event mapping via claudeHooks configuration)

Security measures are maintained with path validation ensuring hooks run within the project directory, and configuration validation prevents insecure execution.

The Claude compatibility layer allows executing external commands that receive JSON payloads and can return responses that influence the Qwen workflow, including tool usage permissions and input modifications.

Reviewer Test Plan

1. Check out the branch and run npm run build to ensure the project builds correctly
2. Review the new hook system by examining the new files in packages/core/src/hooks/
3. Test hook execution by creating a simple hook configuration in .qwen/settings.json:

   {
     "hooks": {
       "enabled": true,
       "hooks": [
         {
           "type": "session.start",
           "inlineScript": "console.log('Hook executed with payload:', payload);"
         }
       ]
     }
   }

4. Run the hook tests with npx vitest run packages/core/src/hooks/ to ensure all tests pass
5. Verify the README documentation accurately describes the new functionality
6. Test Claude-compatible hooks by configuring claudeHooks in settings.json and running external scripts
7. Review the new documentation files in docs/features/ to understand the hook system capabilities

Testing Matrix

	🍏	🪟	🐧
npm run	✅	❓	✅
npx	✅	❓	✅
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Successfully tested on Linux and MacOS (build and test execution). All tests pass including the comprehensive new hook-specific tests.

Linked issues / bugs

Resolves the need for a comprehensive hook system to enable custom automation and integration in Qwen Code, including Claude Code compatibility for easy workflow migration!

Additional Features

The PR also includes implementation and documentation for other important Claude-compatible features:

• Claude Compatibility Mode with qwen-alt CLI alias that supports Claude-style commands and arguments
• System Prompt Customization using --append-system-prompt argument
• Streaming JSON Output mode with --output-format stream-json for real-time processing of responses
• Full compatibility with Claude Code workflows and hook systems

[Mingholy]

Thanks for the contribution!
We do have a PR #926 that provides stream-json output and sets up a basic control system for input-format=stream-json, which is prepared for potential SDK use. We're going to build more things based on that.
We will build a hook system similar to Claude-code, but will not immediately eliminate the differences in tools/settings.
Furthermore, we need to consider that hooks must meet two common requirements: configuration via settings.json, or via control protocol (used by the SDK).

We appreciate your ideas and feedback and will try to implement them as soon as we can, but this PR will not be merged for the time being.