fix(copilot): activate project plugin hooks

[christso]

Summary

Project-scoped Copilot plugin installs now activate declared hooks instead of only copying their scripts. AllAgents materializes plugin hooks.json / hooks/hooks.json declarations into one owned .github/hooks/allagents.json, binds each entry to its plugin-specific COPILOT_PLUGIN_ROOT, and reconciles multiple plugins without touching sibling user hook files.

File-mode project overlays also omit package-only .github/plugin/ metadata. Plugin exclusions remain authoritative: an excluded declaration or hook payload is not activated through the generated file.

Hook translation is independent of marketplace registration and package metadata. Direct local and GitHub plugin sources do not require a marketplace manifest or plugin.json. A missing declaration—or a declaration with disableAllHooks: true—adds no managed entries while the plugin's other eligible artifacts continue syncing.

AllAgents warns and omits a hook declaration that cannot be read or parsed as JSON or lacks the version-1 hooks object envelope. Unless the declaration is disabled, a non-array event value also warns and omits that declaration as a unit. This does not reject the plugin or suppress valid declarations from other plugins. The exact ownership, validation, exclusion, and compatibility boundaries are recorded in docs/decisions/0001-project-plugin-hooks.md.

This closes the gap between Copilot's two discovery modes: installed native plugins load declarations from the plugin directory, while repositories load .github/hooks/*.json. See the GitHub Copilot hooks reference.

WTG.AI.Prompts validation

Validated against WiseTechGlobal/WTG.AI.Prompts commit 6f36ea718dcb using the built CLI:

WORKTREE=/home/entity/projects/EntityProcess/allagents.worktrees/fix-copilot-project-hooks
CLI="$WORKTREE/dist/index.js"
WTG=/tmp/allagents-wtg-hook-fix.4b9Xwu/WTG.AI.Prompts
PROJECT=/tmp/allagents-wtg-e2e.JWJpDm

cd "$WORKTREE"
bun run build

cd "$PROJECT"
git init
"$CLI" init . --client copilot
"$CLI" plugin marketplace add "$WTG" --scope project
"$CLI" plugin install org@wtg-ai-prompts --scope project
"$CLI" plugin install skill-usage-metrics@wtg-ai-prompts --scope project

The generated file contained six entries across five event types: two SessionStart entries plus UserPromptSubmit, PostToolUse, PostToolUseFailure, and SessionEnd. Both plugin roots were present, .github/plugin/plugin.json was absent, and sync state owned .github/hooks/allagents.json.

Reconciliation was exercised with:

cd "$PROJECT"
"$CLI" plugin uninstall org@wtg-ai-prompts --scope project
"$CLI" plugin install org@wtg-ai-prompts --scope project
"$CLI" update --offline

Uninstall removed only org entries and preserved skill-usage metrics. Reinstall restored both roots and all six entries. Offline workspace update regenerated the same hook file.

Live execution used Copilot CLI 1.0.70 with an isolated home and instrumented bash / pwsh wrappers:

cd "$PROJECT"
HOME="$PROJECT/isolated-home" \
COPILOT_HOME="$PROJECT/copilot-home" \
PATH="$PROJECT/harness-bin:$PATH" \
WTG_HOOK_MARKER="$PROJECT/hook-invocations.log" \
NO_COLOR=1 \
copilot --log-level debug --log-dir "$PROJECT/logs4"

Copilot displayed Loading: 8 hooks and attributed UserPromptSubmit to .github/hooks/allagents.json. WTG's org/hooks/emit-advisory.sh and org/hooks/resolve-context.sh executed. The expected org and skill-usage-metrics PowerShell command paths were resolved and invoked; the host has no pwsh, so a shim recorded those invocations rather than executing the PowerShell bodies.

Compatibility regression coverage

The regression tests now explicitly verify both boundaries discussed in review:

• A direct, manifest-less plugin with no hook declaration still installs its skill, emits no Copilot-hook warning, and creates no managed aggregate.
• A plugin whose enabled declaration has a non-array event contributes no managed hook entries, but its skill still syncs and a valid second plugin still contributes hooks.

Automated validation

bun test tests/unit/core/copilot-hooks.test.ts tests/unit/core/github-content.test.ts tests/unit/core/transform-glob.test.ts
bun test
bun run test:e2e
bun run typecheck
bun run lint
bun run build
bun run docs:build

• Focused final pass: 43 passed, 0 failed.
• Full final suite: 1,356 passed, 5 skipped, 0 failed.
• Dedicated E2E suite: 117 passed, 4 skipped.
• Documentation build: 13 pages built successfully.
• Independent review corrected the ownership, disabled-declaration, and COPILOT_PLUGIN_ROOT wording; the final documentation now matches runtime behavior.

Related follow-up

Project-scoped plugin update lookup is intentionally outside this hook PR and is fixed separately by the still-open, green #446. User/global marketplace update behavior was already unaffected. Until #446 merges, dedicated project-scoped plugin update can still report Marketplace not found; install, uninstall, reinstall, and update --offline validation for this PR passed.

Related: WiseTechGlobal/mcp-ediprod#467, #442, #443

Post-Deploy Monitoring & Validation

During the first release window, exercise a project-scoped WTG install and search CLI output for Copilot hooks: warnings. Healthy signals are an owned .github/hooks/allagents.json, the expected plugin roots/events, and Copilot reporting the loaded hooks. Missing generated state, an ownership warning on a fresh workspace, or absent WTG hook invocations is the rollback trigger; revert this PR while preserving user-owned hook files. Validation window: first release candidate and first downstream WTG install. Owner: AllAgents maintainer.

---

[cloudflare-workers-and-pages]

Deploying allagents with    Cloudflare Pages

Latest commit:	298d285
Status:	✅  Deploy successful!
Preview URL:	https://016cca5e.allagents.pages.dev
Branch Preview URL:	https://fix-copilot-project-hooks.allagents.pages.dev

View logs