Repository navigation
feat(hooks)!: retire filename hook routing with safe migration - #3613
Daniel Meppiel (danielmeppiel) merged 14 commits into
Conversation
Hook filenames no longer choose install targets. Every discovered hook file reaches every effective target (active targets intersected with dependency targets: and package target:). Packages whose retired filename routing hid files from a target now fail with actionable migration guidance instead of silently widening executable reach, at preflight, direct integration and uninstall reintegration. Claude output renders documented Copilot alias events (subagentStop, sessionEnd, userPromptSubmitted, postToolUseFailure, preCompact) under their Claude names, dedupes equivalent registrations, and fails before changing settings for lower-case events with no Claude equivalent. apm-spec-waiver: req-tg-008 filename inference is an optional MAY; APM stops exercising it, no normative spec change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…3226) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Uninstall can delete a legacy-routed survivor’s working hooks before routing validation, then swallow the migration failure as a warning without marking cleanup incomplete.
1 open issue
What changed in this PR
This PR replaces filename-based hook routing with configuration-led selection in APM, addressing #3226. It adds migration checks to prevent previously excluded hooks from silently reaching new targets and improves Claude event rendering.
Changes:
- Select hook files through configured targets and reject incompatible legacy layouts.
- Normalize additional Claude event aliases and reject unmapped lower-case events.
- Update migration guidance and regression coverage for routing, rendering, and target contraction.
| File | Description |
|---|---|
tests/unit/integration/test_hook_target_deprecation.py |
Replace deprecation-warning expectations with migration failures. |
tests/unit/integration/test_hook_integrator.py |
Update legacy-routing and alias-deduplication regressions. |
tests/unit/integration/test_hook_integrator_issue1892.py |
Verify incompatible multi-target layouts fail closed. |
tests/unit/integration/test_hook_file_routing_combined_stems.py |
Test legacy classification and widening diagnostics. |
tests/unit/integration/test_hook_configured_routing.py |
Add configured-routing and Claude-event regressions. |
tests/unit/integration/test_dep_target_intersection.py |
Assert migration failures across target combinations. |
tests/unit/install/test_security_scan_scope.py |
Verify configured descriptors are scanned and conflicts recorded. |
tests/integration/test_wave6_integrators_coverage.py |
Redirect classifier tests to the legacy helper. |
tests/integration/test_integrators_hooks_phase3c.py |
Update the legacy classifier import. |
tests/integration/test_integrators_hooks_execution.py |
Update the legacy classifier import. |
tests/integration/test_hook_routing_combined_manifest_e2e.py |
Remove obsolete filename-routing scenarios. |
tests/integration/test_hook_configured_routing_e2e.py |
Add in-process migration, reinstall, and target-contraction scenarios. |
src/apm_cli/integration/hook_source_selection.py |
Select configured descriptors and record migration conflicts. |
src/apm_cli/integration/hook_native_formats.py |
Add Claude event validation. |
src/apm_cli/integration/hook_integrator.py |
Extend aliases and invoke routing/event checks. |
src/apm_cli/integration/hook_file_routing.py |
Replace filename routing with a legacy-widening guard. |
packages/apm-guide/.apm/skills/apm-usage/package-authoring.md |
Update packaged routing and migration guidance. |
docs/src/content/docs/producer/author-primitives/hooks-and-commands.md |
Document configured targets, migration, and event aliases. |
CHANGELOG.md |
Record the breaking routing change and Claude fixes. |
Review effort: Balanced
Resolve hook_integrator.py: keep #2944's _DOT_NAMED_HOOK_ROOTS and drop the retired _filter_hook_files_for_target seam (filename routing is removed by this PR). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
apm uninstall wiped APM-owned merged hook settings in Phase 1 and only then rebuilt survivors, so a survivor relying on retired filename routing (or a Claude event without a native pair) lost its working hooks and the HookContractError was swallowed as a best-effort warning. preflight_survivor_hooks (hook_reintegration owner) now runs the shared HookSourceSelection.require_deployable check for every authorized survivor before Phase 1, so settings and sidecars stay byte-identical, the migration message is shown and uninstall exits non-zero. Addresses Copilot inline on src/apm_cli/integration/hook_integrator.py:1993. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Move the entry to Changed under the repo's **BREAKING:** convention (next to the Python 3.11 break shipping in the same release), drop the duplicate Removed header left by the merge, and spell out the migration steps and the uninstall stop. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…eppiel-w2-pr-3613
- preflight_survivor_hooks validates the selection the canonical HookIntegrator.select_deployable_hook_sources returns, reusing the discovered files, instead of building and scanning a full source plan that the rebuild builds again (performance-expert FU). - legacy_routing_widening reuses the configured descriptors instead of recomputing them per target (performance-expert nit). - Claude event refusals name the package and say 'no documented Claude Code name' (SubagentStart exists in Claude; subagentStart lacks a documented alias) (devx-ux-expert, doc-writer FUs). - Uninstall tells the user to migrate before 'apm install' when the survivor preflight refused (devx-ux-expert FU); grammar fix in the routing refusal text; layering comments (python-architect nit). - test_hook_configured_routing.py declares pytestmark component. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- reconcile_after_removal refuses a legacy-routed or invalid-event survivor before wiping (mutation-break verified). - Real-binary lifecycle: configured-target packages install, repeat idempotently, audit clean, a legacy-routed package is refused with no write, and uninstall of one package leaves the other's hooks (test-coverage-expert FUs). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Narrowing a dependency with targets: only resolves the refusal when the package ships hooks for that one target; a generic hooks.json beside target files needs the author to split the package. Docs, apm-guide and CHANGELOG now separate the author and consumer paths, say the refused package writes nothing, mention the uninstall stop in the guide, and describe refused events as lacking a documented Claude alias (doc-writer FUs). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 2 | Selection authority stays in HookSourceSelection; the uninstall preflight extends it without splitting authority; all write paths guarded. |
| Test Coverage Expert | 0 | 2 | 1 | Regression traps cover install preflight, aliases, invalid events and uninstall byte-identity; reconcile and lifecycle gaps now folded. |
| Doc Writer | 0 | 2 | 1 | Migration docs follow the configuration-only model; narrowing path and alias wording corrected. |
| DevX UX Expert | 0 | 1 | 2 | Uninstall recovery advice now says migrate first; refusals name the package. |
| Supply Chain Security Expert | 0 | 0 | 0 | Every hook deployment path enforces configured routing; widening is detected per effective target after narrowing. Ship. |
| Performance Expert | 0 | 1 | 2 | Survivor preflight now uses the hook selector only; cost bounded to hook-carrying survivors. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 1 follow-ups
- [Python Architect] Extract
_HOOK_EVENT_MAPand the alias tables fromhook_integrator.pyinto a shared module to regain headroom below the 2100-line CI guard (currently 2093). -- Mechanical refactor; land it before the next hooks-touching PR (for example feat(hooks): stage consent-aware Claude standalone inline hooks #3332) to avoid a guard breach.
Architecture
classDiagram
direction LR
class HookSourceSelection {
<<ValueObject>>
+descriptor_files dict
+bundle_files dict
+legacy_routing_conflicts dict
+require_configured_routing(label) void
+require_deployable(pkg_info, event_maps) void
}
class DeployableSourcePlan {
<<ValueObject>>
+hook_source_selection HookSourceSelection
+create() DeployableSourcePlan
+scan_security(policy) SecurityVerdict
}
class HookIntegrator {
+select_deployable_hook_sources() HookSourceSelection
+select_hook_sources_for_target() HookSourceSelection
+preflight_hooks_for_targets() void
+integrate_hooks_for_target() IntegrationResult
+reconcile_after_removal() dict
}
class HookFileRouting {
<<MigrationGuard>>
+configured_hook_file_selection() list
+legacy_routing_widening() list
+raise_for_legacy_routing() void
}
class HookNativeFormats {
+require_claude_native_events() void
}
class HookReintegration {
<<Preflight>>
+build_hook_reintegration_source_plan() DeployableSourcePlan
+preflight_survivor_hooks() void
}
HookIntegrator ..> HookSourceSelection : selects and checks
DeployableSourcePlan *-- HookSourceSelection : carries
HookSourceSelection ..> HookFileRouting : routing check
HookSourceSelection ..> HookNativeFormats : Claude event check
HookReintegration ..> HookIntegrator : canonical selector
HookReintegration ..> HookSourceSelection : require_deployable
class HookSourceSelection:::touched
class HookFileRouting:::touched
class HookNativeFormats:::touched
class HookReintegration:::touched
class HookIntegrator:::touched
classDef touched fill:#fff3b0,stroke:#d47600
Recommendation
All six panelists converged with no blocking-severity findings and no open recommended findings after the folds. 705 targeted tests, a real-binary lifecycle case, a clean lint mirror and mutation-break checks confirm that the fail-closed contract holds. The CHANGELOG BREAKING entry and the migration docs are in place. Ship in 0.36.0 with this PR, and track the hook_integrator.py extraction as a hygiene task before the next hooks-touching PR.
Folded in this run
- (copilot) Uninstall wiped survivor hooks before the routing/event check, then swallowed the refusal -- resolved in 38dbb05 (
preflight_survivor_hooksruns before Phase 1; exit 1, settings byte-identical). - (merge) Conflict with fix(hooks): anchor POSIX user-scope hook commands to $HOME #2944 in
hook_integrator.py; kept_DOT_NAMED_HOOK_ROOTSand dropped the retired filter seam -- resolved in 5166113. - (release) CHANGELOG moved to
**BREAKING:**under Changed with explicit migration steps (0.36.0 alongside the Python 3.11 break) -- resolved in 54d3163. - (performance-expert) Survivor preflight validates through the canonical hook selector instead of building and scanning a full plan; hook files discovered once; configured selection reused across targets -- resolved in cb29cff.
- (devx-ux-expert) Migrate-first advice when the survivor preflight refuses; package label on Claude event refusals; grammar in the routing refusal -- resolved in cb29cff.
- (python-architect) Comments documenting the selection / preflight / write-boundary check layering -- resolved in cb29cff.
- (test-coverage-expert)
reconcile_after_removalrefusal trap; real-binary lifecycle casetest_required_configured_hook_routing_lifecycle; modulepytestmark = pytest.mark.component-- resolved in 2e72d49 and cb29cff. - (doc-writer) Separate author and consumer migration paths (narrowing only helps single-target packages); "no documented Claude alias" wording; uninstall stop in the guide; "writes nothing from it" -- resolved in 1548ede and cb29cff.
Copilot signals reviewed
src/apm_cli/integration/hook_integrator.py:1993-- LEGIT: uninstall Phase 1 wiped merged hooks before the survivor rebuild hit the routing guard, losing working hooks silently (resolved in 38dbb05; thread resolved).
Regression-trap evidence (mutation-break gate)
tests/unit/test_surviving_deps_reintegration.py::test_uninstall_rejects_undeployable_survivor_hooks_before_wiping-- deletedpreflight_survivor_hooks(...)call inengine.py(and, separately, its.require_deployable(...)); test FAILED as expected; guard restored.tests/unit/test_surviving_deps_reintegration.py::test_reconcile_after_removal_refuses_undeployable_survivor_before_wiping-- deletedrequire_deployableinreconcile_after_removal; test FAILED as expected; guard restored.
Lint contract
The full CI lint mirror is silent on the merged head: ruff check, ruff format --check, pylint R0801 (10.00/10), lint-auth-signals.sh and lint-architecture-boundaries.sh. The file-length, YAML-IO and relative_to guards are clean too.
CI
All checks green at 1548ede9 (23 success, 2 neutral, 1 skipped; license/cla success) after 0 CI fix iterations.
Mergeability status
| PR | head SHA | CEO stance | iters | folds | defers | Copilot rounds | CI | mergeable | mergeStateStatus | notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #3613 | 1548ede |
ship_now | 1 | 8 | 0 | 1 | green | MERGEABLE | BLOCKED | pending required review |
Convergence
1 outer iteration; 1 Copilot round. Final panel stance: ship_now. Ready for maintainer review.
This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
…outing Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Avoids landing-order conflicts with other queued PRs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Lane L: main merged for landing
This comment was generated by an AI agent (Lane L landing desk) on behalf of Daniel Meppiel (@danielmeppiel). |

TL;DR
Hook filenames no longer choose install targets. Every hook file in a package now reaches every target allowed by
apm.yml(the active targets, narrowed by the dependency'stargets:and the package'starget:). Packages whose old filenames kept a hook file from a target now fail with migration guidance instead of quietly giving that target more executable hooks. Claude output now renames documented Copilot alias events (e.g.subagentStop→SubagentStop) and refuses lower-case events Claude does not support before changing.claude/settings.json.Fixes #3226
Important
Breaking (pre-1.0, minor-bump class). Packages that used
*-<target>-hooks.json/hooks-<target>.jsonto send different files to different targets now fail with an actionable error naming the target and files. The CHANGELOGRemovedentry and the docs section "Migrating from filename routing" give the migration steps. No removal release or date is promised here; the maintainer chooses the release and notice window.Description
Issue and approved scope
Issue: Fixes #3226
Human scope-approval comment: #3226 (comment) (
apm-scope:v1, approver and review contact Daniel Meppiel (@danielmeppiel)). On 2026-11-12, Daniel Meppiel (@danielmeppiel) confirmed again that this is a bounded Tier1 accept. The trusted-maineligibility.cjsreturnedrecord-presentwithauthorizes_implementation: false.Does this complete the issue? Yes, for the accepted scope. Filename inference is removed from the single hook selection owner that every consumer uses, and the migration fails closed. The demonstrated Claude/Copilot event-rendering defect is repaired. Out of scope, per the record: per-file or per-event selectors, general event translation, and spec ratification.
Note
Adjacent work. Draft PR #3332 (#3227, inline hook consent) also edits
hook_integrator.py,hook_source_selection.py,hooks-and-commands.mdandpackage-authoring.md. Here the overlap is limited to the selection owner, preflight and the alias table; #3332 is not modified. PR #3600 only sharesCHANGELOG.md.Local preflight skipped by maintainer instruction (2026-11-12); CI is the gate.
Problem (WHY)
mainat3b1ab4d: a hooks file declaring bothSubagentStopandsubagentStopproduced{'SubagentStop': 1, 'subagentStop': 1, ...}in.claude/settings.json. Claude Code rejectssubagentStopas an unknown event.x-claude-hooks.jsonmade Claude skip a generichooks.json(claude: ['x-claude-hooks.json'] copilot: ['hooks.json']). The reporter's spelling,checks.claude.json, was ignored, so the behaviour depended on a naming convention nobody could discover.Why these matter: the accepted record requires that "formerly excluded or shadowed scripts cannot silently gain executable reach, and incompatible legacy reliance produces actionable migration failure rather than guessed targets or silent loss of protection" (#3226 scope).
Approach (WHAT)
apm.ymlonly.HookContractErrorwith migration steps at install preflight (before any primitive write), direct per-target integration, and uninstall reintegration (before its destructive wipe).subagentStop,sessionEnd,userPromptSubmitted,postToolUseFailure,preCompact.errorOccurred,subagentStart,stop) fail before.claude/settings.jsonchanges. Existing content dedupe collapses equivalent registrations; distinct matchers stay distinct.Implementation (HOW)
integration/hook_file_routing.py-- rewritten from a router into a migration guard:configured_hook_file_selection,legacy_routing_widening,raise_for_legacy_routing,hook_package_label. Deprecation and "unresolved token" warnings are removed, because filenames no longer mean anything.integration/hook_source_selection.py(single selection owner) -- drops thefilter_hook_filesseam.HookSourceSelectiongainslegacy_routing_conflictsplusrequire_configured_routing()/require_deployable().integration/hook_integrator.py-- the Claude alias map; guard calls inselect_hook_sources_for_target,preflight_hooks_for_targets, Claude merge and reintegration. Net −10 lines, now 2090 against the 2100 guardrail.integration/hook_native_formats.py(rendering owner) --require_claude_native_events.hooks-and-commands.mdandapm-usage/package-authoring.mdget the configuration-only model, a "Migrating from filename routing" section and the extended alias table.test_hook_configured_routing.py(unit) andtest_hook_configured_routing_e2e.py(lifecycle; replaces the ponytail combined-manifest e2e). Legacy-routing assertions are rewritten to the fail-closed contract; pure classifier tests now importlegacy_hook_file_selection.Diagrams
Legend: the selection owner records widening once, and every write path that could deploy hooks checks it before writing.
flowchart LR SP["DeployableSourcePlan.create"] --> SEL["select_hook_sources"] SEL --> CFG["every descriptor per target"] SEL --> LEG["legacy_routing_widening"] LEG --> CONF["legacy_routing_conflicts"] CONF --> PRE["preflight_hooks_for_targets"] CONF --> DIR["select_hook_sources_for_target"] CONF --> REI["uninstall reintegration"] PRE -->|"conflict"| ERR["HookContractError: no hook write"] DIR -->|"conflict"| ERR REI -->|"conflict, before wipe"| ERR PRE -->|"clean"| CL["require_claude_native_events"] CL -->|"lower-case event"| ERR CL -->|"ok"| W["render and write targets"]Trade-offs
target:are not churned.apm-spec-waiver:).Benefits
.claude/settings.jsonno longer receivessubagentStop-style Copilot events; the reported manifest yields{'SubagentStop': 1, 'PreToolUse': 2}.apm.yml) for install, preflight, replay, reintegration and audit drift, all throughHookSourceSelection.Validation
Repro before / after (direct integrator script)
Targeted tests (no xdist, one process at a time)
Lint mirror (after merging origin/main)
Full unit, integration and spec suites were not run locally (maintainer directive); CI is the authority.
Scenario evidence
target:narrowstest_generic_hook_file_reaches_every_effective_target,test_package_target_declaration_limits_generic_hookstest_target_word_in_filename_no_longer_alters_destination,test_reporter_dot_suffix_name_is_an_ordinary_generic_filetest_legacy_reliance_fails_before_any_hook_write[*],test_legacy_filename_layout_fails_before_any_hook_write[*]test_documented_copilot_aliases_render_claude_events[*],test_copilot_events_render_as_claude_events_without_duplicatestest_event_without_claude_equivalent_fails_before_settings_change[*],test_copilot_only_event_still_installs_for_copilottest_migrated_packages_follow_their_configured_targets,test_consumer_target_contraction_retires_the_dropped_targetType of change
Testing
Spec conformance (OpenAPM v0.1)
CONFORMANCE.{md,json}regeneratedHow to test
hooks/hooks.jsondeclaringSubagentStop+subagentStopwith the same command →apm install --target claudewrites oneSubagentStopentry.hooks/x-claude-hooks.jsonbesidehooks.json→ install fails withTarget 'claude' would newly activate: hooks/hooks.json;.claude/settings.jsonis unchanged.target: claude/target: copilot→ each target receives only its package's hooks.errorOccurredwith--target claude→ fails withno Claude Code equivalent; withtargets: [copilot]it installs.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com