fix: resolve Claude hooks.json validation error and add telemetry debug logging - #3021
Merged
Tom Meschter (tmeschter) merged 6 commits intoAug 6, 2026
Conversation
Claude additively loads the default hooks/hooks.json regardless of the manifest's hooks path, so the Copilot-format file there failed 'claude plugin validate'. Rename it to hooks/copilot-hooks.json and reference it explicitly from .plugin/plugin.json (Copilot/VS Code). Nothing now sits at the shared default path, so each client uses its own hooks file. Addresses the hooks portion of microsoft#2957; the unpinned npx launcher is handled separately. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7ace74d0-93aa-4f8c-a9ef-0a928b7d50ad
Add opt-in debugging to the telemetry hook scripts, controlled by the AZURE_SKILLS_TELEMETRY_LOG_DIR env var: raw JSON inputs are written to a raw-input/ subdirectory and MCP args are appended to telemetry.log. Also honor AZURE_SKILLS_PLUGIN_ROOT so skills loaded via --plugin-dir are recognized for reference_file_read events, and generalize reference-path extraction to match any skills/ root. Applied symmetrically to track-telemetry.ps1 and track-telemetry.sh. Related to microsoft#2957 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7ace74d0-93aa-4f8c-a9ef-0a928b7d50ad
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Azure plugin hook configuration to avoid cross-client hooks.json validation conflicts (notably for Claude) and enhances hook telemetry scripts with opt-in debug logging plus improved local-plugin path detection.
Changes:
- Explicitly configures Copilot hooks via
plugin/.plugin/plugin.json→./hooks/copilot-hooks.jsonand updates the README client support matrix accordingly. - Adds opt-in telemetry debugging (
AZURE_SKILLS_TELEMETRY_LOG_DIR) to persist raw hook inputs and append MCP args to a log file. - Improves skill/reference path recognition for local plugin development via
AZURE_SKILLS_PLUGIN_ROOT, and generalizes reference path extraction to any*/skills/*root.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates the client support matrix to reference the new Copilot hooks file path. |
| plugin/hooks/scripts/track-telemetry.sh | Adds opt-in debug logging and local plugin-root detection for reference-file reads. |
| plugin/hooks/scripts/track-telemetry.ps1 | Mirrors the debug logging + local plugin-root detection changes for PowerShell. |
| plugin/hooks/copilot-hooks.json | Introduces a Copilot-format hooks file used by Copilot clients. |
| plugin/.plugin/plugin.json | Points the plugin manifest at ./hooks/copilot-hooks.json explicitly. |
Review details
- Files reviewed: 4/5 changed files
- Comments generated: 4
- Review effort level: Lite
- Use printf instead of echo for raw-input dumps in track-telemetry.sh so JSON is written losslessly without escape-sequence interpretation. - Use local time (no trailing Z) for the debug log timestamp in both scripts. - Fix a stale comment that referenced AZURE_SKILLS_TELEMETRY_LOG instead of AZURE_SKILLS_TELEMETRY_LOG_DIR. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7ace74d0-93aa-4f8c-a9ef-0a928b7d50ad
…d-fiesta # Conflicts: # hooks/copilot-hooks.json # hooks/hooks.json # plugin/hooks/hooks.json
Member
|
This doc needs to be updated with the new hooks manifest location. https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/docs/hooks.md |
Reflect the rename of the Copilot/VS Code hooks manifest away from the default hooks/hooks.json path and explain why (Claude's additive hooks discovery), per issue microsoft#2957. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7ace74d0-93aa-4f8c-a9ef-0a928b7d50ad
Member
Author
|
Member
|
scripts/src/plugin/bootstrap.ts script also needs to be updated. It currently creates .plugin/plugin.json without an explicit hooks property. |
New plugins scaffolded by bootstrap.ts now set \hooks: ./hooks/copilot-hooks.json\ so no Copilot-format manifest sits at the default hooks/hooks.json path, consistent with issue microsoft#2957. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7ace74d0-93aa-4f8c-a9ef-0a928b7d50ad
Member
Author
JasonYeMSFT (@JasonYeMSFT) I believe I have addressed this. Let me know if it matches your expectations now. |
JasonYeMSFT (JasonYeMSFT)
approved these changes
Aug 6, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
Two plugin/hooks changes, both related to #2957:
1. Resolve Claude
hooks.jsonvalidation errorClaude additively loads the default
hooks/hooks.jsonregardless of thehookspath declared in the manifest, so the Copilot-format file living there failedclaude plugin validate(hooks.PostToolUse.0.hooks: expected array, received undefined).plugin/hooks/hooks.json→plugin/hooks/copilot-hooks.json(content unchanged)..plugin/plugin.jsonvia"hooks": "./hooks/copilot-hooks.json"(the documented Copilot CLI / VS Code / OpenPlugin form).Nothing now sits at the shared default
hooks/hooks.jsonpath, so each client loads only its own hooks file (claude-hooks.json,cursor-hooks.json,copilot-hooks.json).2. Telemetry debug logging + local plugin-root skill detection
Applied symmetrically to
track-telemetry.ps1andtrack-telemetry.sh:AZURE_SKILLS_TELEMETRY_LOG_DIR: raw JSON inputs are written to araw-input/subdirectory, and MCP args are appended totelemetry.log.AZURE_SKILLS_PLUGIN_ROOTso skills loaded via--plugin-dirare recognized forreference_file_readevents.skills/root.Notes
@azure/mcp@latestlauncher (the second item in Directory review: hooks.json fails plugin validation + unpinned npx launcher #2957); that is being handled separately.Related to #2957.