feat: target-aware hook event diagnostics

[danielmeppiel]

Summary

When APM deploys hooks for a package, it should log which hook event names were found and note if they may not be recognized by the target platform. Currently APM silently deploys all events regardless of target.

Background

The hooks specification has no unified standard — three implementations exist with divergent event names and schemas:

Platform	Event naming	Example events	Spec reference
GitHub Copilot Agent (cloud/CLI)	camelCase	sessionStart, preToolUse, postToolUse, userPromptSubmitted	docs.github.com
VS Code (Copilot Chat extension)	PascalCase	SessionStart, PreToolUse, PostToolUse, UserPromptSubmit	code.visualstudio.com
Claude Code	PascalCase	SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, PermissionRequest, FileChanged	code.claude.com

Additionally, each platform supports different events — Claude Code has 25+ events, while GH Agent has 8.

Proposed Behavior

When deploying hooks to a target (e.g., copilot, claude, cursor, codex):

1. Log the event names found in the hook JSON (e.g., "Deployed 3 hook events: preToolUse, postToolUse, sessionStart")
2. Optionally note if events use a naming convention that may not match the target (e.g., "Note: camelCase events detected — these are GitHub Copilot Agent format; VS Code expects PascalCase")

Scope

• Informational only — do NOT block deployment
• Emit via existing logger.info or diagnostics mechanism
• Consider a future --strict mode that warns on unrecognized events per target

Related

• Issue Bug: Hook integrator does not process 'windows' property – scripts not copied and paths not rewritten #520 — original hooks bug (missing windows key)
• The hook command keys (command, bash, powershell, windows, linux, osx) are already handled as a superset; this issue addresses the event name dimension

[github-actions]

Triage decision

accept

Proposed labels

area/cli
type/feature
status/accepted

Milestone

0.9.4

Suggested next action

Add a per-target lookup table of known hook event names to the hook integrator and emit a [!] warning when a deployed event name is not in the target's known set.

Suggested issue comment

Good call -- silent deployment of unrecognized hook events is exactly the kind of quiet failure that wastes debugging time.

The fix is well-scoped: a per-target lookup table of known hook event names (e.g., VS Code's `onSave`, `onFileCreate`; Claude's equivalents) in the hook integrator, with a `[!]` warning when an event name is not on the target's known list and an `[i]` confirmation when it is recognized.

A few implementation notes:

- The lookup table should live close to the existing target definitions so it's easy to update as targets evolve their hook specs.
- The warning should name the event, the target, and a pointer to the target's hook documentation (or a note that the spec is not yet published).
- "Not recognized" is a warning, not an error -- APM should still deploy the hook file; the diagnostic is advisory.

If you want to take this on, the hook integrator is the right place to start. Happy to review a PR.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is "know whether my hook events will work for my target before something breaks in production." Currently APM is silent; the fix surfaces a [!] warning at deploy time. This directly satisfies the "failure mode is the product" principle. The proposed behavior (warn on unknown, info on recognized) is proportionate and non-blocking. No new command surface needed.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. Hook event names are string metadata from package files; logging them does not create a security surface. No theme/security required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is the maintainer; no tone-tuning needed.

Python Architect -- Architecture Reviewer

Not activated -- this is a bounded addition to the hook integrator's validation logic: a lookup table (dict[str, set[str]]) keyed by target name, consulted after hook file discovery. No cross-cutting design change required. The DiagnosticCollector is already wired to the hook integrator; the warning slots in naturally.

Doc Writer -- Documentation Reviewer

Not activated -- this is a diagnostic output improvement. The hooks guide may warrant a brief note about target-specific event name support, but no new doc pages are needed. The implementing PR should add a sentence to the hooks reference once the known-events list is established.

APM CEO -- Triage Arbiter

Well-scoped DX improvement that closes a silent-failure gap in the hook integration flow. Pure area/cli infra -- no product-surface implication beyond improving diagnostics. Accept for 0.9.4; no priority label needed. This is straightforward enough that it could be a good first issue if the maintainer does not pick it up quickly.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Add a per-target lookup table of known hook event names to the hook integrator and emit a [!] warning when a deployed event name is not in the target's known set.",
  "comment_markdown": "Good call -- silent deployment of unrecognized hook events is exactly the kind of quiet failure that wastes debugging time.\n\nThe fix is well-scoped: a per-target lookup table of known hook event names (e.g., VS Code's `onSave`, `onFileCreate`; Claude's equivalents) in the hook integrator, with a `[!]` warning when an event name is not on the target's known list and an `[i]` confirmation when it is recognized.\n\nA few implementation notes:\n\n- The lookup table should live close to the existing target definitions so it's easy to update as targets evolve their hook specs.\n- The warning should name the event, the target, and a pointer to the target's hook documentation (or a note that the spec is not yet published).\n- \"Not recognized\" is a warning, not an error -- APM should still deploy the hook file; the diagnostic is advisory.\n\nIf you want to take this on, the hook integrator is the right place to start. Happy to review a PR."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.9M · ◷