You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds comprehensive documentation for the Qwen Code hooks system, including lifecycle diagram, event reference, configuration examples, and best practices. Also fixes JSON schema definitions for hook events in settings.
Screenshots / Video Demo
Before:
After:
Dive Deeper
New hooks documentation (docs/users/features/hooks.md):
- Overview of the hook system architecture
- Complete reference for all 12 hook events with input/output schemas
- Matcher pattern syntax and support matrix
- Execution model (parallel vs sequential)
- Security model and exit codes
- Best practices with working examples (bash and Python)
- Troubleshooting guide
Hook lifecycle diagram (hook-lifecyclue.png): Visual representation of when hooks fire during a session
Schema fixes (settingsSchema.ts): Adds HOOK_DEFINITION_ITEMS to Notification, PreToolUse, PostToolUse,
PostToolUseFailure, and SessionStart event definitions
VS Code schema sync: Updates settings.schema.json to match
Reviewer Test Plan
Review the documentation for accuracy and completeness
Verify the lifecycle diagram renders correctly
Test hook configuration in VS Code with the updated schema:
This PR adds comprehensive documentation for the Qwen Code hooks feature and updates the JSON schema to properly define hook configuration structures. The documentation is thorough and well-organized, covering all hook events, input/output structures, and practical examples. The schema changes correctly update the VSCode settings schema from simple string arrays to proper object structures with matchers and hook configurations.
🔍 General Feedback
Excellent documentation quality: The hooks.md file is comprehensive, well-structured, and includes practical examples that will help users understand and implement hooks effectively
Good schema consistency: The JSON schema updates in settings.schema.json properly mirror the TypeScript schema changes in settingsSchema.ts
Comprehensive coverage: All 11 hook events are documented with specific input/output structures
Minor typo in asset filename: hook-lifecyclue.png appears to have a typo (should be hook-lifecycle.png)
Large documentation file: At 707 lines, the hooks.md file is quite comprehensive but may benefit from some organizational improvements
🎯 Specific Feedback
🟡 High
File: docs/users/features/hooks.md:1 - The filename contains a typo: "hook-lifecyclue.png" should be "hook-lifecycle.png". This affects both the image filename and the reference in the markdown. Recommend renaming the file to fix the typo for professionalism and consistency.
🟢 Medium
File: docs/users/features/hooks.md:28-38 - The hook events table has inconsistent column widths and some use cases could be more specific. Consider adding a "Supported Matchers" column to the table to give users a quick reference without needing to scroll to the matcher patterns section.
File: docs/users/features/hooks.md:62-68 - The PreToolUse output example shows hookSpecificOutput.permissionDecision as REQUIRED, but this pattern isn't consistently documented across all event types. Consider creating a clear table or section that explicitly states which fields are required vs optional for each event type.
File: packages/vscode-ide-companion/schemas/settings.schema.json:796-1583 - The schema has significant duplication (same structure repeated 10 times for each hook event type). While this is valid JSON Schema, consider if there's a way to use $defs to define the hook configuration structure once and reference it, which would reduce maintenance burden and ensure consistency.
🔵 Low
File: docs/users/features/hooks.md:1 - Consider adding a "Quick Start" section at the beginning with a minimal working example. Users often want to see a simple working configuration before diving into the detailed documentation.
File: docs/users/features/hooks.md:44-50 - The common fields section mentions timestamp as a field, but it would be helpful to specify the format (ISO 8601, Unix timestamp, etc.).
File: docs/users/features/hooks.md:127-132 - The PostToolUse output shows a decision field with "allow", "deny", "block" options, but it's unclear when "block" should be used vs "deny". Consider clarifying the distinction between these decision types.
File: docs/users/features/hooks.md:686-707 - The troubleshooting section is quite brief. Consider expanding with common error scenarios and their solutions, such as:
Hook timeout issues
JSON parsing errors
Permission issues with hook scripts
Debug mode for testing hooks
File: docs/users/features/_meta.ts:16 - The navigation entry is added correctly, but consider whether the hooks documentation should be grouped with related features (e.g., under a "Customization" or "Advanced" section) if more documentation is added in the future.
✅ Highlights
Outstanding documentation examples: The security validation hook (Example 1) and user prompt validation hook (Example 2) are excellent, showing real-world use cases with complete implementations in both bash and Python
Comprehensive event coverage: All 11 hook events are thoroughly documented with specific input structures, output options, and example outputs
Clear matcher documentation: The matcher patterns section with the detailed table showing which events support matchers and what they match against is very helpful
Good exit code documentation: The exit code table clearly explains the behavior for different exit codes (0, 2, and other)
Proper schema updates: The TypeScript settings schema and VSCode JSON schema are properly updated in sync, maintaining consistency across the codebase
Helpful notes throughout: The documentation includes useful callouts and notes (e.g., about elicitation_dialog type not being implemented) that help set correct expectations
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TLDR
Adds comprehensive documentation for the Qwen Code hooks system, including lifecycle diagram, event reference, configuration examples, and best practices. Also fixes JSON schema definitions for hook events in settings.
Screenshots / Video Demo
Before:

After:

Dive Deeper
- Overview of the hook system architecture
- Complete reference for all 12 hook events with input/output schemas
- Matcher pattern syntax and support matrix
- Execution model (parallel vs sequential)
- Security model and exit codes
- Best practices with working examples (bash and Python)
- Troubleshooting guide
PostToolUseFailure, and SessionStart event definitions
Reviewer Test Plan
Testing Matrix
Linked issues / bugs